Yaml Front Matter Configuration

⚠️ This is a brain storm and work in progress. Any feedback and suggestions would be greatly appreciated.

YAML front matter configuration allows configuring all module options in the markdown file as opposed to having the options/extensions hard coded. This feature is available starting in version 0.6.0 and requires minimal collaboration with user code to enable this powerful feature.

Using YAML front matter configurator makes preserving markdown content easier since the file defines the parsing and rendering options expected by the document in order to properly parse and render its contents.

Set Parser.FLEXMARK_YAML_CONFIGURATOR to true to enable YAML configuration.

All core modules that support this setting will use a new instance of their parser, renderer, converter based on settings taken from the actual text being parsed or having yaml front matter node in the document AST which contains flexmark configuration settings.

These settings are applied over the options used to create the core module parser, renderer converter or extension.

⚠️ It is highly recommended to implement filtering of YAML front matter configuration by setting Parser.FLEXMARK_YAML_FILTER to your filter implementation. In the filter suppress/customize requested settings to remain in control what you allow to be modified by user documents from your configured defaults.

• configuration with applicable extension/module

  • core modules:
    • Parser options: parser
    • HtmlRender options: html
    • Formatter render options: formatter
  • converters:
    • docx converter options: docx
    • PDF converter options: pdf
    • html2md converter options: html2md
    • Jira converter options: jira
    • YouTrack converter options: youtrack
  • pegdown profile options: pegdown
  • extension without flexmark-ext- prefix
    • abbreviation
    • admonition
    • anchorlink
    • aside
    • attributes
    • autolink
    • definition
    • emoji
    • enumerated-reference
    • escaped-character
    • footnotes
    • gfm-issues
    • gfm-strikethrough
    • gfm-tasklist
    • gfm-users
    • gitlab
    • ins
    • jekyll-tag
    • macros
    • media-tags
    • spec-example
    • superscript
    • tables
    • toc
    • typographic
    • wikilink
    • youtube-embedded
  • each one can have a map of options as provided by extension yaml configuration support function Map<String, YamlOption> getYamlOptionsMap()
    • getYamlOptionsMap() returns only those values which can be set by:
      • boolean
      • int
      • float
      • string
      • enums - map of string identifiers
      • arrays of all of the above
      • maps of any keys the above except arrays mapping to any values including maps
      • YamlOption provides the name, type information and setter to handle setting an actual option from YAML value in a MutableDataSet to be used for processing the document.

  flexmark:
    - module:
      - option: ...  

• Add: YAML configuration option and handling by core modules in a generic reusable way so modules can easily use core functionality.

• Add: quick YAML pre-parser for stream, chars to allow quickly to determine if need new options based on configuration.

• Add: yaml configuration filtering

  • DataSet YamlConfigFilter(String module, DataSet options) module is the module name in the configuration and options contains all options set in the yaml configuration. Return configuration you want to use or null if no mods to configuration for this module should be used.

• spec-example configuration:

  • section to language and ast position information so these can be properly mapped in markdown nav. If not provided default to 1-Markdown, 2-Html, 3-Ast for 1.
    • section types are any text designating language contained in that section with default of text
    • ast type has special meaning for Markdown Navigator and will look for position information in the nodes and highlight selected ranges in the section given by for key, with default being for: 1 meaning position information for text in section 1.
  • visible character mapping: spc, tab, cr, lf, intellij

  For example current implementation defaults would have this for its configuration:

  flexmark:
    - spec-example:
      sections:
        1: markdown
        2: html
        3: ast
           for: 1
      visible-chars:
        spc: ""
        tab: "→"
        cr: "⏎"
        lf: ""
        intellij: "⎮"