Convert AsciiDoc to CSV

Why Convert AsciiDoc to CSV?

Converting AsciiDoc to CSV is valuable when you need to extract tabular data from your documentation for analysis, reporting, or import into spreadsheet applications and databases. AsciiDoc documents frequently contain data tables with configuration parameters, API endpoints, comparison matrices, or status reports that need to be processed in Excel, Google Sheets, or data analysis tools like Python pandas.

AsciiDoc tables use a pipe-delimited syntax (|===) that is excellent for documentation but not directly importable into data processing tools. The conversion extracts table content from AsciiDoc's markup format and transforms it into clean CSV with proper comma separation, quoted fields where necessary, and standard RFC 4180 formatting. This enables seamless data exchange between documentation systems and analytical tools.

This conversion is particularly useful in scenarios where documentation serves as the single source of truth for configuration data, feature comparison matrices, or API endpoint catalogs. Engineering teams often maintain tables in AsciiDoc that also need to be processed programmatically. Converting to CSV creates a machine-readable extract that can feed into automated testing, monitoring dashboards, or database seeding scripts.

When converting AsciiDoc to CSV, the process extracts tabular content while stripping markup formatting such as bold, italic, and links. Non-table content (paragraphs, headings, code blocks, admonitions) is either converted to a flat text representation or excluded depending on the conversion settings. For documents with multiple tables, each table can be extracted as a separate CSV section or file.

Key Benefits of Converting AsciiDoc to CSV:

• Data Extraction: Pull structured data from documentation tables
• Spreadsheet Import: Open AsciiDoc table data in Excel or Google Sheets
• Database Loading: Import documentation data into SQL databases
• Data Analysis: Process table data with pandas, R, or other tools
• Automation: Feed documentation data into CI/CD pipelines
• Reporting: Generate reports from documented data tables
• Universal Format: CSV works with virtually every data tool

Practical Examples

Example 1: API Endpoint Documentation

Input AsciiDoc file (api-endpoints.adoc):

= API Endpoints

|===
| Endpoint | Method | Auth | Description
| /api/users | GET | Bearer | List all users
| /api/users/{id} | GET | Bearer | Get user details
| /api/users | POST | Bearer | Create new user
| /api/login | POST | None | Authenticate user
|===

Output CSV file (api-endpoints.csv):

Endpoint,Method,Auth,Description
/api/users,GET,Bearer,List all users
/api/users/{id},GET,Bearer,Get user details
/api/users,POST,Bearer,Create new user
/api/login,POST,None,Authenticate user

Example 2: Configuration Parameters

Input AsciiDoc file (config-reference.adoc):

== Configuration Parameters

|===
| Parameter | Default | Type | Description
| server.port | 8080 | Integer | HTTP listen port
| db.host | localhost | String | Database hostname
| db.pool.size | 10 | Integer | Connection pool size
| cache.ttl | 3600 | Integer | Cache TTL in seconds
|===

Output CSV file (config-reference.csv):

Parameter,Default,Type,Description
server.port,8080,Integer,HTTP listen port
db.host,localhost,String,Database hostname
db.pool.size,10,Integer,Connection pool size
cache.ttl,3600,Integer,Cache TTL in seconds

Example 3: Feature Comparison Matrix

Input AsciiDoc file (comparison.adoc):

== Feature Comparison

|===
| Feature | Free Plan | Pro Plan | Enterprise
| Users | 5 | 50 | Unlimited
| Storage | 1 GB | 100 GB | 1 TB
| Support | Email | Priority | Dedicated
| API Access | No | Yes | Yes
|===

Output CSV file (comparison.csv):

Feature,Free Plan,Pro Plan,Enterprise
Users,5,50,Unlimited
Storage,1 GB,100 GB,1 TB
Support,Email,Priority,Dedicated
API Access,No,Yes,Yes

Frequently Asked Questions (FAQ)

Q: What is CSV format?

A: CSV (Comma-Separated Values) is a plain text format for storing tabular data. Each line represents a row, and values within a row are separated by commas. Fields containing commas, newlines, or quotes are enclosed in double quotes. CSV is defined in RFC 4180 and is universally supported by spreadsheet applications and databases.

Q: Which parts of an AsciiDoc document are converted to CSV?

A: The conversion primarily extracts tabular data from AsciiDoc table blocks (|=== delimited sections). Non-table content such as headings, paragraphs, code blocks, and admonitions may be converted to a flat text representation or excluded. Tables are the primary source of structured data suitable for CSV format.

Q: How are AsciiDoc table headers handled?

A: AsciiDoc table headers (the first row after |===) are preserved as the first row of the CSV output. In AsciiDoc, header rows are typically styled differently, but in CSV they appear as a standard data row. Most spreadsheet applications will recognize the first row as headers when importing.

Q: What happens to formatting inside table cells?

A: Markup formatting within AsciiDoc table cells (such as *bold*, _italic_, links, and inline code) is stripped during CSV conversion, leaving only the plain text content. CSV is a data-only format that does not support text styling or formatting.

Q: Can I open the CSV output in Excel?

A: Yes! CSV files can be opened directly in Microsoft Excel, Google Sheets, LibreOffice Calc, Apple Numbers, and virtually any spreadsheet application. Simply double-click the .csv file or use the application's import function for more control over delimiters and encoding.

Q: How are commas in AsciiDoc cell data handled?

A: If an AsciiDoc table cell contains commas, the CSV output encloses that field in double quotes as per RFC 4180. This ensures the comma within the data is not confused with the field separator. For example, "New York, NY" would appear as a properly quoted CSV field.

Q: What about AsciiDoc documents with multiple tables?

A: Documents with multiple AsciiDoc tables can have each table extracted separately. The tables may be combined into a single CSV with section separators, or each table can be exported as an individual CSV file. This depends on the conversion settings chosen.

Q: Can I convert AsciiDoc CSV-format tables?

A: Yes. AsciiDoc supports a CSV table format using [%header,format=csv] followed by the |=== delimiter. These tables already contain comma-separated data and convert very naturally to CSV format, often requiring minimal transformation beyond removing the AsciiDoc table delimiters.