markup 1.0.0

markup: ^1.0.0 copied to clipboard

Table of Contents

• Introduction
• Syntax
  • Block Tag
  • Fence Tag
• Built In Directives
  • drawio
  • file
  • ignore
  • output
  • process
  • template
  • toc
• Markup Configuration
• Plugins

Introduction #

Markup is a package to provide automated processing for Markdown files to be able to simplify the creation and maintenance of documentation.

Syntax #

Like most markdown processors, markup uses comments to annotate the processing that neds to occur. The syntax allows for single tag directives as well as block based directives. However, each directive supports only one of the syntaxes and which one is documented in the directive itself.

All directives take the general form of <!-- markup:directive. The difference in what follows is defined by whether it is a single tag format or a block format.

Single Tag #

Single tags are contained within a single comment itself and the contents of the tag are hidden from the rendered markdown. With the single tag format, the tag must end with /-->. This informs the parser that the tag has ended. Single tag formats allow for parameters to follow the directive in either JSON or YAML form. Let's take the example parameters:

{ "file": "my.drawio", "type": "svg" }

That can be added in any of the following ways:

<!-- markdown:name {"file": "my.drawio", "type": "svg"} /-->

<!-- markdown:name
{
  "file": "my.drawio",
  "type": "svg"
}
/-->

<!-- markdown:name
file: my.drawio
type: svg
/-->

Block Tag #

The block tags start and end with markup comment. The content within the tags is visible via the rendered Markdown file. An example of a block tag is:

<!-- markup:output -->

![my.png](my-1.png)

<!-- /markup:output -->

Fence Tag #

The fence tags utilize the standard GitHub fence syntax. This mechanism is provided for plugins as no built in processors exist for the fence syntax. For an example, see the markup_mermaid plugin.

```mermaid
graph LR
    A[Square Rect] -- Link text --> B((Circle))
    A --> C(Round Rect)
    B --> D{Rhombus}
    C --> D
```

Built In Directives #

drawio #

Example

drawio.md

Parameters

file #

Example

file.md

Parameters

ignore #

Example

full_processing.md

Parameters

n/a

output #

Example

n/a

Parameters

n/a

process #

Example

process.md

Parameters

template #

Example

template.md

Parameters

toc #

Example

toc.md

Parameters

Markup Configuration #

Markup can be configured via CLI Args or via a configuration file that may be in either JSON or YAML. Any value specified as a CLI arg will take priority over the same value in the configuration file. If a markup.yaml file exists, Markup will utilize that file by default as the configuration file.

Plugins can only be added via the configuration file, they cannot be passed in via the CLI.

CLI Args

markup 1.0.0

-c, --config     Configuration file for markup to use.
-i, --include    The search glob to find the file or files to modify.
-l, --log        Log level to use.
                 [ALL, FINEST, FINER, FINE, CONFIG, INFO, WARNING, SEVERE, SHOUT, OFF]
-o, --output     If set, all results will be written to this path and it's sub paths.
    --dry-run    Perform a dry run, print all the logs, but do not write any Markdown files.
    --help       Display this message.
    --version    Display version information.

Config File

All values are shown with their defaults in place.

# Whether to perform all processing but not actually write any output
dry-run: false

# The files for markup to scan for processing
include: "**/*.md"

# Log level to use.
# Valid values: ALL, FINEST, FINER, FINE, CONFIG, INFO, WARNING, SEVERE, SHOUT, OFF
log: INFO

# If set, all results will be written to this path and its sub paths
output: null

# The plugins to use
plugins:
  # The directive or code fence name to associate with this plugin
  <name>:
    # The command to execute (required)
    command: <command>

    # The optional arguments to pass to the command
    args: []

    # When true, ignores non-zero exit codes and uses whatever stdout was emitted
    ignore-exit-code: false

    # Defines if the processor is meant to run after the first pass of processing
    post-processor: false

    # Defines if the processor should replace the source content with the output of the process
    replace: false

    # The maximum timeout in seconds to wait for the plugin (defaults to 1 minute)
    timeout: 60

Parameters

Plugins #

Plugins can be created to provide processing not provided by markup itself. One such example is the markup_mermaid plugin.

Plugins must have an executable that reads the parameters via stdin. Plugins need to utilize the markup_common package and implement the MarkupProcessor interface.

Next, the plugin must be added to the Markup Configuration under the plugins map. The key in the plugins map determines the directive or fence tag name handled by the plugin.

Example

plugins:
  mermaid:
    command: markup_mermaid
    replace: true

    # Example to enable the max logging
    args:
      - log
      - FINEST

    # Already defaults to false, included for example purposes
    ignore-exit-code: false

    # Already defaults to false, included for example purposes
    post-processor: false

Parameters