Convert LaTeX to AsciiDoc

Why Convert LaTeX to AsciiDoc?

Converting LaTeX to AsciiDoc is an excellent choice when repurposing academic or scientific content for technical documentation platforms. LaTeX was designed for print-quality typesetting, while AsciiDoc was built for modern documentation workflows that target web, print, and e-book formats simultaneously. This conversion bridges the gap between traditional academic publishing and contemporary documentation practices.

AsciiDoc's strength lies in its semantic clarity. Where LaTeX requires verbose command sequences, AsciiDoc uses intuitive conventions that are immediately readable. This makes AsciiDoc documents easier to review in pull requests, collaborate on with teams of varying technical expertise, and maintain over long periods. The format is particularly well-suited for living documents that are updated frequently.

The Asciidoctor processing ecosystem provides modern build integration through Maven, Gradle, and npm plugins, enabling documentation to be built and tested alongside software. This continuous integration approach to documentation ensures that technical content stays current and can be validated automatically, something that is difficult to achieve with traditional LaTeX workflows.

For organizations migrating from LaTeX-based documentation to a more collaborative platform, AsciiDoc offers the best balance of power and accessibility. It supports nearly all the structural elements found in LaTeX (sections, figures, tables, cross-references, footnotes) while adding modern features like admonition blocks, source code callouts, and conditional content inclusion.

Key Benefits of Converting LaTeX to AsciiDoc:

• Readable Source: Clean, intuitive syntax without backslash commands
• Build Integration: Maven, Gradle, and npm plugins for CI/CD pipelines
• Flexible Output: Single source to HTML5, PDF, EPUB3, and DocBook
• Collaboration: Git-friendly format with clear diff visibility
• Modular Docs: Include directives for reusable content components
• Admonitions: Built-in NOTE, TIP, WARNING, CAUTION, IMPORTANT blocks
• Antora Support: Publish multi-repository documentation sites

Practical Examples

Example 1: Research Paper with Citations

Input LaTeX file (research.tex):

\documentclass{article}
\usepackage{cite}
\title{Machine Learning in Healthcare}
\author{Dr. Alice Johnson}
\date{2024}
\begin{document}
\maketitle
\begin{abstract}
This study explores the application of
deep learning models in diagnostic imaging.
\end{abstract}
\section{Methodology}
We employed convolutional neural networks
(CNNs) as described in \cite{lecun1998}.
\end{document}

Output AsciiDoc file (research.asciidoc):

= Machine Learning in Healthcare
Dr. Alice Johnson
2024
:doctype: article

[abstract]
This study explores the application of
deep learning models in diagnostic imaging.

== Methodology
We employed convolutional neural networks
(CNNs) as described in cite:[lecun1998].

Example 2: Software User Guide

Input LaTeX file (userguide.tex):

\section{Configuration}
\subsection{Environment Variables}
Set the following variables before starting:
\begin{description}
  \item[DB\_HOST] Database server hostname
  \item[DB\_PORT] Database port (default: 5432)
  \item[API\_KEY] Your API authentication key
\end{description}
\textbf{Warning:} Never commit API keys
to version control.

Output AsciiDoc file (userguide.asciidoc):

== Configuration
=== Environment Variables
Set the following variables before starting:

DB_HOST:: Database server hostname
DB_PORT:: Database port (default: 5432)
API_KEY:: Your API authentication key

WARNING: Never commit API keys
to version control.

Example 3: Mathematical Content with Figures

Input LaTeX file (theory.tex):

\section{Theoretical Framework}
The probability density function is:
\begin{equation}
  f(x) = \frac{1}{\sigma\sqrt{2\pi}}
  e^{-\frac{(x-\mu)^2}{2\sigma^2}}
\end{equation}
\begin{figure}[h]
  \centering
  \includegraphics[width=0.8\textwidth]{graph.png}
  \caption{Normal distribution curve}
  \label{fig:normal}
\end{figure}

Output AsciiDoc file (theory.asciidoc):

== Theoretical Framework
The probability density function is:

[stem]
++++
f(x) = \frac{1}{\sigma\sqrt{2\pi}}
e^{-\frac{(x-\mu)^2}{2\sigma^2}}
++++

.Normal distribution curve
image::graph.png[Normal distribution curve,width=80%]

Frequently Asked Questions (FAQ)

Q: What is the difference between ADOC and AsciiDoc extensions?

A: They refer to the same format. The .adoc extension is the modern convention recommended by the Asciidoctor project, while .asciidoc is the original longer extension. Both are processed identically by Asciidoctor. The .asc extension is also recognized but less commonly used.

Q: How are LaTeX equations handled in AsciiDoc?

A: AsciiDoc supports mathematical notation through STEM blocks, which can render LaTeX math syntax using MathJax or KaTeX in HTML output. Set the :stem: attribute in your document header, then use stem:[] for inline math or [stem] blocks for display equations. Most standard LaTeX math commands are supported.

Q: Can I use AsciiDoc for journal submissions?

A: Most academic journals require LaTeX or Word submissions. AsciiDoc is better suited for technical documentation, books, and online publications. If you need to submit to journals, keep your LaTeX source for that purpose and use the AsciiDoc version for web-based or internal documentation.

Q: What is Asciidoctor and do I need it?

A: Asciidoctor is the modern processor for AsciiDoc documents, written in Ruby with ports to Java (AsciidoctorJ) and JavaScript (Asciidoctor.js). You need it to convert AsciiDoc to HTML, PDF, or other output formats. It can be installed via RubyGems, npm, or as a Maven/Gradle dependency.

Q: How does the conversion handle LaTeX cross-references?

A: LaTeX labels and references are converted to AsciiDoc anchors and cross-references. A LaTeX \label and \ref pair becomes an AsciiDoc anchor (double square brackets) and cross-reference (double angle brackets). Section, figure, and table references are all preserved in the AsciiDoc output.

Q: Can AsciiDoc produce print-quality PDFs like LaTeX?

A: Asciidoctor-pdf generates good quality PDF output with customizable themes, but it does not match LaTeX's typographic sophistication. For high-quality print output, you can use the LaTeX backend to generate a .tex file from AsciiDoc and compile it with a TeX engine, combining the best of both worlds.

Q: What is Antora and how does it relate to AsciiDoc?

A: Antora is a multi-repository documentation site generator built specifically for AsciiDoc content. It allows you to aggregate documentation from multiple Git repositories into a unified, versioned documentation website. Converting LaTeX content to AsciiDoc enables you to include it in Antora-powered documentation sites.

Q: Are LaTeX tables converted accurately?

A: Standard LaTeX tables (tabular environment) convert well to AsciiDoc table syntax. Simple column alignments, headers, and spanning cells are preserved. Complex LaTeX table features like longtable, multirow, or custom column specifications may need manual adjustment in the AsciiDoc output.