Auto-format Markdown¶

Markdown that follows formatting guidelines is easier to read, easier to maintain in a team and produces fewer spurious diffs in Git.

Developers and technical writers today often use auto-formatters to automatically format source code. Zensical Studio allows you to adopt this practice for your Markdown content.

The workspace-settings.md document is arguably the one most obviously in need of tidying up. Open it and press Shift+Alt+FmacOSShift+Option+FWindowsShift+Alt+FLinuxCtrl+Shift+I to format it. You may want to undo, then redo the operation to observe the changes.

Note how the auto-formatter changes only what has no impact on the rendering of the page. In this case, it aligns the table cells, changes the characters used for activating emphasis, and adds an empty line between the admonition header and the text.

List markers become consistent, blank lines and trailing whitespace are normalized, attribute lists and fences are tidied, line endings match. None of it changes what the document means, and formatting the same document a second time produces no further edits, which is what makes it safe to run on save or agree on as a team convention.

Tables snap into alignment¶

The table formatting is worth looking at more closely since authors can spend a lot of time making Markdown tables even halfway readable by padding each cell with the correct number of spaces.

With the auto-formatter, tables can be neatly formatted with ease, including correct alignment of table columns. Missing cells are added automatically, so adding a new column is as easy as adding the header cell.

Definitions move to the end¶

The [^dns] footnote in getting-started.md is defined in the middle of the content but is not even close to the place where the footnote appears. Such editing artifacts are common and this is why Zensical Studio's formatter collects definitions at the bottom of the document.

Nothing about the reference in the text changes: Go to Definition still works just the same, only that it now scrolls to the bottom of the file.

Use it after a structural edit¶

Formatting works well after extracting an inline link to a reference definition or moving blocks between tabs and admonitions: whatever the edit left out of place, formatting cleans up and groups the new definition with the others at the end of the document.

Where to go next¶

• Live preview
• Formatting in Write covers enabling format-on-save and what formatting does to tables specifically.