Convert XLSX to ADOC

Why Convert XLSX to ADOC?

Converting XLSX to AsciiDoc enables you to incorporate Excel spreadsheet data directly into technical documentation projects. AsciiDoc is the preferred markup language for many software documentation systems, and having your tabular data in AsciiDoc table format means it can be seamlessly included in manuals, specifications, and knowledge base articles.

One of the primary advantages of this conversion is version control compatibility. XLSX files are binary archives that produce meaningless diffs in Git and other version control systems. By converting your spreadsheet data to AsciiDoc, every change to the table content becomes visible in commit histories, making it easy to track who changed what data and when.

AsciiDoc tables also benefit from the full AsciiDoc publishing pipeline. Once your Excel data is in AsciiDoc format, you can render it to HTML, PDF, EPUB, or DocBook with consistent styling. This is particularly valuable for generating reports, data appendices, or reference tables that need to appear in multiple output formats from a single source.

Our converter reads the XLSX workbook, extracts the data from the first sheet, and generates a properly formatted AsciiDoc table with header row detection and column alignment. The output is clean, readable AsciiDoc markup that can be directly pasted into any documentation project.

Key Benefits of Converting XLSX to ADOC:

• Documentation Integration: Embed Excel data directly in AsciiDoc technical documents
• Version Control: Track changes to table data in Git with meaningful diffs
• Multi-Format Output: Generate HTML, PDF, and EPUB from a single AsciiDoc source
• Plain Text: Edit table data with any text editor, no special software needed
• Portable: Lightweight text format that works across all platforms
• Publishing Ready: Directly usable in Asciidoctor-based publishing workflows

Practical Examples

Example 1: Employee Directory

Input XLSX file (employees.xlsx):

Excel Spreadsheet - Sheet1:
+--------+-----------+-------------+--------+
| Name   | Title     | Department  | Ext    |
+--------+-----------+-------------+--------+
| Alice  | Engineer  | R&D         | 1201   |
| Bob    | Designer  | UX          | 1305   |
| Carol  | Manager   | Operations  | 1102   |
+--------+-----------+-------------+--------+

Output ADOC file (employees.adoc):

[cols="1,1,1,1", options="header"]
|===
| Name  | Title    | Department | Ext
| Alice | Engineer | R&D        | 1201
| Bob   | Designer | UX         | 1305
| Carol | Manager  | Operations | 1102
|===

Example 2: Project Timeline

Input XLSX file (timeline.xlsx):

Excel Spreadsheet - Sheet1:
+-----------+------------------+------------+------------+--------+
| Phase     | Task             | Start Date | End Date   | Status |
+-----------+------------------+------------+------------+--------+
| Planning  | Requirements     | 2025-01-01 | 2025-01-15 | Done   |
| Design    | UI Mockups       | 2025-01-16 | 2025-02-01 | Done   |
| Dev       | Backend API      | 2025-02-02 | 2025-03-15 | Active |
| Testing   | QA Validation    | 2025-03-16 | 2025-04-01 | Pending|
+-----------+------------------+------------+------------+--------+

Output ADOC file (timeline.adoc):

[cols="1,2,1,1,1", options="header"]
|===
| Phase    | Task           | Start Date | End Date   | Status
| Planning | Requirements   | 2025-01-01 | 2025-01-15 | Done
| Design   | UI Mockups     | 2025-01-16 | 2025-02-01 | Done
| Dev      | Backend API    | 2025-02-02 | 2025-03-15 | Active
| Testing  | QA Validation  | 2025-03-16 | 2025-04-01 | Pending
|===

Example 3: Server Configuration Reference

Input XLSX file (servers.xlsx):

Excel Spreadsheet - Sheet1:
+----------+----------------+------+-------+-----------+
| Hostname | IP Address     | CPU  | RAM   | OS        |
+----------+----------------+------+-------+-----------+
| web-01   | 192.168.1.10   | 4    | 16 GB | Ubuntu 22 |
| db-01    | 192.168.1.20   | 8    | 64 GB | CentOS 9  |
| cache-01 | 192.168.1.30   | 2    | 8 GB  | Debian 12 |
+----------+----------------+------+-------+-----------+

Output ADOC file (servers.adoc):

[cols="1,2,1,1,1", options="header"]
|===
| Hostname | IP Address   | CPU | RAM   | OS
| web-01   | 192.168.1.10 | 4   | 16 GB | Ubuntu 22
| db-01    | 192.168.1.20 | 8   | 64 GB | CentOS 9
| cache-01 | 192.168.1.30 | 2   | 8 GB  | Debian 12
|===

Frequently Asked Questions (FAQ)

Q: What is AsciiDoc format?

A: AsciiDoc is a lightweight, text-based markup language designed for writing documentation, articles, and books. It uses simple syntax like Markdown but offers more advanced features such as tables with column spans, admonition blocks, cross-references, and include directives. AsciiDoc documents can be processed by Asciidoctor into HTML, PDF, EPUB, DocBook, and man pages.

Q: Which worksheet is converted from the XLSX file?

A: The converter processes the first (active) worksheet in the XLSX workbook. If your file contains multiple sheets, the data from the first sheet will be extracted and converted into an AsciiDoc table. You can reorder sheets in Excel before conversion if you need a different sheet converted.

Q: Are Excel formulas preserved in the AsciiDoc output?

A: AsciiDoc does not support formulas or calculations. The converter extracts the computed values from formula cells and includes the results as plain text in the AsciiDoc table. The formula expressions themselves are not transferred.

Q: How are merged cells handled?

A: Merged cells in the XLSX file are unmerged during conversion. The content of the merged cell appears in the first cell position, and the remaining cells that were part of the merge are left empty. AsciiDoc supports column and row spans, but the automatic conversion fills individual cells for simplicity.

Q: Can I customize the AsciiDoc table styling?

A: The generated AsciiDoc table uses standard table syntax with the header option enabled. After conversion, you can easily modify the table attributes to add column widths, alignment, formatting, and other AsciiDoc table features. The plain text format makes manual adjustments straightforward.

Q: Is cell formatting (bold, colors) preserved?

A: Cell formatting such as bold text, font colors, and background colors from the Excel file is not preserved in the AsciiDoc output. AsciiDoc tables contain plain text data. However, you can apply AsciiDoc inline formatting (bold, italic, monospace) to individual cells after conversion.

Q: How does the converter handle large spreadsheets?

A: The converter processes spreadsheets of any reasonable size. However, very large tables (hundreds of rows) can make the AsciiDoc file lengthy. For extremely large datasets, consider splitting the data into multiple tables or using AsciiDoc include directives to organize the content across separate files.

Q: Can I use the output with Asciidoctor directly?

A: Yes, the generated AsciiDoc markup is fully compatible with Asciidoctor and can be rendered immediately to HTML or PDF. You can include the file in larger AsciiDoc documents using the include::[] directive, making it easy to integrate spreadsheet data into technical documentation projects.