Can documenter insert (embed) examples from a file to a page code block?

I would like to add some full-feature examples on my package documentation, but rather than copy/pasting in the example block I would like to keep each example on its own file.

In general markdown this is not possible, but maybe using Documenter it is ?? :slight_smile:

There is an open issue for this kind of feature. You have a few options for a workaround though:

  1. As suggested by Kristoffer, you can do something like

    ````@eval
    Markdown.parse("""
    ```julia
    $(readstring("PATH_TO_FILE"))
    ```
    """)
    ````
    
  2. Another option is to use Literate.jl to convert the script into a .md file for Documenter. You can look at how examples/example.jl is included in the Literate docs (basically, you just need to add a Literate.markdown call to docs/make.jl.

  3. Finally, you can always do your own pre-processing or generation of the .md files in docs/make.jl.

1 Like

JuMP embeds all of our examples with literate. It works excellently.

See
https://jump.dev/JuMP.jl/dev/tutorials/Getting%20started/getting_started_with_JuMP/

There is a link at the bottom to the source file

5 Likes