include directive

[Mpdreamz]

Include

Kind	Link
Reference	https://mystmd.org/guide/directives#directive-include
Documentation	https://mystmd.org/guide/embed#docs-include

Allows you to include the source or parsed version of a separate file into your document tree.

Implementation

• Parses directives and aliases
• Emits HTML
• Unit tests
• Validation (emits, warnings and errors).

Specification compliance:

• Argument string - required, The file path, which is relative to the file from which it was referenced.
• Aliases
  • {literalinclude} - *sets literal option to true
• Options
  • label (string)
  • literal (boolean)
    Flag the include block as literal, and show the contents as a code block. This can also be set automatically by setting the language or using the literalinclude directive.
  • lang, language, code (string)
    The language of the code to be highlighted as. If set, this automatically changes an include into a {literalinclude}.
  • caption (parsed) - A parsed caption for the code block.
  • linenos (boolean) - Show line numbers
  • lineno-start (number)
    Start line numbering from a particular value, default is 1. If present, line numbering is activated.
  • number-lines (number)
    Alternative for lineno-start, turns on line numbering and can be an integer that is the start of the line numbering.
  • emphasize-lines (string) - Emphasize particular lines (comma-separated numbers), e.g. “3,5”
  • filename (string)
    Show the filename in addition to the rendered code. The include directive will use the filename by default, to turn off this default set the filename to false.
  • start-line (number)
    Only the content starting from this line will be included. The first line has index 0 and negative values count from the end.
  • start-at (string)
    Only the content after and including the first occurrence of the specified text in the external data file will be included.
  • start-after (string)
    Only the content after the first occurrence of the specified text in the external data file will be included.
  • end-line (number) - Only the content up to (but excluding) this line will be included.
  • end-at (string)
    Only the content up to and including the first occurrence of the specified text in the external data file (but after any start-after text) will be included.
  • end-before (string)
    Only the content before the first occurrence of the specified text in the external data file (but after any start-after text) will be included.
  • lines (string)
    Specify exactly which lines to include from the original file, starting at 1. For example, 1,3,5-10,20- includes the lines 1, 3, 5 to 10 and lines 20 to the last line of the original file.
  • lineno-match (boolean) - Display the original line numbers, correct only when the selection consists of contiguous lines.

[KOTungseth]

Context: elastic-docs-v3/issues/1

[Mpdreamz]

@KOTungseth I think conditionals are a separate directive. This is for the inclusion of external files.

@KOTungseth @bmorelli25 do we need the following?

• Line numbering? (My vote would be no to keep it simple)
• Inclusion offsets (start and end)
  • by line numbers (maybe?)
  • by string demarkations?
    I'd vote no for now to keep it simple.

[Mpdreamz]

Discussed offline we keep options to a minimal for now.