Convert AsciiDoc to Textile

Why Convert AsciiDoc to Textile?

Converting AsciiDoc to Textile is essential when you need to migrate documentation to platforms that natively support Textile markup, such as Redmine, Trac, or Textpattern CMS. While AsciiDoc excels at comprehensive technical documentation, Textile is the preferred markup language for many project management and wiki platforms, making this conversion necessary for teams that use these specific tools.

Textile, created by Dean Allen in 2002, is a lightweight markup language designed to produce well-structured HTML from simple, readable text. It features a clean syntax with intuitive formatting conventions such as *bold*, _italic_, and h1. through h6. for headings. Textile also supports advanced features like CSS class and ID assignment directly in the markup, giving authors fine-grained control over the HTML output without writing raw HTML.

The conversion process maps AsciiDoc structural elements to their Textile equivalents. Headings using = signs become h1. through h6. notation. Bold and italic formatting translates naturally since both formats use similar conventions. Tables, lists, and links are restructured to follow Textile syntax rules. Code blocks are converted to Textile's bc. (block code) notation. While some advanced AsciiDoc features like include directives and admonitions have no direct Textile equivalent, the core content and structure are faithfully preserved.

This conversion is particularly valuable for organizations transitioning project management platforms or teams that need to publish the same content across different systems. Developers who maintain AsciiDoc documentation but also contribute to Redmine wikis benefit from automated conversion rather than manual reformatting. The result is consistent content across platforms with minimal effort.

Key Benefits of Converting AsciiDoc to Textile:

• Redmine Compatibility: Directly use content in Redmine wiki pages and issue descriptions
• Trac Integration: Publish documentation in Trac-based project management systems
• Simpler Syntax: Textile is easier for non-technical team members to edit
• CSS Styling Hooks: Textile supports inline CSS class and ID assignment
• Clean HTML Output: Textile generates well-structured, semantic HTML
• Platform Migration: Move content between different documentation systems
• Wider Team Access: Lower learning curve allows more contributors

Practical Examples

Example 1: Technical Documentation Page

Input AsciiDoc file (guide.adoc):

= Installation Guide

== Prerequisites

Before installing, ensure you have:

* Python 3.8 or higher
* pip package manager
* Git version control

== Installation Steps

. Clone the repository
. Run `pip install -r requirements.txt`
. Configure the settings file

NOTE: Restart the server after installation.

Output Textile file (guide.textile):

h1. Installation Guide

h2. Prerequisites

Before installing, ensure you have:

* Python 3.8 or higher
* pip package manager
* Git version control

h2. Installation Steps

# Clone the repository
# Run @pip install -r requirements.txt@
# Configure the settings file

p(note). Restart the server after installation.

Example 2: Project Status Report

Input AsciiDoc file (status.adoc):

== Sprint Report - Q1 2026

.Task Summary
|===
|Task |Assignee |Status

|Backend API
|Alice
|Complete

|Frontend UI
|Bob
|In Progress

|Testing
|Carol
|Pending
|===

*Overall Progress:* 65% complete

Output Textile file (status.textile):

h2. Sprint Report - Q1 2026

|_. Task |_. Assignee |_. Status |
| Backend API | Alice | Complete |
| Frontend UI | Bob | In Progress |
| Testing | Carol | Pending |

*Overall Progress:* 65% complete

Example 3: API Reference for Wiki

Input AsciiDoc file (api-ref.adoc):

== Authentication API

The authentication endpoint supports:

* OAuth 2.0 flow
* API key authentication
* JWT token refresh

[source,bash]
----
curl -X POST https://api.example.com/auth \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "secret"}'
----

TIP: Store tokens securely using environment variables.

Output Textile file (api-ref.textile):

h2. Authentication API

The authentication endpoint supports:

* OAuth 2.0 flow
* API key authentication
* JWT token refresh

bc. curl -X POST https://api.example.com/auth \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "secret"}'

p(tip). Store tokens securely using environment variables.

Frequently Asked Questions (FAQ)

Q: What is Textile markup?

A: Textile is a lightweight markup language created by Dean Allen in 2002 for generating well-structured HTML from plain text. It uses intuitive syntax like *bold*, _italic_, and h1. for headings. Textile is widely used in project management tools like Redmine and Trac, as well as content management systems like Textpattern.

Q: Why would I convert AsciiDoc to Textile instead of Markdown?

A: The primary reason is platform compatibility. If your team uses Redmine, Trac, or Textpattern CMS, these platforms natively support Textile. Textile also offers built-in CSS class and ID assignment, which Markdown lacks. Converting to Textile ensures your content works seamlessly within these specific ecosystems.

Q: Are AsciiDoc tables preserved in the conversion?

A: Yes, AsciiDoc tables are converted to Textile table syntax. Header rows use the |_. prefix notation in Textile, and regular cells use the standard | delimiter. Column alignment and basic cell content are preserved, though some advanced AsciiDoc table features like column spanning may require manual adjustment.

Q: What happens to AsciiDoc admonitions (NOTE, TIP, WARNING)?

A: AsciiDoc admonitions are converted to Textile paragraph blocks with appropriate CSS classes, such as p(note). or p(warning). This preserves the semantic meaning and allows styling through CSS in the target platform. The exact visual appearance depends on the CSS styles defined in your Textile rendering environment.

Q: Can I use the converted Textile in Redmine?

A: Absolutely! Redmine has built-in Textile support for wiki pages, issue descriptions, and comments. The converted Textile content can be directly pasted into Redmine. Headings, lists, tables, bold, italic, and links will render correctly. Code blocks using bc. notation are also natively supported.

Q: Are code blocks preserved during conversion?

A: Yes, AsciiDoc code blocks (delimited by ----) are converted to Textile's bc. (block code) notation. Inline code using backticks is converted to Textile's @ delimiter. Note that Textile does not natively support syntax highlighting specification, so language hints from AsciiDoc source blocks are not preserved.

Q: What AsciiDoc features are not supported in Textile?

A: Some advanced AsciiDoc features have no direct Textile equivalent. These include include directives (modular content), conditional processing, attributes/variables, sidebar blocks, and table of contents generation. The converter handles these gracefully by converting the visible content while omitting directive-specific syntax.

Q: Is Textile still actively maintained?

A: Textile is in a stable, maintenance-mode state. While it is not receiving major new features, it remains fully functional and supported by platforms like Redmine (which continues active development). Libraries like RedCloth (Ruby) and PHP Textile are available for processing. For new projects, consider whether Textile or Markdown better fits your platform requirements.