Convert Textile to AsciiDoc

Why Convert Textile to AsciiDoc?

Converting Textile to AsciiDoc unlocks a vastly more powerful documentation format with features that Textile simply cannot match. AsciiDoc was designed from the ground up for serious technical writing and publishing, offering include directives, conditional content, cross-references, admonitions, and the ability to produce multiple output formats from a single source.

Textile has served well in environments like Redmine and Textpattern, but its feature set is limited compared to modern documentation needs. AsciiDoc addresses these limitations with a comprehensive markup language that supports everything from simple README files to full-length technical books, all while maintaining human-readable plain text source files.

The Asciidoctor toolchain is the primary processor for AsciiDoc content and provides excellent output quality for HTML5, PDF, EPUB3, DocBook 5, and man pages. The ecosystem includes plugins for syntax highlighting, diagrams (PlantUML, Ditaa), mathematical formulas (STEM), and custom extensions, making it one of the most versatile documentation platforms available.

For teams migrating away from Redmine or Textpattern, converting Textile content to AsciiDoc provides a modern, well-supported format that integrates seamlessly with GitHub, GitLab, CI/CD pipelines, and static site generators. The investment in conversion pays off through improved productivity, better output quality, and access to a thriving community of technical writers and developers.

Key Benefits of Converting Textile to AsciiDoc:

• Rich Feature Set: Includes, conditionals, cross-references, admonitions, and callouts
• Multi-Format Publishing: Generate HTML, PDF, EPUB, DocBook from one source
• Active Community: Asciidoctor has thousands of users and regular releases
• GitHub Integration: Native .adoc and .asciidoc rendering on GitHub
• Professional Publishing: Used by O'Reilly Media and other publishers
• Modular Content: Include directives for reusable documentation components
• IDE Support: Rich plugins for VS Code, IntelliJ IDEA, and other editors

Practical Examples

Example 1: Document Structure

Input Textile file (guide.textile):

h1. User Guide

h2. Getting Started

This guide helps you get started with the application.

h3. Prerequisites

* Ruby 3.0 or later
* Bundler gem installed
* Git version control

Output AsciiDoc file (guide.asciidoc):

= User Guide
:toc: left
:icons: font

== Getting Started

This guide helps you get started with the application.

=== Prerequisites

* Ruby 3.0 or later
* Bundler gem installed
* Git version control

Example 2: Code and Admonitions

Input Textile file (dev.textile):

h2. Installation

Install the package:

bc. gem install asciidoctor
asciidoctor --version

p(note). Make sure Ruby is installed first.

Output AsciiDoc file (dev.asciidoc):

== Installation

Install the package:

[source,bash]
----
gem install asciidoctor
asciidoctor --version
----

NOTE: Make sure Ruby is installed first.

Example 3: Tables and Links

Input Textile file (comparison.textile):

h2. Format Comparison

|_. Feature |_. Textile |_. AsciiDoc |
| Includes | No | Yes |
| PDF Output | No | Yes |
| Admonitions | No | Yes |

See "AsciiDoc docs":https://docs.asciidoctor.org for details.

Output AsciiDoc file (comparison.asciidoc):

== Format Comparison

[cols="1,1,1", options="header"]
|===
| Feature     | Textile | AsciiDoc
| Includes    | No      | Yes
| PDF Output  | No      | Yes
| Admonitions | No      | Yes
|===

See https://docs.asciidoctor.org[AsciiDoc docs] for details.

Frequently Asked Questions (FAQ)

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

A: There is no difference in format. AsciiDoc files can use .adoc, .asciidoc, or .asc extensions. The .adoc extension is the most common and recommended. The .asciidoc extension is the full name variant. Both are processed identically by Asciidoctor and rendered natively on GitHub.

Q: How does Textile compare to AsciiDoc in terms of features?

A: Textile is a simpler markup language focused on HTML output, while AsciiDoc is a comprehensive documentation format. AsciiDoc adds include directives, conditional processing, admonitions (NOTE, TIP, WARNING), cross-references, bibliography support, table of contents, multiple output formats, and document attributes that Textile lacks.

Q: Can I convert Textile tables to AsciiDoc tables?

A: Yes, Textile tables are fully converted to AsciiDoc table syntax. Textile's compact pipe-based syntax (|_. header | data |) is converted to AsciiDoc's delimited table format (|=== ... |===) with proper column definitions, header rows, and alignment settings preserved.

Q: Is AsciiDoc harder to learn than Textile?

A: Basic AsciiDoc is very approachable and similar in complexity to Textile. The learning curve increases with advanced features like includes, conditionals, and custom attributes. However, the investment pays off significantly for technical documentation. Most users can start writing productive AsciiDoc content within an hour.

Q: Does GitHub support AsciiDoc files?

A: Yes, GitHub natively renders both .adoc and .asciidoc files. You can use AsciiDoc for README files, documentation, and wiki pages. GitHub supports most AsciiDoc features including headings, tables, code blocks, admonitions, and cross-references. Some advanced features like includes may not render on GitHub.

Q: What tools do I need to work with AsciiDoc files?

A: The primary tool is Asciidoctor (Ruby gem), which converts AsciiDoc to HTML5, DocBook, and other formats. For PDF output, use asciidoctor-pdf. For EPUB, use asciidoctor-epub3. IDE plugins are available for VS Code (AsciiDoc extension), IntelliJ (AsciiDoc plugin), and other editors, providing syntax highlighting and live preview.

Q: Can I generate PDF from AsciiDoc files?

A: Yes! Use asciidoctor-pdf to generate professional PDF documents directly from AsciiDoc source files. You can customize fonts, colors, page layout, headers, footers, and other visual aspects using a YAML-based theme file. This is one of the key advantages over Textile, which has no native PDF generation capability.

Q: How do I handle Textile's CSS class attributes in AsciiDoc?

A: Textile's inline CSS classes like p(classname). are converted to AsciiDoc's role syntax [.classname]. AsciiDoc roles can be applied to paragraphs, blocks, and inline elements. While the syntax differs, the concept of applying custom styling through classes is supported in both formats, and the conversion preserves the intent of the original styling.