Convert ADOC to AsciiDoc
Max file size 100mb.
ADOC vs AsciiDoc Format Comparison
| Aspect | ADOC (Source Format) | AsciiDoc (Target Format) |
|---|---|---|
| Format Overview |
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 |
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 |
| Technical Specifications |
Structure: Plain text with markup directives
Encoding: UTF-8 Format: Human-readable markup Compression: None Extensions: .adoc (preferred) |
Structure: Plain text with markup directives
Encoding: UTF-8 Format: Human-readable markup Compression: None Extensions: .asciidoc, .asc, .adoc |
| Syntax Examples |
AsciiDoc syntax in .adoc file: = Document Title
Author Name
:toc:
== Chapter One
This is *bold* and _italic_.
[source,python]
----
print("Hello")
----
|
Identical AsciiDoc syntax in .asciidoc 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: .adoc recommended since Asciidoctor 1.0 (2013)
Current Standard: Preferred by Asciidoctor 2.x Status: Modern standard extension Evolution: Gradually replacing .asciidoc and .asc |
Introduced: 2002 (Stuart Rackham)
Original Tool: AsciiDoc (Python) Status: Active, widely used Evolution: Asciidoctor (Ruby/JVM) since 2013 |
| Software Support |
Asciidoctor: Full support (preferred)
GitHub: Renders .adoc files natively VS Code: Full AsciiDoc extension support Other: IntelliJ, Atom, all modern editors |
Asciidoctor: Full support
GitHub: Renders .asciidoc files VS Code: AsciiDoc extension support Other: IntelliJ, Atom, Sublime Text |
Why Convert ADOC to AsciiDoc?
Converting ADOC files from the modern .adoc extension to the original .asciidoc extension is useful for projects that require the full, descriptive file extension for compatibility or stylistic reasons. The .asciidoc extension is the original extension used by the AsciiDoc markup language created by Stuart Rackham in 2002, and some legacy toolchains and projects still expect this longer form.
The .asciidoc extension is completely self-documenting -- anyone encountering a .asciidoc file immediately understands the format without needing any context. This explicitness can be valuable in organizations where not all team members are familiar with the .adoc abbreviation, or in file systems where clear, unambiguous naming is a requirement.
Some legacy documentation build systems, older CI/CD pipelines, and projects that predate the Asciidoctor project may be configured to specifically look for .asciidoc files. Converting from .adoc to .asciidoc ensures compatibility with these systems without requiring changes to build configurations, Makefiles, or automation scripts.
This conversion is purely a file extension change -- no content transformation is needed. The AsciiDoc markup syntax (= headings, *bold*, _italic_, listing blocks, admonitions, includes, cross-references) remains completely identical regardless of whether the file uses the .adoc or .asciidoc extension. Both are processed identically by Asciidoctor and other AsciiDoc processors.
Key Benefits of Converting ADOC to AsciiDoc:
- Self-Documenting: The .asciidoc extension immediately identifies the file format
- Legacy Compatibility: Works with older toolchains expecting .asciidoc files
- Explicit Naming: No ambiguity about the file format
- Build System Compatibility: Matches configurations that look for .asciidoc
- Project Consistency: Standardize to .asciidoc if your project uses that convention
- Original Convention: Uses the extension from the original AsciiDoc project
- Zero Content Loss: All AsciiDoc markup preserved exactly as-is
Practical Examples
Example 1: Technical Documentation Header
Input 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
Output 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 (Identical content, .asciidoc extension)
Example 2: Code Block with Admonitions
Input 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.
Output 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. (Same content, original .asciidoc extension)
Example 3: Document with Includes and Cross-References
Input ADOC file (book.adoc):
= My Technical Book :doctype: book include::chapters/chapter1.adoc[] include::chapters/chapter2.adoc[] See <<chapter1>> for details.
Output AsciiDoc file (book.asciidoc):
= My Technical Book :doctype: book include::chapters/chapter1.asciidoc[] include::chapters/chapter2.asciidoc[] See <<chapter1>> for details. (Include paths updated to .asciidoc extension)
Frequently Asked Questions (FAQ)
Q: What is the difference between .adoc and .asciidoc?
A: There is no difference in content or syntax -- both extensions represent AsciiDoc markup files. The .adoc extension is the modern, shorter form recommended by the Asciidoctor project. The .asciidoc extension is the original, longer form that is more descriptive and self-documenting.
Q: Will my content change when converting from .adoc to .asciidoc?
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 would I use .asciidoc instead of .adoc?
A: You might prefer .asciidoc for legacy compatibility with older build systems, for self-documenting filenames that are immediately recognizable, or to match an existing project convention. Some organizations standardize on .asciidoc for consistency with documentation that predates the .adoc convention.
Q: Do I need to update my include directives after renaming?
A: Yes, if your documents use include directives that reference files by their .adoc extension (e.g., include::chapter.adoc[]), you should update these references to use the .asciidoc extension. Otherwise, the includes will fail during document processing.
Q: Does GitHub support .asciidoc files?
A: Yes! GitHub natively renders .asciidoc files with full AsciiDoc formatting, including headings, tables, code blocks, admonitions, and more. Both .adoc and .asciidoc extensions are supported and rendered identically on GitHub.
Q: Does Asciidoctor support the .asciidoc extension?
A: Yes, Asciidoctor fully supports the .asciidoc extension. While Asciidoctor recommends .adoc for new projects, the processor handles .asciidoc, .adoc, and .asc files identically. All AsciiDoc features work the same regardless of the file extension.
Q: Can I use .asciidoc files with the original AsciiDoc (Python) processor?
A: Yes, the .asciidoc extension was the original default for the Python-based AsciiDoc processor. While that implementation is no longer maintained, many legacy projects still use it. The Asciidoctor project (Ruby/JVM/JavaScript) is the actively maintained successor and supports all AsciiDoc file extensions.
Q: Should I convert all my .adoc files to .asciidoc?
A: Only if your project specifically requires or prefers the .asciidoc extension. For new projects, the Asciidoctor community recommends .adoc. However, if you are maintaining a legacy project that uses .asciidoc, or if your build system is configured for .asciidoc files, converting to match the existing convention makes sense for consistency.