34

Suppose I have a README.md file in a github repository. I am then making a website all about this repository that I will host using gh-pages.

What I want is to have a section of my index.html file that gets its content from my README.md file. This way, only one file needs to be updated.

I imagine that the markdown file will first need to be converted to html, and that html can then be put into another html file.

I have looked into HTML5 Imports, but they are only currently supported in Chrome. Using a separate .js file with document.write() could be useful, but is there a simple, clean way?

Improve this question
5
  • 1
    You can use XMLHttpRequest and innerHTML function or if you're using jQuery, you can use load function. stackoverflow.com/questions/17636528/… Commented Jun 12, 2016 at 4:08
  • 1
    I'd go with running jekyll locally.... it's what gh-pages does on their end as well. but by running locally you can include plugins etc. that does what you want... Commented Jun 13, 2016 at 12:59
  • @mb21 You should submit a detailed answer using jekyll, as you suggested. The detailed Node.js solution by @gliemezis posted below looks good. It uses the marked NPM package. Commented Feb 13, 2017 at 16:05
  • 1
    Here is a solution that uses jekyll: stackoverflow.com/questions/15214762/… Commented Feb 13, 2017 at 16:33
  • 1
    There's always Pandoc Commented Mar 20, 2021 at 22:13

4 Answers 4

Reset to default
57

I am using <zero-md> web component.

<!-- Lightweight client-side loader that feature-detects and load polyfills only when necessary -->
<script src="https://cdn.jsdelivr.net/npm/@webcomponents/webcomponentsjs@2/webcomponents-loader.min.js"></script>

<!-- Load the element definition -->
<script type="module" src="https://cdn.jsdelivr.net/gh/zerodevx/zero-md@1/src/zero-md.min.js"></script>

<!-- Simply set the `src` attribute to your MD file and win -->
<zero-md src="README.md"></zero-md>
Improve this answer
Sign up to request clarification or add additional context in comments.

3 Comments

this should be the accepted answer - so elegant and easy
An off-topic question - how could one include themes in an HTML file to format the markdown?
@amzon-ex use CSS inside <style></style> in the HTML
18

My complete answer using Node.js

1. First install the marked markdown converter:

$ npm install --save-dev marked


2. Then in a new file called generateReadMe.js, compile the markdown to HTML and write it to a new README.html file:

var marked = require('marked');
var fs = require('fs');

var readMe = fs.readFileSync('README.md', 'utf-8');
var markdownReadMe = marked(readMe);

fs.writeFileSync('./site/README.html', markdownReadMe);


3. Then inside the index.html where the README.md content is wanted, add an <object> tag:

<object data="README.html" type="text/html"></object>


4. Then run this on the command line to make it happen:

$ node path/to/generateReadMe.js


The whole process was pretty simple and painless. I added the whole thing to my npm start script. Now any time I make a change to my README.md file, the changes will register on my gh-pages website.

Improve this answer

4 Comments

I found several issues with this marked conversion, including but not limited to, making all the internal links useless. Unlike the Git Markdown method, which adds the following anchor to header tags <a id="user-content-header-title" class="anchor" href="#header-title" aria-hidden="true">, this conversion only adds an id to the header <h3 id="header-name">. This was really troublesome for me. I'm sure I'm not alone in this assessment of the situation with this method. I suggest taking a look here.
I see. Steps 1, 2, and 4 of this solution could be replaced with appropriate changes for using ruby and GitHub's markup, or any other tools to convert a .md file to HTML. Step 3 is the important piece of the answer to this specific question.
how can you do it without using npm?
@moctarjallo as mentioned above, you could replace steps 1, 2, and 4 of this answer with whatever other tool/language you want. Mainly just need something to convert the markdown to html, then you can use the <object> tag the same way.
6

You could use a markdown parser such as https://github.com/markdown-it/markdown-it to convert the markdown to html.

You could either convert the markdown on the server and merge it into the HTML delivered to the client, or use it to load the markdown in the browser and convert it there.

Improve this answer

1 Comment

I think this is another Node.js solution (via the NPM package manager). The accepted answer is better because it has detailed steps.
4

To convert markdown to html, you can use a conversion library or a command tool. For an example using the Ruby language, visit: https://github.com/github/markup.

Try searching for an appropriate conversion library or command tool for your implementation by visiting: https://www.npmjs.com/search?q=markup. The accepted answer above is an example using the NPM package manager for Node.js.

Improve this answer

1 Comment

Another option is jekyll: stackoverflow.com/questions/15214762/….

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.