Novolis Docs
novolis-markup / design.md

Design

Manuscripts, markdown, mermaid

dotnetmarkdownmarkupnovolis

Purpose

Programmatic construction of Markdown and Mermaid text without templates or string concatenation scattered through application code. The libraries migrated from Frank.Markdown and Frank.Mermaid (wave 10).

Packages

PackageResponsibility
Novolis.Markup.MarkdownSection-based GFM documents (headers, lists, tables, alerts, code blocks) and optional HTML export
Novolis.Markup.Markdown.RenderingThemed HTML documents / file export via Novolis Markdown
Novolis.Markup.Markdown.DocumentsMarkdown → PagedDocument / PDF via Documents.Skia
Novolis.Markup.MermaidDiagram builders (flowchart, sequence, class, state, ER, gantt, mindmap, C4, and more) emitting Mermaid source

UI hosts (Novolis.Avalonia.Markdown / .Mermaid, Novolis.Maui.Markdown / .Mermaid) live in novolis-avalonia and novolis-maui. Use Novolis.Markup.Markdown.Documents / novolis-mdpdf for PDF — not QuestPDF.

There is no shared runtime dependency between Markdown and Mermaid; reference only what you need.

Markdown model

  • `IMarkdownDocument` — ordered collection of `IMarkdownSection` instances.
  • `MarkdownDocument` — mutable builder with With(...) chaining and Parse for simple imports.
  • Extension methods on IMarkdownDocument — convenience WithHeader, WithTable<T>, etc.
  • `EnumerableExtensions.ToMarkdownTable<T>` — reflects public properties into pipe tables.

HTML output uses embedded GitHub-flavored CSS constants (GithubMarkdownCss).

Mermaid model

  • `IMermaidable` — stable Hash id plus GetBuilder() / GetMermaidString().
  • `IndentedStringBuilder` — indentation-aware emission shared by diagram types.
  • `MermaidDiagramKind` — catalog of supported diagram families.
  • `MermaidDocument` / `MermaidJson` — parse Mermaid source (and optional YAML front matter) back into typed builders; JSON is a lossless envelope around that source.
  • Flowchart — nodes, links, subgraphs, delimiter shapes, and named shapes (A@{ shape: docs, label: "…" }).
  • Other diagram types (sequence, class, state, ER, gantt, mindmap, C4, Ishikawa, use case, Wardley, Cynefin, railroad, event modeling, …) follow the same builder pattern under their folders.

Reflection-based class diagrams live in Novolis.CodeGen.Reflection.ClassDiagram (novolis-codegen), not in this repo.

Avalonia rendering: Novolis.Avalonia.Mermaid (MermaidControl) in novolis-avalonia.

Documentation policy

Public API is documented with XML comments (GenerateDocumentationFile, strict CS1591). Package READMEs ship on NuGet via PackageReadmeFile.