Convert XLSX to AsciiDoc

Why Convert XLSX to AsciiDoc?

Converting XLSX to AsciiDoc brings your spreadsheet data into the documentation-as-code workflow. AsciiDoc is the format of choice for O'Reilly Media publications, Spring Framework documentation, and countless open-source projects. By converting Excel data to AsciiDoc tables, you can include structured data in professional-quality documentation that renders beautifully across HTML, PDF, and EPUB outputs.

The conversion is especially valuable for teams that maintain their documentation in Git repositories. Unlike binary XLSX files that create opaque blobs in version control, AsciiDoc tables are plain text that produces clean, reviewable diffs. Code reviewers can easily see exactly which rows or values changed in each commit, making collaborative documentation editing practical and transparent.

AsciiDoc tables are also significantly more powerful than Markdown tables. They support column width specifications, cell alignment, header and footer rows, column and row spanning, and even nested content within cells. This means your converted Excel data can be further enhanced with AsciiDoc features that have no equivalent in simpler markup languages.

Our converter extracts data from the XLSX workbook and generates clean AsciiDoc table markup with appropriate column specifications and header detection. The output integrates seamlessly with Asciidoctor, Antora, and other AsciiDoc processing tools.

Key Benefits of Converting XLSX to AsciiDoc:

• Docs-as-Code: Integrate spreadsheet data into documentation-as-code workflows
• Git-Friendly: Plain text tables produce meaningful diffs in version control
• Rich Tables: AsciiDoc tables support spans, alignment, and formatting beyond Markdown
• Multi-Output: Render the same source to HTML, PDF, EPUB, and DocBook
• Professional Publishing: Compatible with O'Reilly and technical book publishing tools
• Modular: Include converted tables in larger documents via include directives

Practical Examples

Example 1: API Endpoints Reference

Input XLSX file (api_endpoints.xlsx):

Excel Spreadsheet - Sheet1:
+--------+------------------+-------------+------------------+
| Method | Endpoint         | Auth        | Description      |
+--------+------------------+-------------+------------------+
| GET    | /api/users       | Bearer Token| List all users   |
| POST   | /api/users       | Bearer Token| Create new user  |
| GET    | /api/users/{id}  | Bearer Token| Get user details |
| DELETE | /api/users/{id}  | Admin Only  | Delete user      |
+--------+------------------+-------------+------------------+

Output AsciiDoc file (api_endpoints.adoc):

.API Endpoints
[cols="1,2,1,2", options="header"]
|===
| Method | Endpoint        | Auth         | Description
| GET    | /api/users      | Bearer Token | List all users
| POST   | /api/users      | Bearer Token | Create new user
| GET    | /api/users/{id} | Bearer Token | Get user details
| DELETE | /api/users/{id} | Admin Only   | Delete user
|===

Example 2: Software Version Matrix

Input XLSX file (versions.xlsx):

Excel Spreadsheet - Sheet1:
+------------+---------+--------+--------+
| Component  | v1.0    | v2.0   | v3.0   |
+------------+---------+--------+--------+
| Java       | 8       | 11     | 17     |
| Spring     | 4.3     | 5.2    | 6.0    |
| PostgreSQL | 10      | 13     | 15     |
| Redis      | 4.0     | 6.0    | 7.0    |
+------------+---------+--------+--------+

Output AsciiDoc file (versions.adoc):

.Software Version Matrix
[cols="2,1,1,1", options="header"]
|===
| Component  | v1.0 | v2.0 | v3.0
| Java       | 8    | 11   | 17
| Spring     | 4.3  | 5.2  | 6.0
| PostgreSQL | 10   | 13   | 15
| Redis      | 4.0  | 6.0  | 7.0
|===

Example 3: Release Notes Summary

Input XLSX file (releases.xlsx):

Excel Spreadsheet - Sheet1:
+---------+------------+-------+-------------------------+
| Version | Date       | Type  | Highlights              |
+---------+------------+-------+-------------------------+
| 3.2.1   | 2025-03-01 | Patch | Bug fixes, security     |
| 3.2.0   | 2025-02-15 | Minor | New API, performance    |
| 3.1.0   | 2025-01-10 | Minor | Dashboard redesign      |
+---------+------------+-------+-------------------------+

Output AsciiDoc file (releases.adoc):

.Release Notes
[cols="1,1,1,3", options="header"]
|===
| Version | Date       | Type  | Highlights
| 3.2.1   | 2025-03-01 | Patch | Bug fixes, security
| 3.2.0   | 2025-02-15 | Minor | New API, performance
| 3.1.0   | 2025-01-10 | Minor | Dashboard redesign
|===

Frequently Asked Questions (FAQ)

Q: What is the difference between ADOC and AsciiDoc?

A: ADOC and AsciiDoc refer to the same format. ".adoc" is the most common file extension for AsciiDoc files, while ".asciidoc" is a longer alternative extension. Both are processed identically by Asciidoctor and other AsciiDoc processors. The format name is "AsciiDoc" and the conventional file extension is ".adoc".

Q: How are Excel column widths translated to AsciiDoc?

A: The converter generates proportional column width specifications in the AsciiDoc cols attribute based on the content width in each column. For example, a table with a wide description column and narrow ID column might produce [cols="1,3"]. You can adjust these proportions after conversion to fine-tune the layout.

Q: Can I convert multiple Excel sheets at once?

A: The converter processes the first worksheet by default. If you need data from multiple sheets, you can convert each sheet separately or rearrange the workbook so the desired sheet is first. Each sheet will produce a separate AsciiDoc table block.

Q: Does the AsciiDoc output include a table title?

A: The converter generates the table with header row detection. You can add a title by placing a line starting with a period before the table block (e.g., .My Table Title). This title will appear as a caption when the AsciiDoc is rendered to HTML or PDF.

Q: What tools can I use to render the AsciiDoc output?

A: The primary tool is Asciidoctor, available as a Ruby gem, npm package (asciidoctor.js), or Java library (AsciidoctorJ). You can render to HTML with asciidoctor file.adoc, to PDF with asciidoctor-pdf file.adoc, or use VS Code with the AsciiDoc extension for live preview.

Q: Are special characters in Excel cells escaped properly?

A: Yes, the converter escapes AsciiDoc special characters such as pipe symbols (|) within cell content to prevent them from being interpreted as column separators. Other special characters like asterisks and underscores are also handled to avoid unintended formatting.

Q: Can I include the converted file in an Antora documentation site?

A: Yes, the output is fully compatible with Antora, the multi-repository documentation site generator for AsciiDoc. Place the converted file in your Antora module's pages or partials directory and include it using standard AsciiDoc include directives.

Q: How does this differ from manually copying Excel data?

A: Manual copying requires reformatting every cell into AsciiDoc pipe syntax, which is tedious and error-prone for large tables. Our converter automates the entire process, handling header detection, column specifications, character escaping, and proper AsciiDoc table syntax in seconds.