Skip to main content

Checks Markdown code blocks in a MkDocs site against user-defined actions

Project description

mkdocs-code-validator

Checks Markdown code blocks in a MkDocs site against user-defined actions

PyPI License GitHub Workflow Status

pip install mkdocs-code-validator

Usage

Activate the plugin in mkdocs.yml. The identifiers config is mandatory. And the plugin doesn't work without pymdownx.superfences:

plugins:
  - search
  - code-validator:
      identifiers:
        bash:
          validators:
            - grep a
markdown_extensions:
  - pymdownx.superfences

The above contrived config checks that every ```bash code block in the Markdown files of this MkDocs site must contain the letter "a", otherwise a warning will appear.

The content of each code block is piped as stdin to the command. The exit code of the command is what's checked: a non-zero code will produce a warning (which in MkDocs you can make fatal with the --strict flag). The output of the command is not used in any way, only preserved on the screen as part of a warning.

You can add any number of identifiers, and within them any number of validators commands, each of them has the ability to produce a warning.

If stdin is not usable with your command, the input can be passed as a temporary file instead -- that is done if the command contains the exact argument $< (which is then replaced with a file path). For the above example, changing the command to grep a $< would be equivalent (other than technicalities).

The commands do not allow freeform shell syntax, it's just one subprocess to call with its arguments. To explicitly opt into a shell, just run it as (e.g.) sh -c 'if grep a; then exit 1; fi'. Or, with a temporary file: sh -c 'if grep a "$1"; then exit 1; fi' $<.

The definition of what a code block is is all according to the pymdownx.superfences extension. It must be enabled; the plugin won't do anything without it.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mkdocs_code_validator-0.2.0.tar.gz (5.4 kB view hashes)

Uploaded Source

Built Distribution

mkdocs_code_validator-0.2.0-py3-none-any.whl (5.9 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page