Reference guide for writing Gum documentation in GitBook markdown. Load when writing or editing docs/ files, adding pages to SUMMARY.md, using GitBook hints/figures, linking between pages, or adding images.
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/.
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.
All images live in docs/.gitbook/assets/. Reference them using a depth-relative path from the page file:
docs/gum-tool/gum-elements/general-properties/x-units.md → ../../../.gitbook/assets/filename.pngdocs/gum-tool/gum-elements/skia-standard-elements/arc/README.md → ../../../../.gitbook/assets/filename.pngImage 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.
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.
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.
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).
The docs have two top-level sections — Gum Tool (docs/gum-tool/) and Code (docs/code/). These must never be mixed:
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.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.
Width Units, Relative To Children, Is Tiling Middle Sections..png) for single states; animated GIFs (.gif) for multi-step interactions. Use them liberally.Every \``csharp` block must have a placement comment as its first line so readers and agents know where the code belongs.
| Comment | Meaning |
|---|---|
// Initialize | General initialization — could be Initialize(), CustomInitialize(), a constructor, etc. 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:
using statements — self-evident, no comment needed.Mixed-scope snippets (class members + method bodies): use // Class scope for the member declarations, then show the actual method block(s) with full signatures and indented bodies — no outer class wrapper:
// Class scope
int clickCount;
protected override void Initialize()
{
var button = new Button();
button.Click += (_, _) => clickCount++;
}
Platform-agnostic by default: prefer // Initialize over MonoGame-specific phrasing unless the page is explicitly MonoGame-only. This supports Raylib and other runtimes.
For adding or updating XnaFiddle interactive links, see xnafiddle.md.
GetType(), typeof(), MemberInfo, or any System.Reflection APIs in doc code samples. Use is pattern matching instead: if (device is MonoGameGum.Input.Keyboard).System.DateTime not DateTime. Do not rely on implicit using statements for non-Gum types.System.Diagnostics.Debug.WriteLine (breaks in NetFiddle) or System.Console.WriteLine (requires user to open the diagnostics window). Instead, show side effects directly in the sample itself — e.g., update a visible label or change a property on a displayed object.{% endhint %} closing tag breaks all content after it on the page.<figure> tags without alt and <figcaption> may not render correctly in GitBook.<figcaption> content must be wrapped in <p> tags: <figcaption><p>Caption</p></figcaption>.csharp language identifier: ```csharp.# Title (H1) at the top. Sections within a page use ## and ### — avoid jumping heading levels.<!-- 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.