Skip to content

Support include syntax for markdown

Brett Walker requested to merge 195798-support-include-syntax-for-markdown into master

What does this MR do and why?

Adds a new markdown syntax to allow for the transclusion/including of another file or url.

::include{file=FILE_OR_URL}

The ::include must be on it's own line, staring in column one. Trailing spaces are not allowed.

This feature is modeled on our implementation of the Asciidoc include support. The same ApplicationSetings are also used, wiki_asciidoc_allow_uri_includes and asciidoc_max_includes.

  • This is only supported in repository files, either a project's repository or a wiki's repository.

  • Files are specified relative to their position in a repository. So if you're editing the doc/README.md file and wish to include the examples/code.md file, then you would use ::include{file=../examples/code.md}

  • URLs are only supported when the ApplicationSetting.wiki_asciidoc_allow_uri_includes is set to true. That value defaults to false, and is also false on gitlab.com.

  • You can specify multiple includes (up to asciidoc_max_includes), with each include on it's own line. At this time we do not support transitive dependencies, meaning includes inside of an include.

Current Asciidoc documentation:

MR acceptance checklist

Please evaluate this MR against the MR acceptance checklist. It helps you analyze changes to reduce risks in quality, performance, reliability, security, and maintainability.

How to set up and validate locally

  1. Enable the markdown_include_directive feature flag from the Rails console.

  2. In either a project's repository or a wiki, create the following files:

    doc/README.md (if creating in the wiki, don't add the .md, it's done automatically)

    Below is a code example:
    
    ::include{file=../examples/code.md}

    examples/code.md (if creating in the wiki, don't add the .md, it's done automatically)

    ```ruby
    # A code example
    def call
    ...
    end
    ```
  3. When you view the doc/README.md file, you should see the code example included.

  4. Try various syntax permutations - only a strict ::include{file=FILE_OR_URL} should be recognized.

  5. Add the include 33 times to a file. Only the first 32 should be expanded.

  6. If a file does not exist, then an error will appear inline.

  7. Add the following include and see it NOT included (just the link should be visible)

    ::include{file=https://gitlab.com/gitlab-org/gitlab/-/raw/master/MAINTENANCE.md}
  8. Now jump into the Rails console and enable wiki_asciidoc_allow_uri_includes:

    ApplicationSetting.first.update!(wiki_asciidoc_allow_uri_includes: true)
  9. The URL should now be included. You may need to edit the doc/README.md file in order to force the caching to be invalidated.

Related to #195798 (closed)

Edited by Brett Walker

Merge request reports

Loading