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?

You can use XMLHttpRequest and innerHTML function or if you're using jQuery, you can use load function. http://stackoverflow.com/questions/17636528/how-do-i-load-an-html-page-in-a-div-using-javascript — Jose Hermosilla Rodrigo, Jun 12 '16 at 04:08
I'd go with running [jekyll](https://jekyllrb.com/) 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... — mb21, Jun 13 '16 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. — jmcmahon443, Feb 13 '17 at 16:05
Here is a solution that uses jekyll: http://stackoverflow.com/questions/15214762/how-can-i-sync-documentation-with-github-pages — jmcmahon443, Feb 13 '17 at 16:33

score 48 · Accepted Answer · answered Feb 23 '20 at 15:20

48

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>

answered Feb 23 '20 at 15:20

Constantin De La Roche

2,530
23
24

2

this should be the accepted answer - so elegant and easy – trdavidson Sep 17 '21 at 10:41
An off-topic question - how could one include themes in an HTML file to format the markdown? – amzon-ex Oct 22 '21 at 15:36
1

@amzon-ex use CSS inside in the HTML – HimDek Dec 12 '21 at 02:28

score 18 · Answer 2 · edited Feb 13 '17 at 16:30

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.

edited Feb 13 '17 at 16:30

jmcmahon443

202
2
14

answered Jun 14 '16 at 14:18

gliemezis

778
2
6
18

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 ` – Siddhant Rimal May 27 '17 at 13:20
1

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. – gliemezis May 31 '17 at 18:44
how can you do it without using `npm`? – moctarjallo Jan 03 '20 at 17:30
@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 ` – gliemezis Jan 06 '20 at 15:20

score 6 · Answer 3 · edited Feb 13 '17 at 16:37

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.

edited Feb 13 '17 at 16:37

jmcmahon443

202
2
14

answered Jun 12 '16 at 04:10

Sudsy

931
7
16

I think this is another Node.js solution (via the NPM package manager). The accepted answer is better because it has detailed steps. – jmcmahon443 Feb 13 '17 at 15:57

score 3 · Answer 4 · edited Feb 13 '17 at 15:57

3

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.

edited Feb 13 '17 at 15:57

jmcmahon443

202
2
14

answered Jun 12 '16 at 04:11

oklas

7,935
2
26
42

1

Another option is jekyll: http://stackoverflow.com/questions/15214762/how-can-i-sync-documentation-with-github-pages. – jmcmahon443 Feb 13 '17 at 16:33

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

4 Answers4

`. 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](https://github.com/github/markup).