Section navigation

Documentation

The site is built by DocFX from Markdown, YAML navigation, XML API comments, generated reports, and the custom template under docs/templates/leancorpus.

Source and generated content

Edit the Markdown source and templates. Do not edit generated output in:

  • docs/.generated;
  • docs/site;
  • docs/api;
  • docs/bench;
  • docs/coverage;
  • bin or obj.

API reference pages are generated from XML documentation. If a public member is unclear, improve its XML comment as well as any conceptual guide.

The feature comparison lives in the Markdown pages under docs/articles/features. User-visible feature additions or removals should update the relevant comparison page where applicable. Keep Lucene.NET 4.8 and current Java Lucene as separate comparisons, and use ◐ only for comparable rather than API-equivalent behaviour.

Repository READMEs and contribution guides remain at their owning repository paths so they work on GitHub. The documentation build copies the selected files into docs/.generated, rewrites local links for their site destinations, and adds a source notice. Update the source-to-destination map in Copy-RepositoryDocumentation when adding or moving one of these guides.

The root docs/toc.yml defines the main site navigation. Each section has its own toc.yml. Add a page to both the DocFX content patterns and the appropriate table of contents when introducing a new hierarchy.

Use relative links between conceptual pages. DocFX validates links during the documentation build.

Diagrams

Use Mermaid for relationships, sequence, state, and flow diagrams. LeanCorpus pins Mermaid 11.16.0 independently of DocFX and loads it only on pages containing a mermaid-latest code block.

Good choices include:

Need Mermaid form
Request or commit ordering sequenceDiagram
Decision or data flow flowchart
Package relationships architecture-beta
Compact fixed field layout packet-beta

Packet diagrams become awkward when a format has variable-length fields, nested frames, or annotations that are not byte offsets. Codec framing therefore uses Bytefield-SVG as a build-time authoring tool.

Bytefield sources live in docs/diagrams. Generated SVG files live in docs/assets/diagrams and are committed so ordinary DocFX builds remain .NET-only.

cd docs/diagrams
npm ci
npm run diagrams

The diagram build also copies the pinned Mermaid browser bundle into docs/assets/diagrams. Pin diagram dependencies and commit the lock file. Review generated assets together with their source.

Build

Build the site without regenerating benchmarks:

./devops docs -SkipBenchmarks

The console groups DocFX warnings by code rather than printing every instance. Full JSON-lines diagnostics are retained under artifacts/docs, and long DocFX stages report elapsed time every 30 seconds.

Resolve broken links, duplicate headings, invalid YAML, and Mermaid parse failures before handing off a documentation change. Generated HTML belongs to the build output and should not be committed manually.

The generated repository staging tree is also ignored. A second documentation build should produce the same content without changing Git status.

Style

Use British English (just for consistency). Prefer a direct explanation, then an example, then operational caveats. State defaults explicitly when they affect behaviour. Distinguish public API from contributor internals and avoid promising a binary layout that the implementation does not guarantee.

Edit this page