Is there a way to include Markdown files inside other Markdown?

General Usage
,
1

I’ve searched this topic but could not find any solution to what it seems to be it should be a pretty common need.

I have several man pages of programs that share common options. For obvious reasons I would like to avoid having to copy the same text over and over again to each individual .md file (and change them the same number of times when something is updated). In RST one can simply .. include:: common but this seems not to be possible with Markdown.

Any solution for this?

Thanks.

2

Simplest solution would be to just preprocess the files using a template language like Mustache, though it’s not always the most ideal solution.

There appears to have been some discussion Transclusion or including sub-documents for reuse - #11 by chrisalley - Extensions - CommonMark Discussion about that kind of extension and there’s a kind of spec in https://github.com/iainc/Markdown-Content-Blocks. I’d consider accepting an extension to CommonMark.jl that supports this syntax if someone feels strongly about it and wants to take a stab at implementing it. It doesn’t look like it would be too difficult to implement. A thorough review of all the options and what’s most supported in the wild would be good to do prior to that.

3

@mike Thanks for the quick update on the situation but for me, only wanting to suffer horribly with docs, it seems easier to … drop Documenter and go back to RST.

4

@joa-quim:

when working with Documenter.jl, the following worked for me for including a file “links.md”, located in docs/src/:

````@eval
using Markdown
Markdown.parse_file(joinpath("..", "src", "links.md"))
`` `

Note: this will be evaluated in (a subfolder of) the build folder. So, you will need to check that you build the relative path correclty.

@mike :

  1. Is there a portable way to easily get to the root of the docs to avoid needing .. (something that will still work in all CI build scenarios etc.)?
  2. maybe some simple implementation along these lines would be enough?
1 Like
5

Note that I just opened a related topic: How to use Markdown reference links with Documenter.jl

6

You can access Main (i.e. stuff in the make.jl script) from the at-blocks. So you should be able to do something like:

  1. Define a global variable in make.jl that points to the root directory (e.g. docroot = joinpath(@__DIR__, "src"))
  2. Then access that in at-eval blocks with Main.docroot

You could even define it as a function to reduce the boilerplate in the at-eval block.

1 Like
7

Thanks a lot @mortenpi ! That worked :slight_smile:

You could even define it as a function to reduce the boilerplate in the at-eval block.

Is it also possible to create a custom macro that one can call then instead of @eval? The use case would be to do, e.g., @_ref(StaticArrays.jl) inside a normal documentation text in order to workaround this limitation: How to use Markdown reference links with Documenter.jl…

8

Technically, yes, but it becomes a little non-trivial. You would have to look at how we implement the various at-blocks in the Expanders pipeline (side note: they have nothing to do with Julia macros). Off the top of my head, I am not sure if something as simple as setting page.mapping[x] to some Markdown AST would work.

Frankly, I don’t think it’s worth the effort, unless you’re implementing some more complex at-block. Also, all those internals are non-public, and while they’ve been rather stable over the years, they may break at any time (if everything works out, I hope to have some major breakage here in 0.28).

At-evals showing objects that have the appropriate show methods defined is much easier and stable. As another example, the package table on our landing page is generated that way too (corresponding at-eval, definitions in make.jl).