Public API Surface

mdwright is a virtual workspace, not a facade crate. Command users install the mdwright package. Rust library users depend on the component crate that owns the capability they need.

The API is still pre-1.0. Import paths and operation shapes may change in minor releases under the pre-1.0 caveats.

Use mdwright as a library

A minimal embed that parses Markdown, runs the standard lint catalogue, and formats with defaults. Add the three crates to Cargo.toml:

[dependencies]
mdwright-document = "0.1"
mdwright-format = "0.1"
mdwright-lint = "0.1"

Then:

use mdwright_document::Document;
use mdwright_format::{FmtOptions, format_validated};
use mdwright_lint::{LintOptions, RuleSet};

fn main() -> anyhow::Result<()> {
    let source = "# Hello\n\nSee https://example.com for the spec.\n";

    // Parse once. `Document` holds source coordinates and recognised facts.
    let doc = Document::parse(source)?;

    // Lint with the shipped default rule set.
    let rules = RuleSet::stdlib_defaults();
    for diag in rules.check_with(&doc, LintOptions::default()) {
        println!("{}: {}", diag.rule, diag.message);
    }

    // Format. Returns a verified rewrite or a `FormatError` on safety-gate refusal.
    let formatted = format_validated(&doc, &FmtOptions::default())?;
    print!("{formatted}");
    Ok(())
}

The table below maps every capability to its owning crate. For the surface a particular crate exposes, follow its docs.rs link from the project README.

Common User Surfaces

Document is parse/query only. Linting, formatting, safe-fix application, config discovery, command delivery, and editor delivery stay in their owning crates.

The mdwright-latex surface targets common MathJax-style math bodies where Unicode can represent the source or terminal output honestly. Unicode-to-LaTeX translation is parser-backed for the supported subset: the crate lexes and parses Unicode mathematical source before emitting canonical LaTeX. It is not a TeX engine API, a browser layout API, or a diagram recogniser. Macro expansion, unsupported package commands, layout-heavy source, and unknown Unicode return typed errors, losses, or visible fallback output rather than hidden approximations.

Extension Surfaces

The standard rule structs under mdwright_lint::stdlib are public so callers can build precise RuleSets. Helper functions inside those rules are not public extension points unless listed above.

Advanced Document Facts

These facts are public because formatter, lint, audit, and custom-rule callers need stable source ranges without learning pulldown event shapes.

Formatter-facing facts expose accessors instead of public fields where practical. That keeps invalid construction out of downstream code while preserving stable ranges for rule authors and diagnostic tooling.

Not Public Surface

• Root facade exports. There is no root package and no mdwright::{Document, FmtOptions, RuleSet} import path.
• Parser internals, pulldown events, source/canonical byte-map internals, and the private document tree.
• Source, CanonicalSource, OffsetMap, ByteSpan, OriginalSpan, NormalisedLabel, and heading trailer scanners.
• Top-level block checkpoint parser helpers. Use mdwright_format::CheckpointTable.
• Formatter rewrite candidates, rewrite snapshots, verification signatures, owner IDs, and byte-application internals.
• mdwright-latex lexer tokens, parser cursors, AST nodes, command-registry storage, and Unicode layout internals.
• Lint suppression maps, diagnostic sorting internals, and stdlib helper functions not listed as extension surfaces.
• TOML raw schema structs and config discovery internals.
• CLI and LSP state machines beyond the documented entry points.