A table in .md document included from external file

Question

Is there an elegant way how to include table from an external file in markdown document rendered by GitHub?

Non elegant solutions I can think of:

1. include it as image (this one is really really ugly)
2. use Rmarkdown and print table using R (wont be rendered by default)

Just to give a bit of explanation. I am using a set of README.md files in my git repository (hosted by GitHub), so it is really clear to browse repo online, because GitHub renders automatically README.md file in every subdirectory.

I am algorithmically generating summary tables that should be included in those documents. It would be way more elegant if that table could be read from external file, because I do not want to write scripts that will modify README.md files directly.

Answer 1

There is no way to include files within markdown. So you need a "preprocessing" stage to generate the markdown which is then shown on Github (or rendered with normal markdown tools).

What Github supports is a basic table layout, which you'd need to render:

Solution 1: scripting

You could add something like this to your README.md:

<!-- TABLE_GENERATE_START -->

| First Header  | Second Header |
| ------------- | ------------- |
| Content Cell  | Content Cell  |
| Content Cell  | Content Cell  |

<!-- TABLE_GENERATE_END -->

And then have a script which pulls in the external table, reformats it to match the github format and puts it between the two comment.

Solution 2: pandoc

Pandoc is a document converter framework with many possible inputs and outputs. If you're up to learn another tool you could

1. reformat you table into a markdown file using csv2table into table.md
2. create a readme_header.md and readme_footer.md with the markdown before/after the table
3. merge the three files with cat readme_header.md table.md readme_footer.md > REAME.md

Of course you can also do a mixture of both solutions, e.g. generate table.md using a script and merge using cat