# Is there a way to include Markdown files inside other Markdown?
**URL:** https://discourse.julialang.org/t/is-there-a-way-to-include-markdown-files-inside-other-markdown/70895
**Category:** General Usage
**Tags:** question, documenter
**Created:** [November 3, 2021, 6:03pm UTC](https://discourse.julialang.org/t/is-there-a-way-to-include-markdown-files-inside-other-markdown/70895 "2021-11-03T18:03:23Z")
**Posts on this page:** 8
**Page:** 1
### Author:  [@joa-quim](https://discourse.julialang.org/u/joa-quim)
#### Post date: [November 3, 2021, 6:03pm UTC](https://discourse.julialang.org/t/is-there-a-way-to-include-markdown-files-inside-other-markdown/70895/1 "2021-11-03T18:03:23Z")
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.
---
### Author:  [@mike](https://discourse.julialang.org/u/mike)
#### Post date: [November 3, 2021, 6:25pm UTC](https://discourse.julialang.org/t/is-there-a-way-to-include-markdown-files-inside-other-markdown/70895/2 "2021-11-03T18:25:59Z")
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](https://talk.commonmark.org/t/transclusion-or-including-sub-documents-for-reuse/270/11) about that kind of extension and there’s a _kind of_ spec in [https://github.com/iainc/Markdown-Content-Blocks](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.
---
### Author:  [@joa-quim](https://discourse.julialang.org/u/joa-quim)
#### Post date: [November 3, 2021, 6:52pm UTC](https://discourse.julialang.org/t/is-there-a-way-to-include-markdown-files-inside-other-markdown/70895/3 "2021-11-03T18:52:14Z")
@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.
---
### Author:  [@samo](https://discourse.julialang.org/u/samo)
#### Post date: [July 14, 2022, 5:23pm UTC](https://discourse.julialang.org/t/is-there-a-way-to-include-markdown-files-inside-other-markdown/70895/4 "2022-07-14T17:23:18Z")
@joa-quim:
when working with Documenter.jl, the following worked for me for including a file “links.md”, located in `docs/src/`:
`````julia
````@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?
---
### Author:  [@samo](https://discourse.julialang.org/u/samo)
#### Post date: [July 14, 2022, 5:59pm UTC](https://discourse.julialang.org/t/is-there-a-way-to-include-markdown-files-inside-other-markdown/70895/5 "2022-07-14T17:59:07Z")
Note that I just opened a related topic: [How to use Markdown reference links with Documenter.jl](https://discourse.julialang.org/t/how-to-use-markdown-reference-links-with-documenter-jl/84232)
---
### Author:  [@mortenpi](https://discourse.julialang.org/u/mortenpi)
#### Post date: [July 15, 2022, 8:20am UTC](https://discourse.julialang.org/t/is-there-a-way-to-include-markdown-files-inside-other-markdown/70895/6 "2022-07-15T08:20:11Z")
> [@samo](#):
>
> 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.)?
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.
---
### Author:  [@samo](https://discourse.julialang.org/u/samo)
#### Post date: [July 15, 2022, 11:00am UTC](https://discourse.julialang.org/t/is-there-a-way-to-include-markdown-files-inside-other-markdown/70895/7 "2022-07-15T11:00:08Z")
Thanks a lot @mortenpi ! That worked 🙂
> 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](https://discourse.julialang.org/t/how-to-use-markdown-reference-links-with-documenter-jl/84232)…
---
### Author:  [@mortenpi](https://discourse.julialang.org/u/mortenpi)
#### Post date: [July 16, 2022, 4:30am UTC](https://discourse.julialang.org/t/is-there-a-way-to-include-markdown-files-inside-other-markdown/70895/8 "2022-07-16T04:30:11Z")
> [@samo](#):
>
> Is it also possible to create a custom macro that one can call then **instead** of `@eval`?
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](https://github.com/JuliaDocs/Documenter.jl/blob/master/src/Expanders.jl) (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](https://juliadocs.github.io/#Packages) is generated that way too ([corresponding at-eval](https://github.com/JuliaDocs/juliadocs.github.io/blob/source/src/index.md#packages), [definitions in `make.jl`](https://github.com/JuliaDocs/juliadocs.github.io/blob/97678b79d26f70ea6c7fc55957f133daeae83281/make.jl#L4-L40)).