Convert SQL to AsciiDoc

Why Convert SQL to AsciiDoc?

Converting SQL files to AsciiDoc format is the preferred approach for creating enterprise-grade database documentation. AsciiDoc's rich semantic markup provides features specifically designed for technical writing, including source code listings with language-aware syntax highlighting, admonition blocks for warnings and notes, and structured sections with automatic table of contents generation.

Database teams often maintain SQL scripts that grow increasingly complex over time. Without proper documentation, understanding the purpose of stored procedures, migration scripts, and complex queries becomes challenging. AsciiDoc conversion solves this by wrapping SQL code in well-structured documents with explanatory text, making the codebase accessible to developers, DBAs, and stakeholders alike.

AsciiDoc stands out from simpler markup languages because it supports professional publishing workflows. A single AsciiDoc source file can be rendered to HTML5 for web publishing, PDF for printed manuals, EPUB for e-readers, and DocBook XML for further processing. This multi-format capability makes it ideal for organizations that need database documentation in various formats.

The integration with modern development tools is another compelling reason to convert SQL to AsciiDoc. GitHub and GitLab render AsciiDoc files natively, Antora can build complete documentation websites, and CI/CD pipelines can automatically generate updated documentation whenever SQL scripts change. This creates a seamless documentation-as-code workflow for database teams.

Key Benefits of Converting SQL to AsciiDoc:

• Enterprise-Grade Docs: Create publication-quality database manuals and reference guides
• SQL Syntax Highlighting: [source,sql] blocks render with proper keyword coloring
• Multi-Format Publishing: Generate HTML, PDF, EPUB, and DocBook from one source
• Admonition Blocks: Highlight important notes, warnings, and tips about SQL operations
• Modular Architecture: Use include directives to compose documentation from multiple files
• CI/CD Integration: Automate documentation generation in build pipelines
• Native Repository Rendering: GitHub and GitLab display AsciiDoc files beautifully

Practical Examples

Example 1: Table Creation Documentation

Input SQL file (create_tables.sql):

-- Product catalog tables
CREATE TABLE categories (
    id INT AUTO_INCREMENT PRIMARY KEY,
    name VARCHAR(100) NOT NULL,
    parent_id INT REFERENCES categories(id)
);

CREATE TABLE products (
    id INT AUTO_INCREMENT PRIMARY KEY,
    name VARCHAR(200) NOT NULL,
    price DECIMAL(10,2) NOT NULL,
    category_id INT REFERENCES categories(id),
    created_at DATETIME DEFAULT NOW()
);

Output AsciiDoc file (create_tables.asciidoc):

= Product Catalog Database Schema
:toc: left
:source-highlighter: rouge

== Categories Table

Product catalog tables.

[source,sql]
----
CREATE TABLE categories (
    id INT AUTO_INCREMENT PRIMARY KEY,
    name VARCHAR(100) NOT NULL,
    parent_id INT REFERENCES categories(id)
);
----

NOTE: Categories support hierarchical nesting
via the parent_id self-reference.

== Products Table

[source,sql]
----
CREATE TABLE products (
    id INT AUTO_INCREMENT PRIMARY KEY,
    name VARCHAR(200) NOT NULL,
    price DECIMAL(10,2) NOT NULL,
    category_id INT REFERENCES categories(id),
    created_at DATETIME DEFAULT NOW()
);
----

Example 2: Data Insertion Script

Input SQL file (seed_data.sql):

-- Seed initial user data
INSERT INTO users (username, email, role)
VALUES
    ('admin', '[email protected]', 'administrator'),
    ('editor', '[email protected]', 'content_editor'),
    ('viewer', '[email protected]', 'read_only');

-- Set default permissions
GRANT SELECT ON public.* TO 'viewer';

Output AsciiDoc file (seed_data.asciidoc):

= Seed Data Script

== Initial User Data

.Seed initial user data
[source,sql]
----
INSERT INTO users (username, email, role)
VALUES
    ('admin', '[email protected]', 'administrator'),
    ('editor', '[email protected]', 'content_editor'),
    ('viewer', '[email protected]', 'read_only');
----

== Default Permissions

.Set default permissions
[source,sql]
----
GRANT SELECT ON public.* TO 'viewer';
----

CAUTION: Review permission grants carefully
before executing in production.

Example 3: Stored Procedure Documentation

Input SQL file (procedures.sql):

-- Calculate total order amount
CREATE PROCEDURE calculate_order_total(
    IN order_id INT,
    OUT total DECIMAL(10,2)
)
BEGIN
    SELECT SUM(quantity * unit_price)
    INTO total
    FROM order_items
    WHERE order_items.order_id = order_id;
END;

Output AsciiDoc file (procedures.asciidoc):

= Stored Procedures Reference

== calculate_order_total

Calculates the total monetary amount for a
given order by summing line items.

.Parameters
[cols="1,1,3"]
|===
|Direction |Name |Description

|IN |order_id |The order identifier
|OUT |total |Calculated total amount
|===

[source,sql]
----
CREATE PROCEDURE calculate_order_total(
    IN order_id INT,
    OUT total DECIMAL(10,2)
)
BEGIN
    SELECT SUM(quantity * unit_price)
    INTO total
    FROM order_items
    WHERE order_items.order_id = order_id;
END;
----

Frequently Asked Questions (FAQ)

Q: What is the difference between AsciiDoc and ADOC?

A: AsciiDoc is the markup language itself, while .adoc and .asciidoc are file extensions. The .asciidoc extension is the full-name variant, while .adoc is the shorter, more commonly used extension. Both produce identical results when processed by Asciidoctor.

Q: Why choose AsciiDoc over Markdown for SQL documentation?

A: AsciiDoc offers significant advantages for technical documentation: admonition blocks (NOTE, WARNING, CAUTION), include directives for modular docs, complex table support, conditional content, and multi-format output (HTML, PDF, EPUB). For database documentation that needs professional publishing, AsciiDoc is the better choice.

Q: How does SQL syntax highlighting work in AsciiDoc?

A: AsciiDoc uses the [source,sql] attribute on code blocks to declare the language. When processed with Asciidoctor and a syntax highlighter (Rouge, Pygments, or highlight.js), SQL keywords, strings, numbers, and comments are automatically color-coded for readability.

Q: Can I generate PDF documentation from the AsciiDoc output?

A: Yes! Use Asciidoctor-PDF to generate professional PDF documents directly from AsciiDoc files. You can customize fonts, colors, headers, footers, and page layouts using a theme file. This is perfect for creating printable database reference manuals.

Q: Does the converter preserve SQL comments?

A: Yes, all SQL comments are preserved in the AsciiDoc output. Single-line comments (--) and multi-line comments (/* */) are included within the source code blocks, maintaining the original documentation within the SQL code.

Q: Can I use AsciiDoc with documentation site generators?

A: Absolutely! Antora is a popular documentation site generator built specifically for AsciiDoc. It can build versioned documentation websites from AsciiDoc content stored across multiple Git repositories, making it perfect for large-scale database documentation projects.

Q: Is AsciiDoc compatible with version control systems?

A: Yes! AsciiDoc is a plain text format, making it ideal for version control with Git. Changes are easy to diff and merge, and you can track documentation updates alongside SQL schema changes in the same repository.

Q: What tools do I need to view AsciiDoc files?

A: AsciiDoc files can be viewed as plain text in any editor. For rendered output, use Asciidoctor (CLI tool), browser extensions like Asciidoctor.js Live Preview, or IDE plugins for VS Code, IntelliJ IDEA, or Eclipse. GitHub and GitLab also render .asciidoc files directly in the browser.