Comparison of 3 Markdown Document Tools: “Easy and Versatile Document Source Format”

Documentation tools like mdBook, Quartz, MkDoc, and HonKit all support Markdown, and are compatible with a variety of other languages ​​and formats. Let’s take a quick look at each tool’s standout features and where they’re best suited.
The Markdown text format makes it easy to create text that is human-readable and readily convertible to HTML. Originally developed for blogs and message boards, it is now widely used as a source format for documents.

In this article, we will look at four documentation generation tools (mdBook, Quartz, MkDoc, and HonKit). All of them support Markdown as their primary source, and can be used in any other project where you want to convert Markdown into a publishable format, such as an eBook or PDF.

Markdown extension support

The core Markdown syntax supports only a small subset of HTML or comment types. To fill in the gaps, extensions and add-ons for Markdown have emerged (e.g. Markdown in GitHub version) Each tool introduced in this article supports various extensions either natively or through plugins. Even somewhat unusual requirements, such as mathematical markup, can be easily supported using the appropriate Markdown extension.

mdBook

Most projects use internal tools to generate documentation, mdbookThis is a typical example. It is written in Rust and the Rust language project uses mdbook. Documents such as Rust Programming LanguageHowever, unless you plan to build your own extensions, you don’t need to know Rust to use mdbook. If you want to use the tool as is, you can download a precompiled binary and use it right away.
The setup process for an mdBook project is similar to initializing a new project in Rust or any other modern programming language. You start by running the mdBook command-line tool, mdbook init, to create a new, empty book project, pre-populated with a minimal amount of boilerplate, including a .gitignore file. You can then provide basic details either interactively or on the command line.
The heart of the mdBook project is the SUMMARY.md file, which serves as a table of contents. It links to files in the book using common Markdown notation, placed under subheadings, and arranged hierarchically. If you provide links to files in SUMMARY.md that do not yet exist, the file will be automatically created when the book runs the build process, and the page titles will be filled in with H1 subheadings.
Here is an example of SUMMARY.MD:

Normally, you would use the build command to regenerate the HTML of your book as needed, but it is often more convenient to use watch to serve interactively built pages on a local web server. This allows you to see what your document will look like in near real time as you write it, since it will be rebuilt automatically when source files change.
If there are code examples in the book, tests for the code can be automatically generated. Currently, mdBook only tests Rust code blocks in this way, and this requires providing a suitable test suite. However, there is room for this feature to be extended to other programming languages.
This part shows the biggest limitation of mdBook, which is that it is focused on documenting Rust projects. The tool can be extended through the preprocessor extension system, but writing such a preprocessor requires knowledge of Rust. Several third-party plugins are available that include sufficient support for other parts (e.g., LaTeX), so mdBook is worth considering for documentation purposes for non-Rust projects as well.

Quartz

Now in version 4 Quartzis not only for publishing documents in Markdown, but also for note collections or what the creator, Jackie Chao, calls ‘Digital Garden‘ can also be used for sharing purposes. Quartz integrates with the popular Markdown-based note-taking app Obsidian (a fitting name for Quartz), and you can use any text editor that supports the Markdown format.
Quartz does not have a standalone binary installer. You can either install it from source (it requires Node.js to run) or set it up by fetching a Docker container. Previous versions of Quartz were quite complicated to set up due to their dependency on the Hugo static site generator, but version 4 has been completely rewritten.
By default, the content directory in your source tree is where Quartz looks for Markdown source files. Quartz also relies on configuration files in the program directory to describe site organization and layout. This makes it difficult to build multiple sites with different organization and layout using a single Quartz source installation.
Quartz documents have something called front matter, which is where metadata is stored. Front matter metadata can be customized via plugins, but the default metadata is sufficient for most projects. Here are some examples of document content:

—
title: A Typing Test
draft: false
tags:
– qwerty
—
Jackdaws *love* my big sphinx of **quartz**!

