Transitioning from Markdown to AsciiDoc

By Ronald Keschke

In this post, I want to document a recent change in our project: the switch from Markdown to AsciiDoc for all our content. Up to now, we had written exactly one blog post in Markdown, but for various reasons, we decided to transition to AsciiDoc. Here, I share our reasons, the process, and the insights gained.

Why AsciiDoc?

AsciiDoc offers several advantages over Markdown that were particularly relevant to our project:

  • More Structuring Options: AsciiDoc allows for finer organization of documents, including appendices, indices, and glossaries.

  • Advanced Formatting Options: While Markdown is somewhat limited in its formatting capabilities, AsciiDoc offers a wide range of styling options, such as admonitions (note boxes), page breaks, and custom attributes.

  • Better Support for Technical Documentation: AsciiDoc was specifically designed for creating technical documentation, making it ideal for our project, which includes detailed documentation.

The Transition Process

The transition began with the conversion of our single Markdown post into AsciiDoc. We followed these steps:

  1. Analysis of the Existing Markdown Document: First, we analyzed the structure and specific formatting of our Markdown document to get an overview of which AsciiDoc features we could utilize.

  2. Manual Conversion and Adjustment: Since we only had one post to convert, we opted for a manual transfer to maintain control over the formatting and structure. During the conversion, we utilized specific AsciiDoc features to improve the readability and structure of the document.

  3. Review and Fine-Tuning: After the initial conversion, we carefully reviewed the result and made fine-tuning adjustments to ensure that all information was correctly transferred and the layout met our expectations.

Insights from the Transition

The transition provided us with several valuable insights:

  • AsciiDoc Requires a Learning Curve: Although AsciiDoc is more powerful than Markdown, it requires some time to learn, especially when it comes to using advanced features.

  • Automated Tools Can Be Helpful: For larger projects, using automated conversion tools could save a significant amount of time. For our small project, manual conversion was feasible, but we plan to explore tools in the future.

  • The Investment Can Pay Off: The additional capabilities of AsciiDoc, especially for technical documentation, justify the transition and the associated effort.

Conclusion

The decision to switch from Markdown to AsciiDoc was significant for our project, and the results so far confirm our decision. The extended features of AsciiDoc provide us with the flexibility and capabilities needed to present our content. We are looking forward to seeing how our documentation and blog posts will evolve now that we can fully leverage the benefits of AsciiDoc.