Our great sponsors
-
-
-
SurveyJS
Open-Source JSON Form Builder to Create Dynamic Forms Right in Your App. With SurveyJS form UI libraries, you can build and style forms in a fully-integrated drag & drop form builder, render them in your JS app, and store form submission data in any backend, inc. PHP, ASP.NET Core, and Node.js.
-
-
-
-
docToolchain
a AsciiDoc Toolchain for technical Software Documentation, focused on Software Architecture Documentation
-
InfluxDB
Power Real-Time Data Analytics at Scale. Get real-time insights from all types of time series data with InfluxDB. Ingest, query, and analyze billions of data points in real-time with unbounded cardinality.
-
-
-
nextra
Simple, powerful and flexible site generation framework with everything you love from Next.js.
-
-
-
-
-
-
-
-
Asciidoctor
:gem: A fast, open source text processor and publishing toolchain, written in Ruby, for converting AsciiDoc content to HTML 5, DocBook 5, and other formats.
-
WorkOS
The modern identity platform for B2B SaaS. The APIs are flexible and easy-to-use, supporting authentication, user identity, and complex enterprise features like SSO and SCIM provisioning.
In 2014, a group of Markdown fans came together and established CommonMark - a standard, interoperable and testable version of Markdown. In March 2017, GitHub published a formal spec for GitHub-Flavored Markdown (GFM); based on CommonMark. In the accompanying blog post when releasing GFM, GitHub addressed many of the limitations that Eric Holscher raised, things like how many spaces are needed to indent a line, or how many empty lines you need to break between different elements. GFM is, by far, the most popular flavor of Markdown.
Internationalization (i18n) pain for a documentation project is a process problem, not a feature gap. Documentation frameworks are not meant to translate your developer docs for you into the language of your choice. Some frameworks might offer i18n support, like the Crowdin support in Docusauraus v2. With Jekyll, you have to pick a theme like this one. I doubt if the reST or adoc frameworks would differ much from this process. Besides the framework support, you'll need a localization vendor like lokalise or a community driven platform like Crowdin to actually do the translation. Sébastien goes into great detail in this Docusaurus RFC when discussing i18n support in Docusaurus v2.
Jekyll, the engine behind GitHub Pages, was the most popular SSG until Hugo came out. Written in Ruby, Jekyll is a great choice for writing blog sites. Jekyll can take your content written in Markdown and Liquid templates and render them to a static website deployed to a server of your choice. The site you're currently on is built using Jekyll and GitHub Pages.
Released in 2022, Markdoc is a relatively new Markdown-based authoring framework. The Markdoc project is open-source and it powers Stripe's documentation. Their website has a live edit button which makes the website a playground for you to give Markdoc a try. Documentations created with Markdoc will automatically render with your React app and using @markdoc/next.js for your Next.js app.
Configured with a single YAML file, MKDocs is the fourth Markdown framework on my list, which falls in the category of SSG. Although there are not as many as in Hugo, MKDocs offers a few official themes and a number of third party themes. As a Python-based framework, you can use pip to install MKDocs plugins. You can follow this getting started guide for your first MKDocs project.
An implementation of the docs-as-code approach, docToolchain is a collection of scripts that makes it easy to create and maintain powerful technical documentation. It is a popular open-source project that uses jBake under the hood as the SSG. docToolchain can publish to Confluence, generate PDF using an Asciidoctor plugin, and more.
Unlike docToolchain or Asciidoctor, Antora is a true framework for Asciidoc that can store, retrieve, and aggregate all Asciidoc content from multiple git repositories. Antora’s page referencing system isn’t coupled to filesystem paths or URLs. You are able to cross reference pages across a local machine, a staging environment, and a production environment. To generate a site with Antora, you need the Antora CLI and Antora site generator.
If you're migrating your documentation project from one markup to another, you'll want to know about projects like Pandoc. If your build process includes a process to convert markup, Pandoc can be run with GitHub Actions. If you're planning on converting Asciidoc files to Markdown, you'll have to take a detour via the XML route. The proces will be: Asciidoc ---> XML ---> Markdown.
Internationalization (i18n) pain for a documentation project is a process problem, not a feature gap. Documentation frameworks are not meant to translate your developer docs for you into the language of your choice. Some frameworks might offer i18n support, like the Crowdin support in Docusauraus v2. With Jekyll, you have to pick a theme like this one. I doubt if the reST or adoc frameworks would differ much from this process. Besides the framework support, you'll need a localization vendor like lokalise or a community driven platform like Crowdin to actually do the translation. Sébastien goes into great detail in this Docusaurus RFC when discussing i18n support in Docusaurus v2.
Before choosing a markup language, you'll need to choose either a desktop code editor like VSCode or stay in your terminal and use something like EmacsVIM. Most code editors will have plug-ins for popular markup languages which will offer you syntax highlighting, preview, etc. If you're testing or learning a specific syntax, there are many online editors, such as, StackEdit for Markdown.
If you're migrating your documentation project from one markup to another, you'll want to know about projects like Pandoc. If your build process includes a process to convert markup, Pandoc can be run with GitHub Actions. If you're planning on converting Asciidoc files to Markdown, you'll have to take a detour via the XML route. The proces will be: Asciidoc ---> XML ---> Markdown.
From the creators of NextJS, the next SSG based on MDX is Nextra. Nextra offers advanced syntax highlighting, ease of i18n creation, out-of-the-box full text search, and Markdown link and image converted to Next.js Link and Next.js Image. With Nextra, you can write a blog or docs using the themes available. Here are the sites that are built using Nextra.
From the creators of NextJS, the next SSG based on MDX is Nextra. Nextra offers advanced syntax highlighting, ease of i18n creation, out-of-the-box full text search, and Markdown link and image converted to Next.js Link and Next.js Image. With Nextra, you can write a blog or docs using the themes available. Here are the sites that are built using Nextra.
Last, but certainly not least, among my favorite frameworks is the family of frameworks based on MDX. Before that, let’s understand what is MDX and how does it vary from MD.
If you're just starting out with Markdown, check out the syntax and write some hello-world docs online.
Released in 2022, Markdoc is a relatively new Markdown-based authoring framework. The Markdoc project is open-source and it powers Stripe's documentation. Their website has a live edit button which makes the website a playground for you to give Markdoc a try. Documentations created with Markdoc will automatically render with your React app and using @markdoc/next.js for your Next.js app.
An implementation of the docs-as-code approach, docToolchain is a collection of scripts that makes it easy to create and maintain powerful technical documentation. It is a popular open-source project that uses jBake under the hood as the SSG. docToolchain can publish to Confluence, generate PDF using an Asciidoctor plugin, and more.
Hugo is probably the most popular open-source static site generator. Written in Go, Hugo builds sites at a blistering speed. It has a native support for a variety of content types, menus, and dynamic API-driven content. These don't require you to use an additional plugin. You can select a theme that suits your project from a wide selection. Check out some of the project websites that are built with Hugo.
Humble brag that the last one in the list (Aiven 🦀) won 2022 DevPortal Awards in the category Best DevPortal Beyond REST Platforms. If I added a list of great docs websites but didn't include the OG, it would be a crime. Check out one of THE BEST documentation out there - Stripe Docs, built using Markdoc.
Before choosing a markup language, you'll need to choose either a desktop code editor like VSCode or stay in your terminal and use something like EmacsVIM. Most code editors will have plug-ins for popular markup languages which will offer you syntax highlighting, preview, etc. If you're testing or learning a specific syntax, there are many online editors, such as, StackEdit for Markdown.
Asciidoctor is a Ruby-based text processor for parsing AsciiDoc into a document model and converting it to HTML5, PDF, EPUB3, and other formats. Built-in converters for HTML5, DocBook5, and man pages are available in Asciidoctor. Asciidoctor has an out-of-the-box default stylesheet and built-in integrations for MathJax (display beautiful math in your browser), highlight.js, Rouge, and Pygments (syntax highlighting), as well as Font Awesome (for icons). Although Asciidoctor is written in Ruby, that does not mean you need to know Ruby to use it. Asciidoctor can be executed on a JVM using AsciidoctorJ or in any JavaScript environment (including the browser) using Asciidoctor.js. You can choose any one of three Asciidoctor processors (Ruby, JavaScript, Java/JVM) and get the same experience. You can also use the Asciidoctor Maven Plugin to convert your Asciidoc documentation using Asciidoctor from an Apache Maven build.