AdocNet.Converters.Man 1.0.23

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 multi-targets .NET 10 and .NET 8 (optimized) plus .NET Standard 2.0 (broad compatibility: .NET Framework 4.6.1+, .NET Core 2.0+, Mono, Unity, Xamarin).

Asciidoctor parity

AdocNet 1.0 produces output that is structurally identical to Asciidoctor (zero DOM diff) for HTML, DocBook, and Reveal.js across the full 36-document conformance corpus (spec/conformance/*.adoc, verified via tools/parity-sweep.py, which renders both with matching options and compares the structural DOM). 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

The meta-package pulls in the core parser plus the HTML and PDF renderers:

dotnet add package AdocNet

Which package do I need?

For library use, reference the package for the output you want. (The AdocNet.Pdf, AdocNet.Epub, etc. IDs are command-line tools, not libraries — for code, use the AdocNet.Converters.* packages below.)

Command-line tools

These are dotnet tool packages (not referenceable libraries):

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
dotnet tool install --global AdocNet.Docx         # docx2adoc (.docx → AsciiDoc)

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;                  // ParseOptions, RenderToString extension
using AdocNet.Parser;           // AdocParser
using AdocNet.Converters.Html;  // HtmlRenderer, HtmlRenderOptions, HtmlTheme

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

// dotnet add package AdocNet.Converters.DocBook
using AdocNet;                     // RenderToString extension
using AdocNet.Converters.DocBook;

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

Render to EPUB

// dotnet add package AdocNet.Converters.Epub
using AdocNet.Converters.Epub;

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

Import a Word document

// dotnet add package AdocNet.Importers.Docx
using AdocNet.Importers.Docx;

var importer = new DocxImporter();
string adoc = importer.ToAsciiDoc("handbook.docx");

// Or keep the AST, extracted images, and the fidelity report
var imported = importer.ImportFile("handbook.docx");
Console.Write(imported.Report.ToSummary());   // fidelity: 99.63% (272/273 units) …

Structure, lists, tables, images, links, notes and formatting are mapped; anything AsciiDoc cannot express (page geometry, tab stops, shapes) is listed in the report rather than dropped silently. See docs/DOCX_IMPORT.md.

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

Focused 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 (and AdocNet.Avalonia) multi-target netstandard2.0, net8.0, and net10.0. The CLI tools and LSP server target net10.0 only.

License

MIT