The single orientation file for any AI agent (Claude Code, Copilot, Codex, ...) and any human working in this repo. Keep it current.
- Status: active. Open-source library, published to NuGet as
ShinyPDFandShinyPDF.Markdown(same version, released together). Fork of the last MIT-licensed version of QuestPDF. - Stack: C# / .NET 10 (SDK pinned in
src/global.json), SkiaSharp + HarfBuzzSharp for rendering, NUnit for tests. - Layout:
src/ShinyPDF(library:Fluent= public API,Elements,Drawing,Infrastructure,Helpers),src/ShinyPDF.Markdown(Markdown element on top of the public API, parsing via Markdig),src/ShinyPDF.UnitTests(fast tests with an operation-recording test engine),src/ShinyPDF.Examples(NUnit tests that render real PDFs/images).
- Never commit
.env,*.tfvars, or.claude/settings.local.json. - The public API (
ShinyPDF.Fluent, public types) is used by consumers: breaking changes need aBREAKING CHANGE:commit footer (major release). - SkiaSharp, HarfBuzzSharp and their
NativeAssets.*packages must stay on matching versions, including the Linux ones inDirectory.Build.props. - Native asset references in
Directory.Build.propskeepPrivateAssets="all"so they never become package dependencies. - The
Gridelement's[Obsolete]marker is inherited from the QuestPDF base, not a ShinyPDF decision; it may be reintroduced. Do not removeGridor migrate existing usages unprompted; its CS0618 warnings are expected. - Use NUnit
Assert.Thatin tests (no FluentAssertions).
dotnet build src/ShinyPDF.slnx # build all projects
dotnet test src/ShinyPDF.UnitTests/ShinyPDF.UnitTests.csproj # unit tests (seconds, what CI runs)
dotnet test src/ShinyPDF.Examples/ShinyPDF.Examples.csproj # example renders (~8 min, writes PDFs/PNGs to bin/)
dotnet pack src/ShinyPDF/ShinyPDF.csproj -c Release -o out # local NuGet package
dotnet pack src/ShinyPDF.Markdown/ShinyPDF.Markdown.csproj -c Release -o out # local Markdown packageExample tests marked .ShowResults() try to open the generated file in a viewer; run them only when rendering changed.
On Linux (or with SHINYPDF_DEVCONTAINER=true) the Linux native assets are added automatically.
- GitHub:
LM-Development/ShinyPDF, useghfor issues and PRs. Branch frommain, open a PR, CI (pull-request.yaml) builds and runs the unit tests. - Commits follow Conventional Commits. Every push to
mainrunsrelease.yaml:feat:/fix:/BREAKING CHANGEcreate a GitHub release and publish to NuGet;chore:,test:,docs:release nothing. - Merge PRs with a merge commit, not squash, so commit types and footers reach
mainunchanged. - Published NuGet versions cannot be deleted, only unlisted: check the commit type before merging.
Open issues: template designer app (#12). Markdown (#33): math and Mermaid have no built-in renderer, only the CodeBlockRenderers hook; raw HTML is shown as text.