PasDoc ยป MarkdownOption

Overview

Run PasDoc with --markdown command-line option to understand (a subset of) Markdown syntax in the comments. This allows to specify various formatting options without writing @tags, which sometimes looks much more readable.

Supported blocks

Note that only a subset of Markdown syntax is supported.

  • Bold text: **bold** or __bold__ (output like @bold tag)

  • Italic text: *italic* or _italic_ (output like @italic tag)

  • Inline code: `code` (output like @code tag)

  • Links: [Link Title](https://example.org/link-target) (output like @url tag)

  • Multi-line code (preformatted text, output like @preformatted tag):

    Important note: Use 3 backtick characters, like this ```, to make this work. In the example below we show 3 apostrophes because of a limitation of GitHub wiki formatting (seems to implement incomplete/old AsciiDoctor syntax for escaping).

    '''
    Example
    preformatted
    multi-line
    text.
    '''
  • Multi-line Pascal code with syntax highlighting (output like @longCode tag):

    Important note: Use 3 backtick characters, like this ```, to make this work. In the example below we show 3 apostrophes because of a limitation of GitHub wiki formatting (seems to implement incomplete/old AsciiDoctor syntax for escaping).

    '''pascal
    if Foo then
      Writeln('Example Pascal code'); // comment
    '''
  • Unordered lists (output like @unorderedlist tag):

    * item 1
    * item 2
  • Ordered lists (output like @orderedlist tag):

    1. item 1
    2. item 2

Notes on lists

List items are defined with the usual format:

[WHITESPACE*N]MARKER[item contents]

Where:

  • WHITESPACE*N is any number (including zero) of tabs #9 or spaces #32

  • MARKER is

    • * or -, followed by one whitespace character, for unordered lists

    • NUMBER, followed by . or ), followed by one whitespace character, for ordered lists

Nested lists are supported as well. Each nested list must be indented with at least one more whitespace character than the parent item:

* item 1
  * item 1.2
    * item 1.3

Note that PasDoc implementation of lists is somewhat simpler and stricter than, f.i., GitHub has. PasDoc is much about indents - almost always a content belonging to one nesting level has the same indent. Exception is for text content without empty line only. Rules of how PasDoc reads list item contents (hereafter indent of a text line means number of leading whitespace characters and indent of a list item means number of leading characters before first character of item content - that is, leading whitespace characters plus list marker).

  • List item with indent lesser than current means current list is finished

 * item 1
  * item 1.2
 * item 2
  • List item with indent greater than current means nested list

* item 1
 * item 1.1
  • Line of text not preceded by empty line belongs to current item regardless of indent

* item 1
  * item 1.1
text 1.1
   text 1.1
  • Line of text preceded by empty line must have the same or greater indent to belong to current item. Text with lesser indent means current list is finished

* item 1
  * item 1.1
    text 1.1
      text 1.1
* item 2
  * item 2.1

   text 2
  • List item with the same indent is considered sibling of current item within current list (even preceded by empty line!)

* item 1

* item 2

* item 3

Future

Going forward, we want to implement as much as possible from GitHub Flavored Markdown syntax. All new Markdown features implemented in PasDoc should follow that spec as closely as possible.