Markdown¶

Markdown is a lightweight markup language for authoring text such as technical documentation, blog posts, etc. It was created in 2004 by John Gruber, with help from Aaron Swartz. Compared to alternatives like HTML or XML, it is easy to write and read, using a lean and intuitive syntax.

Zensical uses Python Markdown for compatibility with Material for MkDocs. Python Markdown aims to be a faithful and extensible port of John Gruber's original Markdown syntax. For the most part, it is fully compatible with the original specification, supporting the core features like headings, lists, links, blockquotes, and inline formatting (e.g., bold and italics).

Both Python Markdown itself and the Python Markdown Extensions that Zensical also supports provide extensions to the core Markdown language to cater for the needs of technical writers who want to produce clear, compelling, and visually attractive documentation.

Supporting the same syntax for content is a key component in our approach to ensure compatibility with Material for MkDocs and to then evolve Zensical from that point of departure. See our roadmap and compatibility pages for details.

Learning Markdown¶

The original description of Markdown by John Gruber is still a good starting point if you are unfamiliar with Markdown syntax. The Markdown Guide is another great resource.

Linking between pages¶

When adding links to other pages always use related links to the corresponding Markdown files instead of linking to the HTML that will be produced. Zensical will translate them to the correct links to the target. Crucially, it will produce the correct link to an HTML file or a link ending with a directory if use_directory_urls is being used.

In the future, Zensical will support output formats other than HTML and when this happens, links that point to the Markdown pages will still work, while links entered into the content that point directly to a HTML page will not.

Also, when using relative links, your site can move to a new site_url without any changes. Resist the urge to use absolute links. Absolute links may work on your local machine but may break on a production server.

Page title¶

Zensical produces a page title for each page. It uses, in order of priority:

1. a title defined for the page in the nav configuration setting.
2. a title defined in the front-matter of the page.
3. a first-level Markdown header in the page content
4. the base name of the Markdown file

So, explicitly defined navigation takes the highest priority, followed by an explicitly defined page title, followed by a title derived from the first level one Markdown header. If none of these are available, the filename is used as a fallback.