Our great sponsors
-
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.
-
Appwrite
Appwrite - The Open Source Firebase alternative introduces iOS support . Appwrite is an open source backend server that helps you build native iOS applications much faster with realtime APIs for authentication, databases, files storage, cloud functions and much more!
-
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.
-
InfluxDB
Access the most powerful time series database as a service. Ingest, store, & analyze all types of time series data in a fully-managed, purpose-built database. Keep data forever with low-cost storage and superior data compression.
-
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.
-
nextra
Simple, powerful and flexible site generation framework with everything you love from Next.js.
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
: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.
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.
-
Sonar
Write Clean JavaScript Code. Always.. Sonar helps you commit clean code every time. With over 300 unique rules to find JavaScript bugs, code smells & vulnerabilities, Sonar finds the issues while you focus on the work.
