AdocNet.Core 1.0.11

Adoc.Net

A pure managed C# AsciiDoc library for .NET. No external runtime dependencies.

Adoc.Net parses AsciiDoc into a typed AST and renders it to HTML5, PDF, DocBook 5.0, EPUB 3.0, man pages, or reveal.js slides. HTML rendering supports custom per-node templates via INodeTemplate. It targets both .NET 10 (optimized) and .NET Standard 2.0 (broad compatibility: .NET Framework 4.6.1+, .NET Core 2.0+, Mono, Unity, Xamarin).

Asciidoctor parity

AdocNet 1.0 produces byte-identical output to Asciidoctor for HTML, DocBook, and Reveal.js across the full 36-document conformance corpus (spec/conformance/*.adoc, verified via tools/parity-sweep.py). EPUB ships the same asset payload as asciidoctor-epub3 (fonts, stylesheets, default images) with a dedicated chapter renderer emitting the reference's semantic HTML5; readers see indistinguishable output. Man output is cleaner roff than the reference while remaining structurally equivalent. See CHANGELOG.md for the v1.0 parity arc.

Installation

dotnet add package AdocNet

For the CLI tools:

dotnet tool install --global AdocNet.Tool         # adocnet (HTML default)
dotnet tool install --global AdocNet.Pdf          # adocnet-pdf
dotnet tool install --global AdocNet.Epub         # adocnet-epub
dotnet tool install --global AdocNet.DocBook      # adocnet-docbook

Quick Start

using AdocNet;

// One line — that's it
string html = Adoc.ToHtml("= Hello\n\nThis is *bold* text.");

More control

// Styled full HTML document with CSS theme
string page = Adoc.ToStyledHtml(source, HtmlTheme.Asciidoctor);

// PDF output
byte[] pdf = Adoc.ToPdf(source);

// Write directly to a stream (no intermediate string)
using var file = File.Create("output.html");
Adoc.ToHtml(source, file);

// Convert a file with include resolution
Adoc.ConvertFile("docs/chapter.adoc", file);

// Parse with diagnostics
var result = Adoc.Parse(source);
if (result.HasErrors)
    foreach (var d in result.Diagnostics) Console.WriteLine(d);

Full API (when you need options)

using AdocNet.Parser;
using AdocNet.Converters.Html;

var result = AdocParser.Parse(source, new ParseOptions
{
    SourceFilePath = "docs/chapter.adoc",  // enables include resolution
    Attributes = new Dictionary<string, string> { ["version"] = "2.0" },
});

var html = new HtmlRenderer().RenderToString(result.Document,
    new HtmlRenderOptions { Theme = HtmlTheme.Asciidoctor });

Render to PDF

using AdocNet.Converters.Pdf;

byte[] pdf = new PdfRenderer().RenderToBytes(result.Document);
File.WriteAllBytes("output.pdf", pdf);

Render to DocBook

using AdocNet.Converters.DocBook;

string xml = new DocBookRenderer().RenderToString(result.Document);

Render to EPUB

using AdocNet.Converters.Epub;

byte[] epub = new EpubRenderer().RenderToBytes(result.Document);
File.WriteAllBytes("output.epub", epub);

Parse with includes

var text = File.ReadAllText("book.adoc");
var result = AdocParser.Parse(text, new ParseOptions
{
    SourceFilePath = "book.adoc",
});

Check for errors

if (result.HasErrors)
{
    foreach (var diag in result.Diagnostics.Where(d => d.IsError))
        Console.Error.WriteLine(diag);
}

CLI Tools

# General-purpose (default: HTML)
adocnet input.adoc                            # → input.html
adocnet input.adoc -b pdf                     # → input.pdf
adocnet input.adoc -o -                       # → stdout

# Specialized tools (same flags, different default format)
adocnet-pdf input.adoc                        # → input.pdf
adocnet-epub input.adoc                       # → input.epub
adocnet-docbook input.adoc                    # → input.xml

# Common options (all tools)
adocnet input.adoc -o custom.html             # explicit output file
adocnet input.adoc -a version=2.0             # set document attribute
adocnet docs/ -r -D build/                    # convert directory
adocnet docs/ --watch -v                      # watch and rebuild
adocnet preview input.adoc                    # live preview with hot reload

# Built-in HTML themes (require -e for full document with embedded CSS)
adocnet input.adoc -e --theme default         # AdocNet's bold, modern default
adocnet input.adoc -e --theme asciidoctor     # iconic Asciidoctor red-on-cream look
adocnet input.adoc -e --theme clean           # minimal monochrome
adocnet input.adoc -e --theme github          # GitHub-flavoured markdown style

The --theme asciidoctor option is for users migrating from Asciidoctor who want their HTML output to look familiar — it reproduces the iconic red section headings, serif body, and centered layout.

See docs/CLI.md for the full reference.

Supported AsciiDoc Features

Block-level

Inline

Rendering Features

Processing Extensions

Performance

Editor Integration

Architecture

Eleven assemblies, each with a single responsibility:

The data flow for the Avalonia viewer is strictly layered: AST → Layout → Avalonia. The Layout library has zero UI dependencies and targets netstandard2.0, making it consumable by any .NET UI framework.

Documentation

Performance

AdocNet is a native managed library with no interpreter startup, so it's significantly faster than Asciidoctor (Ruby) for typical workloads. Preliminary measurements on the 36-document conformance corpus show 15-25× speedup for HTML rendering on warm JIT. To benchmark on your hardware:

dotnet run -c Release --project benchmarks/AdocNet.Benchmarks

Concrete numbers (with BenchmarkDotNet methodology, percentile breakdowns, allocation counts) will be published in a follow-up release.

Migrating from Asciidoctor

For users moving from the Asciidoctor (Ruby) toolchain, the docs/MIGRATION-FROM-ASCIIDOCTOR.md guide covers CLI flag mapping, parity matrix per format, intentional differences (e.g. CDN vs local paths for reveal.js assets), and known out-of-scope features.

Building

dotnet build
dotnet test

Target Frameworks

All core libraries target netstandard2.0 and net10.0. The CLI and LSP server target net10.0 only.

License

MIT