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?

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

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

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

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