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, so that it does not just 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 components and eliminates 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:

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

See the Auto-format Markdown page to see how auto-formatting can help you bring existing content into a consistent format and maintain that format over time and across a team.

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

  • Linting covers the structural and accessibility problems formatting does not fix for you.
  • Live preview to check the rendered result after formatting.