Skip to content

Formatting

Formatting helps you keep documents readable and structurally correct after edits, especially when content is nested across tabs, admonitions, lists, block quotes, definitions, and code fences. In team workflows, it also reduces style churn so diffs are cleaner, reviews are faster, and shared conventions stay consistent.

In Python Markdown, indentation and block ownership affect meaning. A formatter has to understand which block owns each line, or it can make a file look tidier while quietly changing how it parses. Zensical Studio's formatter is designed for Python Markdown and its extensions, so it can normalize style while preserving structure.

Formatting a document

Run Format DocumentFormat DocumentFormatReformat CodeShift+Alt+FmacOSShift+Option+FWindowsShift+Alt+FLinuxCtrl+Shift+I on a Python Markdown file. Zensical Studio normalizes structural authoring noise: headings, list markers, task lists, definition lists, blank lines, trailing whitespace, fences, tables, reference and footnote definitions, attribute lists, and line endings.

Table alignment is one of formatting's most visible wins, which is why it's the example below; see the Clean up Markdown page for more examples of what the formatter does.

a table with misaligned pipes and uneven cell padding snaps into correct column alignment after running Format Document

Nested content stays attached to the block that owns it. Tabs, admonitions, details, block quotes, lists, and code blocks keep the indentation that makes them parse correctly, instead of being flattened to a uniform indent.

Formatting also normalizes inline syntax where it is safe to do so: links, images, their titles, emphasis, and inline code are tidied to a consistent style without changing what they say. One concrete example: formatting strips extraneous whitespace from inside a link target.

Formatting on save

Running Format DocumentFormat DocumentFormatReformat CodemacOSShift+Option+FWindowsShift+Alt+FLinuxCtrl+Shift+I works right away, with no setup needed. If you'd rather it happen automatically whenever you save a Python Markdown file, add this to your project's .vscode/settings.json:

{
  "[python-markdown]": {
    "editor.defaultFormatter": "zensical.zensical-studio",
    "editor.formatOnSave": true
  }
}

When to use it

Formatting is especially useful right after a structural edit, such as using Extract to reference definition or moving content between tabs and admonitions. It groups reference and footnote definitions at the end of the document where that is safe, and cleans up whatever the edit left behind.

Where to go next

  • Live preview to check the rendered result after formatting.