pymdownx-block-converter

PyMdown Extension v9.10+ introduces a new way to define blocks, which you might know under the following names:

• admonitions
• details
• tabs

The new syntax improves the readability of the Markdown source and allows for more flexibility. However, you might already have a lot of Markdown files that use the old syntax.

This repo contains a script created by @tiangolo to update Markdown block syntax (per sqlmodel#712 , sqlmodel#713, and pymdown-extensions#1973 ). Additionally, this script is packaged in a container allowing conversion from the old block syntax to the new one across your entire documentation base or just a single file.

Supported Syntax

• Admonitions declared with !!!
  • including those with varied spacing around the type
• Details declared with HTML tags
  • with and without <summary/> tags
• Details declared with ???, including the open attribute with ???+
  • again, with and without a summary
• Tabs with ===

Limitations:

1. The script doesn't handle nested tabs conversion at this moment.

Usage

Important

It is always a good idea to first run the script against a single file to see if it works as expected.

✨ To do so, first determine whether to run the container or locally run the script.

Container

Container Volume Mount Single File

To volume mount a specific file and fallback to pattern matching /work/*.md:

sudo docker run --rm -v $(pwd)/path/to/file.md:/work/test.md \
     ghcr.io/hellt/pymdownx-block-converter

Container Volume Mount Directory

To convert the whole documentation base that is typically contained in the docs folder (uses fallback to /work/*.md), run the following command:

sudo docker run --rm -v $(pwd)/docs:/work \
     ghcr.io/hellt/pymdownx-block-converter

Container Volume Mount Directory, but Only Execute on Single File

To volume mount a directory, but only execute against a single file:

sudo docker run --rm -v $(pwd)/docs:/work \
     ghcr.io/hellt/pymdownx-block-converter /work/path/to/test.md

GitHub Codespace Container

Launch a GitHub ✨Codespace and use a local execution method (see below) to convert Markdown blocks.

1. With the click of a button
   • 
2. Manual steps

   • From this project's main page, click Code, then Codespace.

   • Choose Create codespace on <branch_name>

     This creates a codespace with the default resources (currently 2 CPU, 8 GB RAM, 32 GB Storage).

   • 🚀 Run block_conv on your Markdown file:

     /app/block_conv.py /path/to/test.md

Important

Keep in mind there are monthly limits measured in core hours and to stop your codespace 🛑 when you're not using it to conserve your monthly core hours allowance.

Local Execution without Container

While there's nothing wrong with containers, it is possible to locally run the script.

Local Execution on Single File

Local execution against a single file:

python block_conv.py /path/to/test.md

Local Execution on Directory

Local execution against a directory (utilizes globbing):

python block_conv.py /path/to/

Local Execution using Fallback

Running the script without a file or path argument fallsback and runs against /work/*.md in (to remain backwards compatible with the container's Dockerfile).

python block_conv.py