Github include md files in README.md?

Question

Is there a way in Github to include md files in for example the README.md?

# Headline

Text

[include](File:load_another_md_file_here.md)

It should not link to the file, it should load the contents from it, like PHP include / file_get_contents.

Mcphee

Answer 1

That does not seem to be possible, especially when considering github/markup#346 and github/markup#172.

No include directive is supported.

Godiva

Thanks! I will do the workaround then, use Gulp Concat to merge the files into one before sent to Github. – Shores

Yeah, and this is very unlikely to change in the future. Github doesn't provide this feature even for reStructuredText (rst) which has include directive in the official language spec. – Ngo

Answer 2

Since it is not possible I just ended up placing a link as

[MY-LINK](../../SOME-OTHER-README.MD)

Kitchens

this is an answer: "is not possible", and proposes an alternative (not the best in my opinion, but it's fine) – Ecbatana

Is there no solution yet? – Skerry

Answer 3

migrate your readme to a different file then construct your actual README however you like as a github action

EDIT: Here's a demo that you can build off of. This repo has a single github action that runs a script that dynamically builds the README.md based on the contents of the repository (to build a site map for the repo in the form of a table of contents): https://github.com/dmarx/bench-warmers

the workflow config:

name: update-readme

on:
  push:
    branches: [ "main" ]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v2
      - name: Run the script
        run: python scripts/update_readme.py
      - name: Commit files
        run: |
          git config --local user.name "dmarx"
          git add README.md
          git commit -m "Updated TOC"
      - name: Push changes
        uses: ad-m/github-push-action@master
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          force: true

Here's the chunk of my update script that's relevant to you:

... # code that builds the object `toc_str`

# template readme
with open('README.stub') as f:
    readme_stub = f.read()

# simple replacement, use whatever stand-in value is useful for you.
readme = readme_stub.replace('{TOC}',toc_str)

with open('README.md','w') as f:
    f.write(readme)

Which assumes you have a file named README.stub which might look something like this:

# Title

some text

{TOC}

more text

Where {TOC} is the substitution target for our dynamic content.

Hybris

Answer 4

This is not the correct answer but a workaround for others who really want this.

It's possible to use Gulp and Gulp Concat to merge the files into one before they are sent to Github..

Mcphee

Answer 5

Ruby gem markdown_helper implements include files for GitHub flavored markdown (GFM).

Disclosure: I wrote the gem.

Implacable

Does this work when viewing the markdown file on Github itself? – Falbala

Answer 6

Not a direct answer, since GFM doesn't support includes, but I keep a list of projects I found that let you include things with a preprocessing step to produce the final markdown file:

https://github.com/realazthat/snipinator/#-related-projects

Disclosure: I wrote snipinator.

Not complete, and not necessarily up to date. Make a PR to README.md.jinja, (see realazthat/snipinator/Contributions) to insert/modify the table, and edit this answer.

Project	Stars	Last Update	Language	Platform	Similarity X Obviousness
mdx-js / mdx	16.8k	2024/04/17	JS	N/A	⭐⭐⭐⭐⭐
fletcher / MultiMarkdown-6	599	2023/12/30	C	CLI	⭐⭐⭐⭐⭐
gajus / gitdown	448	2022/03/01	JS	CLI	⭐⭐⭐⭐⭐
gpoore / codebraid	362	2023/10/17	Python	CLI	⭐⭐⭐⭐⭐
amyreese / markdown-pp (archived)	307	2021/09/02	Python	CLI	⭐⭐⭐⭐⭐
zakhenry / embedme	222	2023/11/08	JS	CLI	⭐⭐⭐⭐⭐
DCsunset / pandoc-include	62	2024/04/30	Python	Pandoc / CLI	⭐⭐⭐⭐⭐
BurdetteLamar / markdown_helper	38	2020/03/16	Ruby	CLI	⭐⭐⭐⭐⭐
SimonCropp / MarkdownSnippets	23	2024/04/23	.NET	CLI	⭐⭐⭐⭐⭐
endocode / snippetextractor	4	2014/08/16	C++	CLI	⭐⭐⭐⭐⭐
polywrap / doc-snippets	3	2023/09/26	JS	CLI	⭐⭐⭐⭐⭐
hxtmike / markdown_include	2	2024/05/09	Python	CLI	⭐⭐⭐⭐⭐
JulianCataldo / remark-embed	2	2022/09/22	JS	JS / library	⭐⭐⭐⭐⭐
xrd / oreilly-snippets	2	2015/10/15	Ruby	Ruby / library	⭐⭐⭐⭐⭐
DamonOehlman / injectcode	1	2021/08/01	JS	CLI	⭐⭐⭐⭐⭐
electrovir / markdown-code-example-inserter	1	2024/02/19	JS	CLI	⭐⭐⭐⭐⭐
andersfischernielsen / Simple-Embedded-Markdown-Code-Snippets	1	2021/02/12	JS	CLI	⭐⭐⭐⭐⭐
ildar-shaimordanov / git-markdown-snippet	0	2021/09/14	Perl	CLI	⭐⭐⭐⭐⭐
teyc / markdown-snippet	0	2024/01/22	Powershell	Powershell / function	⭐⭐⭐⭐
marc-bouvier-graveyard / baldir_markdown	0	2020/06/15	Python	CLI	⭐⭐⭐⭐⭐
facelessuser / pymdown-extensions (snippets)	903	2024/05/05	Python	Python / PyMarkdown	⭐⭐⭐⭐
dineshsonachalam / markdown-autodocs	176	2022/09/19	JS	GH Action	⭐⭐⭐⭐
sethen / markdown-include	148	2017/10/26	JS	CLI+config	⭐⭐⭐⭐
cmacmackin / markdown-include	95	2023/02/07	Python	Python / library	⭐⭐⭐⭐
tokusumi / markdown-embed-code	28	2022/01/05	Python	GH Action	⭐⭐⭐⭐
sammndhr / gridsome-remark-embed-snippet	2	2021/06/14	JS	Gridsome	⭐⭐⭐⭐
NativeScript / markdown-snippet-injector	4	2019/01/24	JS	CLI	⭐⭐⭐⭐
fossunited/markdown-macros	0	2021/06/10	Python	Python / Python-Markdown	⭐⭐⭐⭐
fuxingloh / remark-code-import-replace	0	2022/12/21	JS	Remark?	⭐⭐⭐⭐
szkiba / mdcode	15	2014/02/12	Go	CLI	⭐⭐⭐
devincornell/pymddoc	0	2023/12/01	Python	Python	⭐⭐⭐
shiftkey / scribble (docs)	40	2013/08/08	.NET	CLI	⭐⭐
calebpeterson / jest-transformer-test-md	2	2020/08/21	JS	Jest Tests	⭐⭐
tjstankus / commitate	0	2014/05/29	Ruby	CLI	⭐
GitHub Docs: Creating a permanent link to a code snippet	N/A	N/A	N/A	GitHub	⭐
javierfernandes / markdown-exercises	1	2017/05/01	JS	N/A	⭐
gatsby-remark-embed-snippet	N/A (55k)	2024/01/23	JS	Gatsby	⭐
ARMmbed / snippet (docs)	6	2021/08/05	Python	CLI	⭐
drewavis / markdowninclude	1	2024/04/06	JS	VSCode Extension	?
romnn / embedme	0	2024/04/18	Go	N/A	⭐

Stu