gum-docs-writing
Skill659 starsChanged 2 months agoMITView on GitHub
Writing Gum docs in GitBook markdown. Triggers: editing docs/, SUMMARY.md, GitBook hints/figures, cross-page links, doc images.
In this repository69 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- debuggingSkill
- frb-build-verificationSkill
- frb-pixel-harnessSkill
- gum-architecture-layersSkill
- gum-bundleSkill
- gum-cliSkill
- gum-cross-platform-unificationSkill
- gum-file-pathsSkill
- gum-forms-behaviorsSkill
- gum-forms-controlsSkill
- gum-forms-default-visualsSkill
- gum-forms-itemscontrolSkill
- gum-forms-theme-importSkill
- gum-iconsSkill
- gum-issue-creationSkill
- gum-kernsmith-integrationsSkill
- gum-layout-engineSkill
- gum-layoutSkill
- gum-localizationSkill
- gum-monogame-renderingSkill
- gum-monthly-releaseSkill
- gum-project-versioningSkill
- gum-property-assignmentSkill
- gum-raylib-renderingSkill
- gum-releaseSkill
- gum-runtime-animation-chainsSkill
- gum-runtime-bindingSkill
- gum-runtime-fontsSkill
- gum-runtime-hot-reloadSkill
- gum-runtime-syntax-versionSkill
- gum-runtime-systemmanagers-initSkill
- gum-runtime-topologySkill
- gum-runtime-variable-referencesSkill
- gum-samplesSkill
- gum-serviceSkill
- gum-source-linked-projectSkill
- gum-themingSkill
- gum-tool-animationsSkill
- gum-tool-codegenSkill
- gum-tool-copy-pasteSkill
- gum-tool-delete-logicSkill
- gum-tool-dialogsSkill
- gum-tool-errorsSkill
- gum-tool-file-watchSkill
- gum-tool-font-generationSkill
- gum-tool-import-from-gumxSkill
- gum-tool-loggingSkill
- gum-tool-outputSkill
- gum-tool-pluginsSkill
- gum-tool-save-classesSkill
- gum-tool-screenshotsSkill
- gum-tool-selectionSkill
- gum-tool-tree-viewSkill
- gum-tool-undoSkill
- gum-tool-variable-gridSkill
- gum-tool-variable-referencesSkill
- gum-tool-viewmodelsSkill
- gum-unit-testsSkill
- gum-variable-deep-diveSkill
- The first 60 shown.
The file
Show its rules and text
We split this skill into the rules it gives an agent
17 rules. About 0 are common, 13 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈13
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 21
Before writing prose: read the page you are editing and one or two sibling pages in the same folder, and match their sentence length and …
- Very specific: line 38
All docs live under docs/.
- Distinctive: line 40
Every new file must be added to SUMMARY.md with a 2-space indent per nesting level:
- Very specific: line 56
All images live in docs/.gitbook/assets/.
- Distinctive: line 103
Always use relative paths — no absolute URLs.
- Very specific: line 109
Do not use anchor-only links to other files (e.g., foo is fine, but foo only works within the same page).
- Distinctive: line 154
Not this — date leaks into body bullets, so removing the dated context later means rewriting prose:
- Distinctive: line 191
Read-aloud test: If a clause repeats the clause before it, or the sentence runs out of breath, rewrite it.
- Distinctive: line 202
Use numbered lists for procedures.
- Distinctive: line 205
Avoid passive voice, prefer "Gum displays a label" over "a label is displayed."
- Distinctive: line 206
Never mix informing and instructing.
- Distinctive: line 210
Never use an em dash (—): Use a comma, period, or parenthetical instead.
- Distinctive: line 211
Prefer plain language over jargon when a plainer phrasing says the same thing.
- Distinctive: line 212
Avoid hyphenated compound phrases where a plainer wording works.
- Distinctive: line 213
After writing, re-read a passage and ask whether someone with no technical background could follow it.
- Distinctive: line 215
Describe how to use a feature, not where it is missing: Do not add lists of platforms or elements that lack a feature, or paragraphs about …
- Very specific: line 220
Every \\\csharp` block must have a placement comment as its first line so readers and agents know where the code belongs.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Gum Docs Writing Reference
Readers Are People With Little Attention
Docs are for people who want to get something done and will not read more than they must. Skills are for agents, who read fast, so a skill can hold many details as long as it does not overload context. Both stay short, for different reasons.
For every sentence, section and screenshot, ask: is this absolutely critical for getting the task done? If not, cut it. Detail the tool, a warning message or the code already shows is not critical.
Write the page, then cut it in half before committing: a property page says what it does in one or two sentences and when to change it in one, and repeats nothing the tool already shows in a label, tooltip or subtext. If a sentence would not change what the reader does, delete it.
XML doc comments in the C# runtimes are docs too, with the same readers. Say what the member does and its one precondition; do not add advice about other members.
Before You Write and Before You Commit
- Before writing prose: read the page you are editing and one or two sibling pages in the same folder, and match their sentence length and voice.
- Before committing: re-read every new paragraph against those pages and the Prose Style and Tone and Style sections below. Cut explanation the neighbors would not include.
Organize by Functionality, Not API Type
A page's home is the functional section a user browses when they have the problem it solves, not a type-indexed folder chosen because that's where the class lives. A new feature's primary explanation goes in its task-based section (e.g. cursor hit-testing for scaled/render-target rendering under events-and-interactivity/); the gum-code-reference/<Type>/ folders hold only terse per-member stubs that link back to it.
Verify Behavior Claims Before Writing Them
Before writing a claim like "X isn't available on backend Y" or "X requires package Z," verify it against the relevant domain skill (e.g. gum-runtime-fonts, gum-kernsmith-integrations, gum-cross-platform-unification) or source — this skill covers GitBook mechanics only, not product behavior. A missing per-platform package is not proof of a capability gap: the platform may get the capability another way (Silk.NET has no KernSmith package because it renders through SkiaSharp, which rasterizes fonts natively — parity, not a gap).
Keep Interfaces Out of Docs
Docs teach the normal path through GumService and the concrete classes. IGumService and the other interfaces are explained once, in docs/code/gum-code-reference/gumservice-gumui/README.md. Mention an interface elsewhere only when the concrete member returns null or cannot be used (for example GumUI.Cursor while a custom cursor is installed).
File Location and SUMMARY.md
All docs live under docs/. docs/SUMMARY.md is the master table of contents — GitBook navigation is built entirely from it. A file not listed in SUMMARY.md is unreachable from the nav even if it exists on disk.
Every new file must be added to SUMMARY.md with a 2-space indent per nesting level:
* [Section](gum-tool/section/README.md)
* [Page Title](gum-tool/section/page.md)
* [Sub-page](gum-tool/section/sub/page.md)Paths in SUMMARY.md are relative to docs/.
README.md as Section Landing Pages
A README.md inside a folder is the section's landing page. In SUMMARY.md, link it as folder/README.md. Sub-pages of that section are indented under it.
Image Paths
All images live in docs/.gitbook/assets/. Reference them using a depth-relative path from the page file:
- From
docs/gum-tool/gum-elements/general-properties/x-units.md→../../../.gitbook/assets/filename.png - From
docs/gum-tool/gum-elements/skia-standard-elements/arc/README.md→../../../../.gitbook/assets/filename.png
Image filename convention: date-time prefix like 15_06 10 06.png (day_hour minute second) or 08_14 21 31.gif. Spaces in filenames require wrapping the path in <> angle brackets in standard Markdown image syntax: . In <figure> tags the src attribute handles spaces without angle brackets.
Take starting screenshots without being asked. When a docs change describes something visible in the Gum tool or in a rendered result, take the screenshots yourself, cropped tight, named by the convention above, and wrapped in the same <figure> markup as neighboring pages. Pages under docs/gum-tool/ use the editor: dark theme, only the canvas with its checker background, nothing selected unless the page is about the tool UI. Pages under docs/code/ use a render of the running game or a sample, not the editor. The user reviews and replaces the images later, so skip red arrows and do not chase a perfect match.
Some images use a generic image (N).png naming pattern with numeric suffixes like image (13) (1).png — these are GitBook-uploaded files; don't rename them.
GitBook-Specific Syntax
Hint blocks — must always have a closing {% endhint %} tag or the page breaks:
{% hint style="info" %}
Content here.
{% endhint %}
{% hint style="warning" %}
Content here.
{% endhint %}Figure blocks — used for images with captions. Always include alt attribute and <figcaption>:
<figure><img src="../../../.gitbook/assets/filename.png" alt=""><figcaption><p>Caption text</p></figcaption></figure>For inline images without captions, use standard Markdown: .
HTML entities —   (space) and d (d) appear in GitBook-generated content for spacing and special characters. Do not strip them; GitBook uses them intentionally.
Cards for listing subpages — GitBook auto-lists subpages only on a page with no content, so a landing page that has intro text needs an explicit list. A Cards table in raw HTML renders correctly (see adding-initializing-gum/README.md). The second cell's href is the page path relative to the file, and GitBook fills in the card title from the first cell:
<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td>Card title</td><td><a href="page.md">page.md</a></td></tr></tbody></table>Previewing Docs Changes
Every PR that touches docs/ gets two GitBook checks. Run gh pr checks <number> and open the GitBook (./docs) - docs.flatredball.com/gum/ link for a live preview of the rendered site, or the GitBook (./docs) link for the diff in the GitBook editor. Check the preview before reporting a docs change as done, since GitBook-specific markup (cards, hints, tabs) can only be confirmed there.
Internal Links
Always use relative paths — no absolute URLs. Link to a section landing page using its README.md:
[Container](../container/README.md)Do not use anchor-only links to other files (e.g., [foo](other-file.md#section) is fine, but [foo](#section) only works within the same page).
Tool Docs vs Code Docs
The docs have two top-level sections — Gum Tool (docs/gum-tool/) and Code (docs/code/). These must never be mixed:
- Tool docs (
gum-tool/) describe the Gum UI tool — properties, editors, menus, and workflows within the tool. They should not contain C# code samples or reference runtime APIs. - Code docs (
docs/code/) describe using Gum at runtime in game code — C# APIs, Forms controls, layout in code, etc. They should not describe how to use the Gum tool UI.
When writing a tool doc page (e.g., a property page under gum-elements/), focus entirely on the tool experience: what the property does visually, where it appears in the UI, and screenshots showing the effect. Do not add code examples showing how to set the property in C#. Conversely, code doc pages should not walk through the tool's UI.
Per-runtime supported-file facts live on the one code page docs/code/files-and-fonts/supported-files.md; tool pages describe what the tool supports, and a code page never links to a tool page for runtime facts.
Decide the page's home before writing: if the feature is something the tool ships or edits (built-in shaders, templates, Forms themes, variables and their rows), its main page is a tool page; the code page covers only the generic runtime API that any user-supplied asset uses, and never describes a tool-shipped asset or says "ships with Gum". Check every new section against this split before presenting it.
Cross-Cutting Topics (Binding, Localization, Theming)
Some features cut across many controls — binding, localization, theming, code generation — and individual controls have control-specific behaviors that intersect with them. For example, TextBox.Text can be bound to a numeric ViewModel property and the binding implicitly converts string ↔ number; ListBox interacts with BindingContext differently than other controls; localized labels behave differently in PasswordBox.
The convention for these:
- Document the system-level behavior in the feature's own section. Someone hitting the feature for the first time will look there. Binding rules go in
docs/code/binding-viewmodels/, localization rules in the localization section, etc. This is the single source of truth. - Add a brief note on the control's page with a short example and any control-specific gotchas, then link back to the feature page for the general rule (e.g.
[Implicit Type Conversion](../binding-viewmodels/advanced-binding-options.md#implicit-type-conversion)). Do not duplicate the system-level explanation — trust the reader to follow the link.
The control-page note exists so that a reader troubleshooting "why doesn't my int binding take" while reading the TextBox page finds what they need without bouncing around. The feature-page section exists so that a reader learning the binding system isn't surprised later. Both audiences are real; the split avoids both blind spots without duplicating content.
Date-Specific Content Goes in Hint Blocks
Anything that is only true relative to a release date — "as of <month> <year>", "before <date>", "in <version> X changed" — must live in a {% hint %} block, not in the body paragraphs of a section. Phrase the surrounding prose in terms of current behavior so it stays correct after the dated note is removed.
Why: dated notes eventually become noise once enough time has passed (everyone reading the docs is on the new behavior). Keeping them in hint blocks gives a single, visually obvious anchor to delete later instead of forcing the author to re-read every paragraph hunting for embedded dates.
Pattern:
The Font Generator project property controls ... There are two options:
* **KernSmith** — ... This is the default for new projects.
* **BMFont** — ... a separate external tool.
{% hint style="info" %}
**As of May 2026:** New projects default to **KernSmith**. Before this, the default was **BMFont**. Existing projects keep their current setting.
{% endhint %}Not this — date leaks into body bullets, so removing the dated context later means rewriting prose:
* **KernSmith** — ... Default for new projects starting in May 2026.
* **BMFont** — ... Was the default before May 2026.This applies to: "as of <date>", "starting in <date>", "before <date>", "in version X", "the May 2026 release", and any "what changed in <release>" section heading. When in doubt: if deleting the sentence later would leave the surrounding paragraph still accurate, it's safe in the body; if deleting it would leave a contradiction or dangling reference, lift it into a hint.
Flag Release Status for New Features
Before documenting a new feature or behavior, ask the user whether it has already shipped, is out in preview, or hasn't shipped yet — they usually know offhand, which is faster than investigating. Only investigate yourself when they don't know: walk the feature's commits with git merge-base --is-ancestor <commit> <sha> against the commit each candidate NuGet build was made from, then confirm against the live NuGet feed.
"Shipped" means published to NuGet (stable or preview), not merged to main. Runtime NuGet packages publish on a separate, manually-triggered workflow (dotnet-nuget.yaml) from the Tool's near-daily GitHub Releases (build-and-release.yml) — a feature on main, or even bundled into a dated Tool release, can sit unpublished to NuGet for days.
Then flag accordingly in a {% hint style="info" %} block (same pattern as dated content above):
- Not yet shipped —
Available in <next calendar month> <year>, or now if building Gum from source.Next month is always the target; don't ask the user which release. - Shipped in preview — note that it's a preview feature.
- Fully shipped — no flag; write it as current behavior.
Monthly Migration Pages
A docs/gum-tool/upgrading/migrating-to-<year>-<month>.md page needs What Changed at a Glance only when one point is critical and wide-reaching, such as a hard break most readers hit (migrating-to-2026-october.md is the model). Otherwise leave the section out: the ### headings under Breaking Changes and Migrations already list each change, so a summary of them adds nothing. Never use a stock lead-in over a bullet list ("Two changes need your attention:").
Each entry lists only what a user must do after upgrading. Leave out descriptions of internal or generated-code changes that need no action, and leave out additions: new members, new APIs and new options are release-notes material, never a migration entry. Before keeping a section, ask what the reader would do differently; if nothing, delete it.
Prose Style: Clarity Beats Brevity
Cut length that adds reading, never length that adds understanding. Density and clarity are separate axes, and a longer sentence that lands the first time beats a compressed one the reader has to decode. Trimming a page is not the same as making it clearer, and a reader who has to re-read a sentence has not been saved anything.
Three habits that cost words without buying understanding:
- Restating a claim as its own negation. "The font is generated automatically, not something you opt into" is one fact wearing two coats. Keep the positive half and delete the rest.
- Naming the mechanism instead of the effect. A reader wants to know what changes on screen and which property to set. The internal class, cache, or algorithm that does it belongs in a skill or a code comment, not in a user-facing page, unless the reader has to call it.
- Imperatives that hide the subject. "Set
Fontto a.ttfpath to bypass family lookup" makes the reader the subject and the property an object. Make the property the subject so the line reads as reference material a reader can scan.
Read-aloud test. If a clause repeats the clause before it, or the sentence runs out of breath, rewrite it. Do not shorten it.
❌ "Set text.Font to a path ending in .ttf to bypass family name resolution and route the value through the file backed rasterization path rather than the operating system font lookup. This happens automatically, and there is nothing to enable."
✅ "Gum loads a Font value ending in .ttf as a font file rather than looking it up as an installed font family. It decides this from the extension alone, so there is no setting to turn on."
Run this as a pass before committing, not only while drafting. The mechanical rules on this page (em dashes, {% endhint %} pairs, placement comments, SUMMARY indentation) can be grepped, and the prose rules cannot, so they are the half that silently gets skipped. Re-read every new or edited paragraph against the three habits above and against the passive-voice rule under Tone and Style.
Tone and Style
- Second person ("you"), present tense, instructional tone.
- Use numbered lists for procedures; bullet lists for non-sequential items.
- Bold UI element names: menu items, button labels, tab names, category names shown in the tool (e.g., Source category, Variables tab).
- Backticks for property names, variable names, property values, file names, and code:
Width Units,Relative To Children,Is Tiling Middle Sections. - Avoid passive voice, prefer "Gum displays a label" over "a label is displayed."
- Never mix informing and instructing. A sentence either says what something is or shows (no imperative, no "you can ... to ..."), or it is a numbered step that names where to act and what the reader then sees.
- Screenshots (
.png) for single states; animated GIFs (.gif) for multi-step interactions. Use them liberally. - Do not document error and warning states or every dialog option. The tool's own tooltips and messages own that. Use one screenshot per distinct task step, two at most per page, and match the length of the sibling pages.
- Do not copy a list of values the tool or code owns into prose (platforms, themes, file formats, dialog options, version limits). Name the control and let the tool show the values, or link to the one page that owns the list.
- Never use an em dash (—). Use a comma, period, or parenthetical instead. Check new/edited text for the character before finishing a doc pass.
- Prefer plain language over jargon when a plainer phrasing says the same thing; keep Gum's own terms (control names, property names) since those are what readers need to look up.
- Avoid hyphenated compound phrases where a plainer wording works.
- After writing, re-read a passage and ask whether someone with no technical background could follow it; simplify if not, without dropping needed Gum keywords.
- Gum docs never mention FlatRedBall 1 (FRB1). It has its own docs, differs from Gum use far enough that a note here does not help, and is in maintenance mode while FRB2 replaces it. Do not add new "FRB works differently" text or sections. Leave existing mentions alone.
- Describe how to use a feature, not where it is missing. Do not add lists of platforms or elements that lack a feature, or paragraphs about how one platform differs (Raylib included). Document the behavior users get by following the instructions.
- Do not document behavior owned by a third party that can change without Gum changing, such as .NET runtime or JIT quirks, SDK or compiler settings, and bugs in MonoGame, SkiaSharp or other dependencies, and their workarounds. It goes stale when the third party ships a fix, and nothing in this repo flags it. Put it on the issue instead. A dated hint block does not fix this.
Code Sample Placement Comments
Every \``csharp` block must have a placement comment as its first line so readers and agents know where the code belongs.
| Comment | Meaning |
// Initialize | Runs once right after GumUI.Initialize. Use this by default. |
// Update | Code that runs each frame in the update loop. |
// Draw | Code that runs each frame in the draw loop. |
// Class scope | Field or property declarations at class level. |
// In CustomInitialize | Code specifically in a generated partial CustomInitialize() method. |
When to omit the comment:
- Non-game types shown as their own type definition (ViewModels, enums, partial generated classes).
usingstatements — self-evident, no comment needed.
Mixed-scope snippets get one marker per part, with no class wrapper and no method signatures:
// Class scope
int clickCount;
// Initialize
var button = new Button();
button.Click += (_, _) => clickCount++;
// Update
GumUI.Update(gameTime);Runtime-Neutral Snippets
Snippets outside MonoGame-only pages show no Game class, no override methods and no GumUI.Initialize call; they start after Gum is initialized and use the markers above. The markers are defined for readers in docs/code/getting-started/setup/adding-initializing-gum/README.md. Per-frame calls are written GumUI.Update(gameTime); and GumUI.Draw();. A page that needs a Gum project loaded links to getting-started/setup/loading-a-gum-project-.gumx.md (or reads ObjectFinder.Self.GumProjectSave) instead of showing the load call. Host setup never gets per-runtime tabs; it lives only on the runtime setup pages.
A page may stay MonoGame-only when it is a runtime setup page or uses MonoGame-only types (SpriteBatch, GraphicsDevice, RenderTarget2D, GumBatch, Window). Its title, intro or the line before the sample says so.
Irreducible per-platform syntax → tabs, don't ask. First try to collapse a sample to a single platform-neutral form. When an API genuinely differs per runtime (for example opening bundled content with TitleContainer), wrap just those blocks in GitBook {% tabs %} with one {% tab %} per platform (e.g. MonoGame / Raylib). This is the standard, expected treatment for irreducible divergence; use it without asking. Keep the surrounding prose shared above/below the tabs — only the code that truly differs goes inside. Don't assume a member's type differs per backend from memory (e.g. KeyCombo.PushedKey, KeyEventArgs.Key) — check current source, since Gum has been steadily unifying input types onto Gum.Forms.Input.Keys across backends.
Runtime Setup Pages
Each page in docs/code/getting-started/setup/adding-initializing-gum/ has the same shape, with monogame-kni-fna/README.md as the model: a Starting From a New Project section on platforms gumcli new --platform supports, a complete program that builds with only the base package and loads no .gumj, then an Optional Extras table (package plus the one Use*() line per extra) and a Loading Your Gum Project section (the .gumj Initialize line plus the csproj copy rule). Never put optional Use*() calls or a .gumj path in the complete program, since a reader who skipped a package must still get a build that runs.
XnaFiddle Links
For adding or updating XnaFiddle interactive links, see xnafiddle.md.
Code Sample Rules
- Values a sample reads from outside the code block get a comment showing what they contain. That covers translation keys, content files, project assets and configuration, so the code block makes sense without reading the prose.
- Parallel samples share one design. When a page shows the same task in two forms (code-only vs. a generated screen, MonoGame vs. raylib), a design change to one sample (where navigation lives, how the classes are split up) gets applied to the others in the same pass, or the page explains why they differ.
- One-time initialization goes first, never mid-sample — put all startup/registration calls (e.g.
GumUI.UseKeyboardDefaults(),GumUI.UseGamepadDefaults(), input-device registration, service configuration) at the top of the sample, right under the// Initializecomment whereGumUIis set up — before the feature code. Readers copy a sample as one block, so a setup call buried between feature lines reads as part of the feature logic and is confusing. Group setup first, then the feature it enables. Bad: create the control, add items, thenUseKeyboardDefaults(), then wire focus. Good:UseKeyboardDefaults()first, then create the control and wire focus. - No reflection — never use
GetType(),typeof(),MemberInfo, or anySystem.ReflectionAPIs in doc code samples. Useispattern matching instead:if (device is Gum.Input.Keyboard). The one exception istypeof(T)on a generic type parameter, whichiscannot replace, as in anIContentLoadersample branching on the requested asset type. - Keys are always
Gum.Forms.Input.Keys.X, fully qualified. MonoGame files usually already haveusing Microsoft.Xna.Framework.Input;, so a bareKeysis ambiguous (CS0104) once Gum's namespace is imported. Never writeMicrosoft.Xna.Framework.Input.Keysin a sample that calls a Gum API, and apply the same to samples underSamples/. - Fully qualify non-Gum types — any type that is not part of the Gum API must use its fully qualified name. For example, use
System.DateTimenotDateTime. Do not rely on implicitusingstatements for non-Gum types. - Prefer visible output over console output — by default, surface a sample's result in the UI itself (update a visible label, change a property on a displayed object) rather than logging it. This keeps the sample XnaFiddle-runnable and lets a reader see the effect — e.g. show "You clicked the button" in a
Labelinstead of writing it to the output window. AvoidSystem.Console.WriteLine(requires opening the diagnostics window) andSystem.Diagnostics.Debug.WriteLine(breaks in NetFiddle) on any page intended to be fiddle-able. The one exception is a page whose subject is debugging — where the sample's output is a developer-facing diagnostic that nobody will fiddle (e.g. the events troubleshooting page). There, a breakpoint-and-inspect orDebug.WriteLineis the natural tool and is acceptable; visible-label output would be contrived.
Gotchas
- SUMMARY.md indentation is 2 spaces per level — wrong indentation breaks nesting visually in GitBook.
- A missing
{% endhint %}closing tag breaks all content after it on the page. <figure>tags withoutaltand<figcaption>may not render correctly in GitBook.- The
<figcaption>content must be wrapped in<p>tags:<figcaption><p>Caption</p></figcaption>. - Code blocks in docs use
csharplanguage identifier:```csharp. - Some README.md section pages contain only a brief intro paragraph and a figure — that is intentional; sub-pages provide detail.
- Page titles use
# Title(H1) at the top. Sections within a page use##and###— avoid jumping heading levels. - Image/gif placeholders must be visible — never use HTML comments (
<!-- TODO -->) for placeholders because they are invisible in the rendered docs. Instead use a warning hint block so the placeholder is obvious when browsing the docs.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

