For quite long time all Nextras repos were using Texy. Really great plain text format for writing structured documents. Yet, we are switching to Markdown.
As of today, the official nextras.org website is able to render Markdown documentation. We use CommonMark renderer with support for GitHub flavored version. So what is the main motivation:
- Direct rendering support on GitHub — we have the documentation right next to the code, directly in the repository. To gain more from this good decisions, we are switching to a format that can be directly rendered on GitHub. Naturally, GitHub flavored Markdown was the first choice.
- Tooling support — the most difficult thing about documentation is to write it. To ease the process, the tooling is nowadays quite necessary. Markdown’s direct support in PhpStorm is the major motivation. But there is a lot of other editors you and me can choose to write the docs.
The official web app uses great The Php League’s CommonMark library to render the Markdown on the web. The main requirement was to keep the current “render quality”. Surprisingly, this was quite easy. We use the following extensions:
- CommonMarkCoreExtension — provides basic Markdown functionality.
- HeadingPermalinkExtension — provides permalink to headings — a great feature for documentation and we currently use. The great thing here is that the configuration is really powerful, so we were able to render it the same way as previously — all links should stay working.
- GithubFlavoredMarkdownExtension — extension for GitHub flavor — tables and so.
- SmartPunctExtension — provides further typography extensions; sadly not powerful as Texy.
Also, we use custom renderer to highlight source-code on the server. Since the nextras.org source-code is open-sourced, you may check everything out on GitHub.
Design touch-ups
With the new backend we also updated the visuals:
- The text font-family is the system’s default. This applies for both — the text and the source-code.
- More focus on the text — no source code background, less of horizontal & vertical lines.
- The HTML title tag now contains the documentation page’s title.
