AsciiDocSharp Library

AsciiDocSharp is a native .NET library designed to parse AsciiDoc documents and convert them into structured models and various output formats. It provides a modern, implementation of the AsciiDoc specification for all .NET Standard 2.0+ platforms.

Overview

AsciiDocSharp delivers a comprehensive, extensible, and high-performance AsciiDoc processor for the .NET ecosystem. Its objectives are:

• Parse AsciiDoc files into a structured, object-oriented document model based on the official AsciiDoc specification.

• Provide modular, pluggable output converters (HTML, Markdown, etc.), with HTML as the primary focus.

• Ensure broad compatibility by targeting .NET Standard 2.0 (usable from .NET Framework 4.6.1+, .NET Core 2.0+, .NET 5+, and later).

• Offer a solid architectural foundation that is easy to extend and maintain.

• Deliver production-quality code with comprehensive documentation and automated testing.

License

AsciiDocSharp is distributed under the MIT License. See the LICENSE.adoc file for details.

Status

Important

AsciiDocSharp is under active development and has not yet had a public release. No official NuGet package is available at this time. The library is evolving rapidly and breaking changes may occur.

If you wish to experiment with or contribute to the project, you can build it from source and use it directly in your projects.

Basic Use

Until a release is published, the recommended way to use AsciiDocSharp is to clone the repository and build the project using the .NET SDK:

git clone https://github.com/AsciiDocSharp/AsciiDocSharp.git
cd AsciiDocSharp
dotnet build

You can then add the built library projects to your solution or reference the resulting DLLs.

Project Status

• Implements ~85-88% of the core AsciiDoc specification (as of July 2025)

• Fully documented public API with XML comments

• Comprehensive test suite and performance benchmarks

• Actively developed and open for contributions

Supported Features

The following AsciiDoc features are currently supported and fully functional:

Document Structure & Metadata

• Document header with title, author, email, revision, and date

• Document attributes (:attr: value syntax)

• Attribute blocks ([role="value"])

• Global document attributes

Block Elements

Sections & Headers

• Multi-level sections (=, ==, ===, etc.)

• Document title (top-level)

Lists

• Unordered lists (bullet lists with * marker)

• Ordered lists (numbered lists with 1., 2., etc.)

• Description lists (term-definition pairs with term::)

• Checklists with checkbox support:

  • Unchecked items: * [ ] task

  • Checked items: * [x] task or * [X] task

  • Mixed lists (regular items + checkboxes)

• Nested lists (multi-level support)

Delimited Blocks

• Literal blocks (preformatted text with …​.)

• Listing blocks (code listings with ----)

• Open blocks (generic containers with --)

• Example blocks (example content with ====)

• Sidebar blocks (sidebar content with **)

• Block quotes (quoted content with __)

• Verse blocks (poetry/verse with attribution)

• Passthrough blocks (raw content with )

Tables

• Basic table structure (|===)

• Table headers and data rows

• Table cells with content

• Table titles (optional captions)

Admonitions

• NOTE admonitions

• TIP admonitions

• IMPORTANT admonitions

• WARNING admonitions

• CAUTION admonitions

Code Blocks

• Syntax highlighted code blocks

• Language specification for highlighting

• Optional line numbering

Inline Elements

Text Formatting

• Strong/Bold text (text)

• Emphasis/Italic text (text)

• Highlight text (text)

• Superscript text (^text)

• Subscript text (_text)

• Inline code formatting (code)

Links & References

• External links (HTTP/HTTPS with optional text)

• Anchors ()

• Cross references ([anchor-id])

Images

• Inline images

• Block-level image macros (image::path[alt])

• Alt text for images

Macros

• Block macros (block-level macro invocations)

• Inline macros (inline macro invocations)

• Image macros (image insertion)

• Video macros (video embedding)

• Include macros (file inclusion)

• Table of contents generation (toc::[])

• Footnotes (references and content)

Special Features

• Include directives with file inclusion

• Circular reference detection

• Path resolution for includes

• Error handling and recovery

• Performance optimization

Output Formats

• HTML5 Converter: Complete standards-compliant HTML output

  • Semantic markup with proper HTML elements

  • CSS classes for styling support

  • Document structure conversion

  • Support for all implemented elements

  • Proper checkbox rendering

Author

AsciiDocSharp is created and maintained by Guillermo Espert.