Note that targets for links created in Markdown documents are not automatically generated when you build your site, so links will go to a 404 page.
One of the really nice things about Quartz is its rich and powerful built-in features for readers. Backlinks, breadcrumbs, callouts, and popover previews can all be generated automatically or programmatically from Markdown. LaTeX and Mermaid diagrams are also supported out of the box, and there are powerful user features like search-as-you-type and single-page app routing to avoid flashing unstyled content when navigating. It’s also TypeScript-ready. Own pluginYou can also write .

MkDocs

Made with Python MkDocsis one of the relatively simple Markdown document generators. It doesn’t have many core features, but it is highly extensible through a rich plugin ecosystem.
MkDocs does not have a standalone installer, but runs within the Python environment and can be configured using pip install mkdocs. It provides command line tools for the Python environment to run programs and issue commands. mkdocs new Typing mkdocs will create a simple new documentation project in the provided directory, and mkdocs serve will start a local web server to display the documentation project in the current directory.
A new MkDocs project starts with two files: index.md (a table of contents) and a configuration file, mkdocs.yml. (You can also use README.md as an index file.) The configuration file provides metadata for the documentation project and a way to organize the files into a table of contents. For example:

nav:
– Home: index.md
– User Guide:
– Writing your docs: writing-your-docs.md
– Styling your docs: styling-your-docs.md
– About:
– License: license.md
– Release Notes: release-notes.md

nav: If no block is provided, MkDocs will automatically search all .md files in the document directory, sorted by file name, and automatically create the block.
It comes with some important features built in. One of the hallmarks of a good document is the ability to search as you type. lunr.js It is included through the project. It provides some adjustable options, such as whether to pre-index the site (good for large sites). The supported Markdown includes features such as tables and code highlighting. Some extensionsThis is included by default. Metadata for documents follows Quartz’s Front Matter format or MultiMarkdown metadata styleYou can use both styles interchangeably in the same project, but the metadata keys supported will vary depending on the theme you are using to render the document.

The poor core functionality of MkDocs is A vast ecosystem of plugins and auxiliary projectsis largely offset by themes, generating documentation with APIs, graphics and charts, interacting with and executing code (e.g. Inline Jupyter Notebook), additional extensions for Markdown, and many other categories of features are included in the ecosystem.

HonKit

A commercial document hosting service that uses an open source rendering front end is Gitbook. HonKitIt is a fork of the Gitbook project created around 2018, and is compatible with Gitbook in many ways, but has a separate development team. Also, while the open source part of Gitbook uses GNU GPL 3, HonKit uses Apache, so it has a higher degree of license freedom.

HonKit’s core functionality is a well-curated, minimalist one. It works both as a Node.js library and as a command-line tool, generating documentation from Markdown or AsciiDoc files. Once you’ve installed HonKit globally or locally using npm, you can access its commands using npx honkit . The init command sets up a new, blank book, serve previews the book locally, and build renders the output. Output in PDF, ePub, and Mobi formats are all included without any additional plugins, and cover art can be automatically included.
Markdown files can use YAML-style front matter according to Quartz, and variables defined here can be used by users in their own templates. HonKit supports a basic but useful set of Markdown features, including tables, code blocks with common syntax highlighting, and simple footnotes.
The only file required to create a new HonKit book is a README.md file, which serves as an introduction. An optional table of contents (SUMMARY.md), written in a rough style, is also provided, as is JSON-based configuration data for the book. The latter can contain various details, such as file paths, publishing details, and the version of the program used to render the output.
Gitbookclass HonKitThere are hundreds of plugins available. HonKit can be used interchangeably between two types of plugins, making it easy to extend the basic functionality for any documentation task, especially those using Git/GitHub based integrations.

conclusion

For any Rust or Rust-related project, mdBook is the best choice, as it is written in the Rust language and was originally designed to generate documentation for Rust projects.

But it’s also useful for those who want a documentation creation environment that they can download and use right away. Quartz uses Node.js, so unless you’re already building a Node app, there’s a bit of extra work involved, but it has a ton of basic functionality. MkDocs requires Python as a dependency, and while it’s very basic, it has a rich plugin ecosystem.

Python users can also extend MkDocs by simply using it as a library. HonKit is also small (it also requires Node.js), but as a Gitbook fork, it has a large third-party ecosystem.
editor@itworld.co.kr