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.

Answer 1

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

No include directive is supported.

Answer 2

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

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

Answer 3

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

Answer 4

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.

Answer 5

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

Disclosure: I wrote the gem.