Convert ORG to ADOC

Why Convert ORG to ADOC?

Converting Org-mode documents to AsciiDoc format is valuable when you need to share your documentation with users outside the Emacs ecosystem or publish content in multiple formats. While Org-mode excels in personal productivity and literate programming within Emacs, AsciiDoc offers broader publishing capabilities and platform independence.

AsciiDoc provides excellent support for technical documentation publishing. If you've written notes, tutorials, or documentation in Org-mode and need to publish them as professional PDF books, EPUB ebooks, or HTML documentation sites, converting to AsciiDoc gives you access to the powerful Asciidoctor toolchain used by publishers like O'Reilly Media.

The conversion is particularly useful for teams where not everyone uses Emacs. AsciiDoc files render natively on GitHub and GitLab, making them ideal for project documentation that needs to be accessible to all team members. Unlike Org-mode, which requires Emacs for full functionality, AsciiDoc can be edited in any text editor.

AsciiDoc also provides features that complement Org-mode's strengths, such as code callouts (numbered annotations), conditional content processing, and better integration with documentation build systems like Antora. For technical manuals and API documentation, AsciiDoc's structured approach is often preferred.

Key Benefits of Converting ORG to ADOC:

• Platform Independence: Edit in any text editor, not just Emacs
• Publishing Ready: Professional PDF, EPUB, and HTML output
• GitHub/GitLab Native: Renders directly in repositories
• Team Collaboration: Accessible to non-Emacs users
• Code Callouts: Numbered annotations for code explanations
• Conditional Content: Include/exclude content based on attributes
• Modern Tooling: Asciidoctor is fast and feature-rich

Practical Examples

Example 1: Basic Document Structure

Input ORG file (document.org):

#+TITLE: Getting Started Guide
#+AUTHOR: Jane Developer

* Introduction

Welcome to the *project documentation*.
This guide will help you get started.

* Installation

Install using pip:

#+BEGIN_SRC bash
pip install myproject
#+END_SRC

#+BEGIN_NOTE
Requires Python 3.8 or higher.
#+END_NOTE

Output ADOC file (document.adoc):

= Getting Started Guide
Jane Developer

== Introduction

Welcome to the *project documentation*.
This guide will help you get started.

== Installation

Install using pip:

[source,bash]
----
pip install myproject
----

NOTE: Requires Python 3.8 or higher.

Example 2: Code Blocks and Tables

Input ORG file (api.org):

* API Reference

#+BEGIN_SRC python
def calculate_total(items):
    """Calculate the total price."""
    return sum(item.price for item in items)
#+END_SRC

| Method | Endpoint | Description |
|--------+----------+-------------|
| GET    | /users   | List users  |
| POST   | /users   | Create user |

Output ADOC file (api.adoc):

== API Reference

[source,python]
----
def calculate_total(items):
    """Calculate the total price."""
    return sum(item.price for item in items)
----

[cols="1,1,2"]
|===
| Method | Endpoint | Description

| GET
| /users
| List users

| POST
| /users
| Create user
|===

Example 3: Links and Lists

Input ORG file (guide.org):

* Resources

** Prerequisites
- Python 3.8+
- pip package manager
- Git (optional)

** Useful Links
- [[https://docs.python.org][Python Documentation]]
- [[https://github.com/myproject][Project Repository]]

See [[*Installation][Installation section]] for details.

Output ADOC file (guide.adoc):

== Resources

=== Prerequisites
* Python 3.8+
* pip package manager
* Git (optional)

=== Useful Links
* https://docs.python.org[Python Documentation]
* https://github.com/myproject[Project Repository]

See <<installation,Installation section>> for details.

Frequently Asked Questions (FAQ)

Q: What is Org-mode?

A: Org-mode is a powerful plain text markup format and major mode for GNU Emacs. Created in 2003 by Carsten Dominik, it's used for note-taking, task management, project planning, literate programming, and document authoring. It features hierarchical outlines, TODO states, scheduling, and the ability to execute code blocks in 40+ languages.

Q: Will my TODO items and scheduling be preserved?

A: TODO states, deadlines, and scheduling information are Org-mode specific features that don't have direct equivalents in AsciiDoc. During conversion, TODO items are converted to regular text (e.g., "TODO Task name" becomes plain text). For documentation purposes, this is usually acceptable, but task management features won't be functional.

Q: How are Org-mode code blocks converted?

A: Org-mode code blocks (#+BEGIN_SRC ... #+END_SRC) are converted to AsciiDoc source blocks ([source,lang]). The language specification is preserved, so Python, JavaScript, Bash, and other language blocks maintain their syntax highlighting. However, Babel execution features (results, sessions) are not preserved.

Q: What about Org-mode tables with formulas?

A: Org-mode tables are converted to AsciiDoc table syntax. However, spreadsheet formulas (using Calc) are Org-specific and won't be functional in AsciiDoc. The table structure and data are preserved, but computed cells will show their last calculated values as static text.

Q: Can I convert AsciiDoc back to Org-mode?

A: Yes, Pandoc supports bidirectional conversion. Use: `pandoc -f asciidoc -t org input.adoc -o output.org`. This is useful if you need to import AsciiDoc documentation into your Org-mode workflow, though some AsciiDoc-specific features may not have Org equivalents.

Q: How are Org-mode links converted?

A: External links [[url][description]] become AsciiDoc links url[description]. Internal links to headings are converted to cross-references. File links may need manual adjustment depending on your documentation structure.

Q: Do I need Emacs to use the converted files?

A: No! That's one of the main benefits of converting to AsciiDoc. The resulting .adoc files can be edited in any text editor (VS Code, Sublime, Vim, etc.) and processed with Asciidoctor without requiring Emacs. This makes your documentation more accessible to team members who don't use Emacs.

Q: What happens to Org-mode properties and drawers?

A: Property drawers (:PROPERTIES: ... :END:) and other Org-mode specific metadata are either converted to AsciiDoc attributes where possible or omitted if no equivalent exists. Custom properties may need manual handling after conversion.