Markdown Output Formatting

[iainbrighton]

Markdown is meant to be a human-readable document format and some PScribo options aren't well suited to its output (unless converted to Html by a parser/renderer). Whilst working on the Markdown plugin, several rendering questions have arisen and I'd like the community's feedback.

• Should headers and footers be included in Markdown (.md) documents?

  • Personally, I don't think so as there is no concept of pages in the specification and it obfuscates the actual content
  • I know headers/footers are in the Text output, but they should probably be removed from there too for the same reason!
  • When the .md file is rendered in Html, there is no pseudo pagination like the PScribo Html plugin

• Should image data be included at the bottom of the Markdown (.md) document?

  • I am unsure with this one; including the image data means the resulting .md file can be converted to Html without any external dependencies but makes the .md file very messy/cluttered
  • Using traditional web/file links is cleaner, but does require the image source to be accessible when the .md file is rendered/converted into Html
  • It seems counterintuitive to try and shoehorn binary data when the resulting document should be human-readable

Any feedback is greatly appreciated! Thanks, Iain

[iainbrighton]

Initial implementation with the Markdown plugin can be found here: https://github.com/iainbrighton/PScribo/tree/Issue36. Here is the contents of the about_MarkdownPlugin help file.

TOPIC
    Markdown

SYNOPSIS
    PScribo supports outputting GitHub Flavored Markdown format (.md) documents.

DESCRIPTION
    Markdown is a plain text format for writing structured documents, based on conventions for indicating formatting
    in email and usenet posts. PScribo implements the GitHub Flavored Markdown (GFM) specification which is a
    strict superset of the CommonMark specification (https://github.github.com/gfm/).

KNOWN LIMITATIONS
    There are some restrictions emposed by the GFM specification that means that some PScribo functionality cannot
    either be partially or fully implemented:

    - No indentation (-Tab) support as indented text is rendered as code blocks.
    - Text underlining is not supported/defined in the specification.
    - Image resizing is not supported/defined in the specification.
    - Only image links are included in the Markdown output, by default (see Plugin Options below).
      - Local image file references may not be rendered by some Markdown parsers/viewers (for security).
    - Numbered lists only support one level of indentation.
    - Headers and footers are not rendered in the output.

PLUGIN OPTIONS
    The Markdown plugin accepts the following output customisation options:

        TextWidth [int]               : Sets the default line length used for rendering output. If not specified,
                                        defaults to 120 characters per line. Note: table output is not wrapped.
        PageBreakSeparator [char]     : Specifies the character used for page breaks. If not specified, defaults
                                        to '*'.
        PageBreakSeparatorWidth [int] : Specifies the width of the rendered page break. If not specified, defaults
                                        to 20.
        LineBreakSeparator [char]     : Specifies the character used for line breaks. If not specified, defaults
                                        to '-'.
        LineBreakSeparatorWidth [int] : Specifies the width of the rendered page break. If not specified, defaults
                                        to 10.
        EmbedImage [bool]             : By default, web/file image links are included in the Markdown file. If enabled,
                                        all images will be Base64-encoded and appended to the end of the file.
        RenderBlankLine [bool]        : Markdown parsers typically ignore multiple/consecutive blanklines. When enabled,
                                        this option will output Html line breaks to ensure they are rendered by Markdown
                                        viewers.

    Output customisations are passed to the Export-Document cmdlet, e.g.

    PS> $document | Export-Document -Format Markdown -Options @{ EmbedImage = $true }

[DSI-BenThomas]

Was there a plan to finish this at some point? Or were you looking for assistance to test it?

[carceneaux]

• Should headers and footers be included in Markdown (.md) documents?

The way I handled this in the JSON plugin is I included the header only once at the beginning and the footer only once at the end. My thought was the header/footer could potentially contain valuable information but it doesn't need to be seen more than once given there's no actual "pages".

• Should image data be included at the bottom of the Markdown (.md) document?

I'd say keep it simple for MVP. The tried and true traditional image links referencing the external file(s) will be fine for most folks.

Additionally, I've performed an initial review of the Markdown plugin code. Overall, it's looking pretty good! Outside of the items referenced above, here's some bugs/oddities I found:

• TOC does not have indentions so sub-sections are not evident
  • I recommend using a Markdown list to enforce indentions
  • An unordered list could be used
• We need to ensure lines are trimmed prior to adding closing Markdown text tags for bold and italics.
  • In my testing, an empty variable caused Markdown parsing to fail as these text modifiers want to "touch" the first and last character.
  • Ex: _example _ Note the space in between the final e and _.