Convert ADOC to JSON

Why Convert ADOC to JSON?

Converting AsciiDoc (ADOC) files to JSON format bridges the gap between human-readable documentation and machine-processable data. While AsciiDoc excels at creating structured, readable documentation with rich formatting, JSON provides the universal data format needed for APIs, web applications, content management systems, and automated processing pipelines.

JSON (JavaScript Object Notation) has become the de facto standard for data interchange on the web. By converting your AsciiDoc documentation to JSON, you unlock the ability to serve content through REST APIs, import into headless CMS platforms, index in search engines like Elasticsearch, and integrate with modern web frameworks like React, Vue, or Next.js.

The conversion process extracts the semantic structure of your AsciiDoc documents—headings, paragraphs, lists, code blocks, tables, and metadata—and represents them as structured JSON objects. This preserves the document hierarchy while making it accessible to any programming language or platform that can parse JSON.

This conversion is particularly valuable for documentation-as-code workflows, where you author content in AsciiDoc for its excellent writing experience, then convert to JSON for programmatic consumption by documentation portals, API reference sites, or content delivery networks.

Key Benefits of Converting ADOC to JSON:

• API Integration: Serve documentation content through REST APIs for web and mobile apps
• Headless CMS: Import structured content into Contentful, Strapi, or Sanity
• Search Indexing: Index documentation in Elasticsearch or Algolia for full-text search
• Static Site Generators: Use as data source for Next.js, Gatsby, or Nuxt
• Content Automation: Enable automated translation, validation, or analysis
• Universal Compatibility: Works with every programming language and platform
• Structured Extraction: Extract specific sections or metadata programmatically

Practical Examples

Example 1: API Documentation to JSON Response

Input ADOC file (api-docs.adoc):

= User API Endpoint
:author: API Team
:version: 2.0

== GET /users/{id}

Retrieves a user by their unique identifier.

=== Parameters

|===
| Name | Type | Description

| id
| integer
| The unique user identifier
|===

=== Response

Returns a user object with profile information.

Output JSON file (api-docs.json):

{
  "title": "User API Endpoint",
  "metadata": {
    "author": "API Team",
    "version": "2.0"
  },
  "sections": [
    {
      "heading": "GET /users/{id}",
      "level": 2,
      "content": "Retrieves a user by their unique identifier.",
      "subsections": [
        {
          "heading": "Parameters",
          "level": 3,
          "table": {
            "headers": ["Name", "Type", "Description"],
            "rows": [["id", "integer", "The unique user identifier"]]
          }
        },
        {
          "heading": "Response",
          "level": 3,
          "content": "Returns a user object with profile information."
        }
      ]
    }
  ]
}

Example 2: Tutorial Content for CMS Import

Input ADOC file (tutorial.adoc):

= Getting Started with Python
:tags: python, tutorial, beginner
:published: 2024-01-15

== Introduction

Python is a versatile programming language.

== Installation

. Download Python from python.org
. Run the installer
. Verify with `python --version`

== Your First Program

[source,python]
----
print("Hello, World!")
----

Output JSON file (tutorial.json):

{
  "title": "Getting Started with Python",
  "metadata": {
    "tags": ["python", "tutorial", "beginner"],
    "published": "2024-01-15"
  },
  "sections": [
    {
      "heading": "Introduction",
      "content": "Python is a versatile programming language."
    },
    {
      "heading": "Installation",
      "list": {
        "ordered": true,
        "items": [
          "Download Python from python.org",
          "Run the installer",
          "Verify with `python --version`"
        ]
      }
    },
    {
      "heading": "Your First Program",
      "codeBlock": {
        "language": "python",
        "code": "print(\"Hello, World!\")"
      }
    }
  ]
}

Example 3: Configuration Documentation to Settings

Input ADOC file (config.adoc):

= Application Settings
:environment: production

== Database Configuration

* Host: localhost
* Port: 5432
* Database: myapp_production
* Pool Size: 10

== Cache Settings

* Provider: Redis
* TTL: 3600
* Max Connections: 50

Output JSON file (config.json):

{
  "title": "Application Settings",
  "metadata": {
    "environment": "production"
  },
  "database": {
    "host": "localhost",
    "port": 5432,
    "database": "myapp_production",
    "poolSize": 10
  },
  "cache": {
    "provider": "Redis",
    "ttl": 3600,
    "maxConnections": 50
  }
}

Frequently Asked Questions (FAQ)

Q: What is the purpose of converting ADOC to JSON?

A: Converting ADOC to JSON transforms human-readable documentation into structured data that can be processed by applications, APIs, and automated systems. This enables integration with web applications, content management systems, search engines, and data pipelines while preserving the document structure.

Q: How are AsciiDoc attributes preserved in JSON?

A: Document attributes (like :author:, :version:, :tags:) are converted into a metadata object within the JSON structure. Multi-value attributes like tags are converted to arrays. This preserves all attribute information in a format easily accessed programmatically.

Q: What happens to code blocks during conversion?

A: Code blocks are preserved with their language specification intact. The code content is stored as a string value, and the language attribute is maintained for syntax highlighting in consuming applications. Source blocks, listing blocks, and literal blocks are all properly converted.

Q: Can I convert complex tables from ADOC to JSON?

A: Yes! Tables are converted to structured JSON with headers and row arrays. Column headers become the "headers" array, and each row becomes an array of cell values. Complex tables with merged cells are simplified to standard tabular structure suitable for JSON representation.

Q: How are images and media references handled?

A: Image references are converted to JSON objects containing the image path, alt text, and any attributes (width, height, alignment). The actual image files are not embedded—only their paths are stored for your application to resolve and display.

Q: Is the JSON output valid and parseable?

A: Yes! The converter produces valid JSON conforming to RFC 8259 and ECMA-404. The output can be parsed by any JSON parser in any programming language (Python's json, JavaScript's JSON.parse, Java's Jackson, etc.) without modification.

Q: Can I use the JSON output with REST APIs?

A: Absolutely! The JSON output is ideal for REST API responses. You can serve it directly through Express, Django, Flask, or any web framework. It's perfect for documentation portals, content delivery APIs, and headless CMS integrations.

Q: What encoding is used for the JSON output?

A: The JSON output uses UTF-8 encoding as specified by RFC 8259. This supports all Unicode characters including international text, special symbols, and emoji from your original ADOC content. Non-ASCII characters are properly escaped when necessary.