How to include markdown (.md) files inside html files

Question

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?

Solution 1

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>

Solution 2

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.

Solution 3

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.

Solution 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.

View more solutions

Comments

[Jose Hermosilla Rodrigo]

You can use XMLHttpRequest and innerHTML function or if you're using jQuery, you can use load function. stackoverflow.com/questions/17636528/…

[mb21]

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...

[jmcmahon443]

@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.

[jmcmahon443]

Here is a solution that uses jekyll: stackoverflow.com/questions/15214762/…

[Genovo]

There's always Pandoc

[jmcmahon443]

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

[jmcmahon443]

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

[Siddhant Rimal]

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.

[gliemezis]

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.

[moctarjallo]

how can you do it without using npm?

[gliemezis]

@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.

[trdavidson]

this should be the accepted answer - so elegant and easy

[amzon-ex]

An off-topic question - how could one include themes in an HTML file to format the markdown?

[HimDek]

@amzon-ex use CSS inside <style></style> in the HTML