Convert AsciiDoc to JSON

Why Convert AsciiDoc to JSON?

Converting AsciiDoc to JSON transforms human-readable documentation into machine-parseable structured data. This is essential when document content needs to be consumed by APIs, stored in databases, indexed by search engines, or processed by automated systems. The conversion extracts the semantic structure of an AsciiDoc document -- its headings, attributes, lists, tables, and text blocks -- into a hierarchical JSON representation.

JSON (JavaScript Object Notation) is the lingua franca of web services and data interchange. Standardized as ECMA-404 and RFC 8259, JSON is natively supported in every modern programming language and is the default format for REST APIs, NoSQL databases like MongoDB, and frontend frameworks. By converting AsciiDoc to JSON, you make documentation content programmatically accessible to any application or service in your technology stack.

AsciiDoc's structured nature makes it particularly well-suited for JSON conversion. Document attributes become JSON key-value pairs, section headings create nested objects, ordered and unordered lists map to JSON arrays, and definition lists produce key-value objects. Tables can be represented as arrays of objects where column headers become property names. This structural correspondence ensures that the conversion preserves the logical organization of your content.

Common use cases include building documentation search indexes, feeding content management systems, generating API response payloads from documentation, creating localization files for translation workflows, and powering dynamic documentation portals. Organizations like Elastic and Red Hat use similar pipelines to transform their AsciiDoc documentation into searchable, API-driven knowledge bases that serve millions of developers daily.

Key Benefits of Converting AsciiDoc to JSON:

• API Integration: Feed document content to REST APIs and microservices
• Database Storage: Import structured docs into MongoDB, Elasticsearch, or PostgreSQL
• Search Indexing: Build full-text search indexes from documentation content
• Programmatic Access: Parse and query document data in any programming language
• CMS Integration: Import content into headless CMS platforms like Strapi or Contentful
• Schema Validation: Validate document structure using JSON Schema
• Data Pipeline: Process documentation through ETL and data transformation workflows

Practical Examples

Example 1: API Documentation to JSON

Input AsciiDoc file (api-docs.adoc):

= User API
:version: 2.0
:base-url: https://api.example.com

== GET /users

Returns a list of all users.

.Parameters
|===
| Name | Type | Required

| page | integer | No
| limit | integer | No
|===

Output JSON file (api-docs.json):

{
  "title": "User API",
  "attributes": {
    "version": "2.0",
    "base-url": "https://api.example.com"
  },
  "sections": [
    {
      "heading": "GET /users",
      "content": "Returns a list of all users.",
      "tables": [
        {
          "title": "Parameters",
          "headers": ["Name", "Type", "Required"],
          "rows": [
            ["page", "integer", "No"],
            ["limit", "integer", "No"]
          ]
        }
      ]
    }
  ]
}

Example 2: Product Catalog Document

Input AsciiDoc file (catalog.adoc):

= Product Catalog
:category: Electronics

== Laptop Pro 15

Price:: $1,299
Display:: 15.6" 4K IPS
RAM:: 16GB DDR5
Storage:: 512GB NVMe SSD

== Tablet Ultra

Price:: $599
Display:: 11" OLED
RAM:: 8GB
Storage:: 256GB

Output JSON file (catalog.json):

{
  "title": "Product Catalog",
  "category": "Electronics",
  "products": [
    {
      "name": "Laptop Pro 15",
      "price": "$1,299",
      "display": "15.6\" 4K IPS",
      "ram": "16GB DDR5",
      "storage": "512GB NVMe SSD"
    },
    {
      "name": "Tablet Ultra",
      "price": "$599",
      "display": "11\" OLED",
      "ram": "8GB",
      "storage": "256GB"
    }
  ]
}

Example 3: Knowledge Base Article

Input AsciiDoc file (troubleshooting.adoc):

= Troubleshooting Guide
:tags: support, networking

== Connection Timeout

Check the following:

. Verify firewall rules
. Test DNS resolution
. Confirm port availability

NOTE: Default timeout is 30 seconds.

== Memory Issues

Increase heap size in `config.yml`.

Output JSON file (troubleshooting.json):

{
  "title": "Troubleshooting Guide",
  "tags": ["support", "networking"],
  "articles": [
    {
      "heading": "Connection Timeout",
      "steps": [
        "Verify firewall rules",
        "Test DNS resolution",
        "Confirm port availability"
      ],
      "note": "Default timeout is 30 seconds."
    },
    {
      "heading": "Memory Issues",
      "content": "Increase heap size in config.yml."
    }
  ]
}

Frequently Asked Questions (FAQ)

Q: How is the AsciiDoc document structure mapped to JSON?

A: The conversion creates a hierarchical JSON object that mirrors the document's structure. The document title becomes a top-level property, attributes become a key-value object, sections become an array of objects with heading and content properties, lists become arrays, tables become arrays of objects, and definition lists become key-value pairs.

Q: Can I validate the JSON output against a schema?

A: Yes. JSON Schema (json-schema.org) lets you define the expected structure of your JSON output and validate it programmatically. This is useful for ensuring consistency when converting multiple AsciiDoc documents into a standardized JSON format. Libraries like ajv (JavaScript), jsonschema (Python), and everit-org/json-schema (Java) support validation.

Q: Is the JSON output minified or pretty-printed?

A: By default, the output is pretty-printed with indentation for readability. For production use where file size matters, you can minify the JSON by removing whitespace. Most JSON libraries support both modes: Python's json.dumps(data, indent=2) for pretty-printing and json.dumps(data, separators=(',', ':')) for minification.

Q: How are AsciiDoc tables converted to JSON?

A: Tables are typically converted to arrays of objects, where each row becomes an object and column headers become property names. For example, a table with columns "Name", "Type", "Required" produces objects like {"Name": "page", "Type": "integer", "Required": "No"}. This structure is ideal for programmatic consumption.

Q: Can I import the JSON into MongoDB?

A: Yes. JSON is MongoDB's native data format. You can import the converted JSON directly using mongoimport or insert it via MongoDB drivers in any programming language. The hierarchical structure of the JSON output maps naturally to MongoDB documents, making it an excellent pipeline for building searchable documentation databases.

Q: What happens to AsciiDoc formatting (bold, italic) in JSON?

A: Inline formatting can be handled in two ways: stripped to plain text (for clean data extraction) or preserved as markup strings (for rendering later). The default approach typically strips formatting to produce clean JSON values. If you need to preserve formatting, the content can be stored as HTML fragments within JSON string values.

Q: How large are the resulting JSON files?

A: JSON output is typically similar in size to the AsciiDoc source for text-heavy documents, plus overhead from JSON syntax (braces, brackets, quotes, property names). Pretty-printed JSON is larger due to indentation. Minified JSON is usually comparable to or smaller than the original AsciiDoc. Images are not embedded in the JSON by default.

Q: Can I convert JSON back to AsciiDoc?

A: Round-trip conversion is possible if the JSON preserves sufficient structural information. A JSON object with title, sections, and content properties can be rendered back to AsciiDoc syntax. However, some formatting nuances and AsciiDoc-specific features may not survive the round trip. For lossless round-tripping, store the original AsciiDoc source alongside the JSON.