mirror of
https://github.com/xoofx/markdig.git
synced 2026-11-16 17:30:52 +00:00
* Add IsAotCompatible for net8.0 and later targets * Enable the trim, AOT and single-file analyzers in Markdig's own build, so CI catches an AOT regression before it ships to consumers * Limit the property to net8.0+, since the analyzers do not run on netstandard and net462 targets * Test the assembly metadata, asserting IsAotCompatible only on net10.0, because the ILLink 8 build tasks used for net8.0 emit just IsTrimmable Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> * Fix test by verifying the AOT marking with an IL3058 build check * Replace the assembly metadata unit tests, which failed in the netstandard workflow because it builds Markdig for netstandard2.x only * Add Markdig.AotTests with VerifyReferenceAotCompatibility and IL3058 as an error, so the CI solution build fails if Markdig loses the AOT marking * Leave PublishAot unset, so the check restores no package beyond the ILLink.Tasks package the IsAotCompatible property already requires Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
4.6 KiB
4.6 KiB
Markdig — Codex Agent Instructions
Markdig is a fast, powerful, CommonMark compliant, extensible Markdown processor for .NET.
Paths/commands below are relative to this directory.
Orientation
- Workspace:
src/markdig.slnx(solution/workspace listing the projects below) - Library:
src/Markdig/ - Tests:
src/Markdig.Tests/(NUnit; includes generated spec tests) - AOT tests:
src/Markdig.AotTests/(the build fails with IL3058 ifMarkdigis no longer marked AOT-compatible) - Signed library build:
src/Markdig.Signed/(strong-named build ofsrc/Markdig/sources) - Benchmarks:
src/Markdig.Benchmarks/(BenchmarkDotNet perf comparisons) - Fuzzing:
src/Markdig.Fuzzing/(SharpFuzz/libFuzzer harness for parser/renderers) - Web app:
src/Markdig.WebApp/(ASP.NET Core API for converting Markdown → HTML) - Tooling:
src/mdtoc/(CLI to generate a Markdown TOC from a local file or GitHub URL) - Tooling:
src/SpecFileGen/(regenerates*.generated.csspec tests fromsrc/Markdig.Tests/**.md) - Tooling:
src/UnicodeNormDApp/(generates the Unicode→ASCII mapping used byMarkdig.Helpers.CharNormalizer) - Docs to keep in sync with behavior:
readme.mdand the docs undersite/docs/(e.g.,site/docs/**/*.md) - Website:
site/— Lunet-based documentation site (https://xoofx.github.io/markdig)
Build & Test
# from the project root (this folder)
cd src
dotnet build -c Release
dotnet test -c Release
All tests must pass and docs must be updated before submitting.
Website (Lunet)
The project website lives in site/ and is built with Lunet, a static site generator.
# Prerequisites: install lunet as a .NET global tool
dotnet tool install -g lunet
# Build the site (from the project root)
cd site
lunet build # production build → .lunet/build/www/
lunet serve # dev server with live reload at http://localhost:4000
Escaping {{ }} in site Markdown
Because the site is processed by Scriban via Lunet, any literal {{ or }} in Markdown documentation must be escaped as {{ "{{" }} and {{ "}}" }} respectively. Hand-written pages must be escaped manually.
Contribution Rules (Do/Don't)
- Keep diffs focused; avoid drive-by refactors/formatting and unnecessary dependencies.
- Follow existing patterns and naming; prefer clarity over cleverness.
- New/changed behavior requires tests; bug fix = regression test first, then fix.
- All public APIs require XML docs (avoid CS1591) and should document thrown exceptions.
C# Conventions (Project Defaults)
- Naming:
PascalCasepublic/types/namespaces,camelCaselocals/params,_camelCaseprivate fields,I*interfaces. - Style: file-scoped namespaces;
usingoutside namespace (Systemfirst);varwhen the type is obvious. - Nullability: enabled — respect annotations; use
ArgumentNullException.ThrowIfNull(); preferis null/is not null; don't suppress warnings without a justification comment. - Exceptions: validate inputs early; throw specific exceptions (e.g.,
ArgumentException/ArgumentNullException) with meaningful messages. - Async:
Asyncsuffix; noasync void(except event handlers); useConfigureAwait(false)in library code; considerValueTask<T>on hot paths.
Performance / AOT / Trimming
- Minimize allocations (
Span<T>,stackalloc,ArrayPool<T>,StringBuilderin loops). - Keep code AOT/trimmer-friendly: avoid reflection; prefer source generators; use
[DynamicallyAccessedMembers]when reflection is unavoidable. - Use
sealedfor non-inheritable classes; preferReadOnlySpan<char>for parsing.
API Design
- Follow .NET guidelines; keep APIs small and hard to misuse.
- Prefer overloads over optional parameters (binary compatibility); consider
Try*methods alongside throwing versions. - Mark APIs
[Obsolete("message", error: false)]before removal once stable (can be skipped while pre-release).
Git / Pre-Submit
- Commits: commit after each self-contained logical step; imperative subject, < 72 chars; one logical change per commit; reference issues when relevant; don't delete unrelated local files.
- Commit subjects must start with a dotnet-releaser autolabel prefix:
Breaking Change,Add,Fix/Bugfix,Enhance/Refactor,Improve Perf,Add/Improve/Fix/Updatefollowed byci/doc/test/example/translation/accessibility, orUpdate Depend.../Bump <dependency>for dependencies. Put any GitHub issue reference at the end in parentheses, e.g.Fix parser error (#18). - Checklist: each self-contained step is committed; build+tests pass; docs updated if behavior changed; public APIs have XML docs; changes covered by unit tests.