Convert AsciiDoc to ADOC
Max file size 100mb.
AsciiDoc vs ADOC Format Comparison
| Aspect | AsciiDoc (Source Format) | ADOC (Target Format) |
|---|---|---|
| Format Overview |
AsciiDoc
AsciiDoc Markup Language
Lightweight markup language created by Stuart Rackham in 2002 for writing technical documentation, articles, books, and web pages. Uses intuitive plain-text syntax with = headings, *bold*, _italic_, listing blocks, admonitions, and cross-references. Processed by Asciidoctor. Markup Language Technical Docs |
ADOC
AsciiDoc File (.adoc extension)
The modern standard file extension for AsciiDoc documents. ADOC is the recommended extension by the Asciidoctor project and is universally recognized by editors, CI/CD pipelines, GitHub, and documentation tools. Content is identical to AsciiDoc; only the file extension differs. Standard Extension Asciidoctor |
| Technical Specifications |
Structure: Plain text with markup directives
Encoding: UTF-8 Format: Human-readable markup Compression: None Extensions: .asciidoc, .asc, .adoc |
Structure: Plain text with markup directives
Encoding: UTF-8 Format: Human-readable markup Compression: None Extensions: .adoc (preferred) |
| Syntax Examples |
AsciiDoc markup syntax: = Document Title
Author Name
:toc:
== Chapter One
This is *bold* and _italic_.
[source,python]
----
print("Hello")
----
|
Identical AsciiDoc syntax in .adoc file: = Document Title
Author Name
:toc:
== Chapter One
This is *bold* and _italic_.
[source,python]
----
print("Hello")
----
|
| Content Support |
|
|
| Advantages |
|
|
| Disadvantages |
|
|
| Common Uses |
|
|
| Best For |
|
|
| Version History |
Introduced: 2002 (Stuart Rackham)
Original Tool: AsciiDoc (Python) Status: Active, widely used Evolution: Asciidoctor (Ruby/JVM) since 2013 |
Introduced: .adoc recommended since Asciidoctor 1.0 (2013)
Current Standard: Preferred by Asciidoctor 2.x Status: Modern standard extension Evolution: Gradually replacing .asciidoc and .asc |
| Software Support |
Asciidoctor: Full support
GitHub: Renders .asciidoc files VS Code: AsciiDoc extension support Other: IntelliJ, Atom, Sublime Text |
Asciidoctor: Full support (preferred)
GitHub: Renders .adoc files natively VS Code: Full AsciiDoc extension support Other: IntelliJ, Atom, all modern editors |
Why Convert AsciiDoc to ADOC?
Converting AsciiDoc files from the .asciidoc or .asc extension to the modern .adoc extension is a recommended practice for standardizing your documentation projects. The Asciidoctor project, which has become the de facto standard for processing AsciiDoc content, officially recommends the .adoc extension for all new documents. This conversion ensures your files follow current best practices and are instantly recognized by modern tooling.
The .adoc extension was introduced alongside the Asciidoctor processor to provide a shorter, cleaner alternative to the original .asciidoc extension. While the content remains identical -- AsciiDoc markup with = headings, *bold*, _italic_, listing blocks (----), admonitions (NOTE:, TIP:), includes, and cross-references -- the .adoc extension is more concise and is the default expected by GitHub, GitLab, CI/CD pipelines, and IDE plugins.
Many organizations including Red Hat, the Spring Framework team, and O'Reilly Media have standardized on the .adoc extension for their documentation repositories. GitHub automatically renders .adoc files with full AsciiDoc formatting, making it easy to host rich documentation directly in your repository. Using the standard .adoc extension ensures seamless integration with these platforms.
This conversion is purely a file extension rename -- no content transformation is needed. However, after renaming, you should update any include directives, cross-references, or build scripts that reference the old file extension to maintain a consistent and functional documentation pipeline.
Key Benefits of Converting AsciiDoc to ADOC:
- Modern Standard: Follows Asciidoctor's recommended file extension
- GitHub Integration: Automatic rendering and syntax highlighting on GitHub
- Shorter Extension: Concise .adoc vs verbose .asciidoc
- Tooling Support: Better IDE and editor plugin recognition
- CI/CD Compatibility: Standard extension for documentation build pipelines
- Industry Adoption: Used by Red Hat, Spring, O'Reilly, and more
- Future-Proof: The .adoc extension is the direction the ecosystem is moving
Practical Examples
Example 1: Technical Documentation Header
Input AsciiDoc file (guide.asciidoc):
= Installation Guide :author: Jane Smith :revdate: 2025-01-15 :toc: left :icons: font == Prerequisites Before installing, ensure you have: * Java 17 or later * Maven 3.8+ * Git
Output ADOC file (guide.adoc):
= Installation Guide :author: Jane Smith :revdate: 2025-01-15 :toc: left :icons: font == Prerequisites Before installing, ensure you have: * Java 17 or later * Maven 3.8+ * Git (Identical content, .adoc extension)
Example 2: Code Block with Admonitions
Input AsciiDoc file (api-reference.asciidoc):
== API Configuration NOTE: All endpoints require authentication. [source,yaml] ---- server: port: 8080 context-path: /api/v2 ---- TIP: Use environment variables for sensitive values.
Output ADOC file (api-reference.adoc):
== API Configuration NOTE: All endpoints require authentication. [source,yaml] ---- server: port: 8080 context-path: /api/v2 ---- TIP: Use environment variables for sensitive values. (Same content, modern .adoc extension)
Example 3: Document with Includes and Cross-References
Input AsciiDoc file (book.asciidoc):
= My Technical Book :doctype: book include::chapters/chapter1.asciidoc[] include::chapters/chapter2.asciidoc[] See <<chapter1>> for details.
Output ADOC file (book.adoc):
= My Technical Book :doctype: book include::chapters/chapter1.adoc[] include::chapters/chapter2.adoc[] See <<chapter1>> for details. (Include paths updated to .adoc extension)
Frequently Asked Questions (FAQ)
Q: What is the difference between .asciidoc and .adoc?
A: There is no difference in content or syntax -- both extensions represent AsciiDoc markup files. The .adoc extension is simply shorter and is the modern recommended standard by the Asciidoctor project. The .asciidoc extension is the original, longer form.
Q: Will my content change when converting from .asciidoc to .adoc?
A: No. The conversion is purely a file extension change. All your AsciiDoc markup -- headings, formatting, code blocks, admonitions, tables, includes, and cross-references -- remains completely unchanged. The document content is preserved exactly as-is.
Q: Why does the Asciidoctor project recommend .adoc?
A: The Asciidoctor project recommends .adoc because it is shorter, easier to type, and has become the universally recognized extension in the AsciiDoc ecosystem. It is also the default extension expected by GitHub, GitLab, and most documentation build tools.
Q: Do I need to update my include directives after renaming?
A: Yes, if your documents use include directives that reference files by their old extension (e.g., include::chapter.asciidoc[]), you should update these references to use the .adoc extension. Otherwise, the includes will fail during document processing.
Q: Does GitHub support .adoc files?
A: Yes! GitHub natively renders .adoc files with full AsciiDoc formatting, including headings, tables, code blocks, admonitions, and more. Both .adoc and .asciidoc extensions are supported, but .adoc is more commonly used in GitHub repositories.
Q: What is AsciiDoc used for?
A: AsciiDoc is used for writing technical documentation, user manuals, API references, books, articles, and any structured content. It is used by major organizations including Red Hat, the Spring Framework, Eclipse Foundation, and O'Reilly Media for their documentation needs.
Q: Can I use .adoc files with the original AsciiDoc (Python) processor?
A: Yes, the original AsciiDoc Python processor recognizes .adoc files. However, the original Python implementation is no longer maintained. The Asciidoctor project (Ruby/JVM/JavaScript) is the actively maintained successor and fully supports .adoc files as its preferred extension.
Q: Should I convert all my .asciidoc files to .adoc at once?
A: It depends on your project. For new projects, use .adoc from the start. For existing projects, you can convert incrementally or all at once. If you convert all files, remember to update any build scripts, CI/CD configurations, and include directives that reference the old extension to avoid broken references.