Markdown, Asciidoc, or reStructuredText - a tale of docs-as-code

1

StackEdit

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.

#Markdown Editor #Text Editors #Office & Productivity 49 social mentions

2

Pygments

Sphinx is incredibly powerful and can offer a table of contents, automatic links for functions, automatic code highlighting using Pygments, and other capabilities using built-in or third-party extensions. If you'd like to use (a flavor of) Markdown with Sphinx, you can do so using MyST-parser - a Sphinx and Docutils extension to parse MyST.

#App Reviews #Customer Feedback #Documentation 9 social mentions

3

Notaku

Besides these five frameworks, Notaku gets an honorable mention that uses Notion as CMS to create documentation site. With SEO and site performance optimization out-of-the-box, Notaku can be a great choice for teams those are already using Notion.

#Blog #Docs #Notion 26 social mentions

4

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.

#Developer Tools #Web Frameworks #JavaScript Framework 919 social mentions

5

Markdown Live Preview

If you're just starting out with Markdown, check out the syntax and write some hello-world docs online.

#Note Taking #Productivity #Markdown Editor 12 social mentions

6

Lokalise

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.

#Translation Service #Localization #Website Localization 11 social mentions

7

JBake

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.

#Blogging #CMS #Blogging Platform 3 social mentions

8

Hugo

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.

#Static Site Generators #Blogging #Blogging Platform 353 social mentions

9

Docusaurus

With over 40K GitHub starts, Docusaurus is undeniably one of the most popular modern documentation frameworks based on MDX. Docusaurus orignates from Meta Open Source (f.k.a Facebook) and is packed with content-centric features (docs, blog, pages, versioning, i18n, a11y, SEO...). As a React + Node.js static site generator, you can either use MD to get started easily or use MDX to make your docs look interactive. This showcase of documentation sites using Docusaurus is enough to convince me that the UX and DX of a documentation site is as important as the content itself.

#Documentation #Documentation As A Service & Tools #Static Site Generators 192 social mentions

10

Markdown by DaringFireball

The original version of Markdown by John Gruber doesn't specify the syntax unambiguously. For example, it doesn't have table formatting. Due to the popularity of Markdown and the limitations of Gruber Markdown, a plethora of variations, or "flavors", of Markdown have been introduced. Due to this lack of standard, folks like Eric Holscher, who are passionate about the community, have been vocal about not using markdown for documentation.

#Markdown Editor #Text Editors #Office & Productivity 79 social mentions

11

Crowdin

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.

#Localization #Website Localization #App Localization 19 social mentions

12

Visual Studio Code

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.

#Text Editors #IDE #Software Development 1007 social mentions

13

Asciidoctor

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.

#Documentation #Documentation As A Service & Tools #Knowledge Base 23 social mentions

14

Antora

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.

#Documentation #Documentation As A Service & Tools #Static Site Generators 21 social mentions