Extending the manual

For game developers. Your game can add a section of its own to this manual, and add pages to a section that is already here. Both are a directory of markdown pages and one call.

Adding a section

1. Make a directory for the pages, for example res://manual/.
2. Write an index.md in it: the section's first page.
3. After integrating the editor, register the directory:

map_editor.register_manual_section(&"game", "My Game", "res://manual", 50)

The first argument is the section's id, used in links. The last places it in the index: core is 10, editor 20, audio 30, navigation 40. Leave it out to put the section last.

unregister_manual_section(&"game") takes it away again.

Adding pages to a section

To document your own entities beside the editor's, add a directory of pages to the editor section, or to any other:

map_editor.register_manual_pages(&"editor", "res://manual/editor")

The pages are listed in that section's index by their order, and link as if they were in the section's own directory. A page with the same file name as one the section already has is ignored. unregister_manual_pages takes them away again.

Writing a page

One page is one .md file with a lowercase, hyphenated name: guard-patrols.md. It starts with front matter, then a single # title matching title:

---
title: Guard patrols
order: 40
keywords: guards, patrol, route, waypoint
---

# Guard patrols

• order sorts the page in the index. index.md is always first. Leave gaps of 10.
• keywords are optional. Search counts them after the title and before the headings.

The manual renders a small part of markdown, and nothing else:

• Headings ## and ### below the title.
• Bold, italic and inline code. Write keys as inline code: Cmd S.
• Bullet and numbered lists, one level of nesting (indent two spaces).
• Tables with a header row.
• Fenced code blocks.
• Callouts: a quote that starts with a bold word, such as > **Tip:**, > **Note:** or > **Warning:**.

No raw HTML, footnotes or task lists.

Tip: Save a page while the manual is open on it, then open it again from the index. The manual reads a page again when its file has changed.

Links

Links are relative paths in a tree of <section id>/<page>.md, whatever directory a page is read from:

A heading's anchor is its text in lowercase, with spaces turned into hyphens and punctuation dropped: ## Closed doors is #closed-doors.

Images

Keep images in an images/ directory beside the pages, as PNG, and reference them relatively. An image on a line of its own is a figure, and its alt text is the caption:

![A guard walking the courtyard route, seen from above](images/guard-patrols-courtyard.png)

An image that is not there yet is drawn as a box with its caption, so a page can be written before its pictures.

Checking pages

The editor's test suite checks every page the Hammerite addons ship: front matter with a title, one # title matching it, and every link and anchor leading somewhere. Run it alone with:

Godot --headless --path tests --script res://addons/hammerite-editor/tests/validate_manual.gd

For your own section, build the manual the way your game does and call validate() on it. It returns one line for each problem:

for problem in map_editor.manual.validate():
    print(problem)

Publishing on a website

docs/manual/publish.sh in the Hammerite repository copies every addon's manual into one directory, one folder per section id, with an index.md that lists the sections. Links work unchanged, so any static site generator that renders markdown can publish it.

docs/manual/publish.sh site/manual
docs/manual/publish.sh site/manual game="My Game":../my-game/manual
docs/manual/publish.sh site/manual editor+=../my-game/manual/editor

id="Title":directory adds a section after the addons'. id+=directory adds pages to a section.

Exporting

A .md file is not a resource, so an export would leave it out. Hammerite packs them itself: every installed addon's manual/ directory goes into the export whether or not the preset's filters mention it.

Pages of your own that live outside an addon are not found that way. List their directories in Project Settings → Hammerite → Manual → Export Directories, or add *.md to Filters to export non-resource files/folders in the export preset's Resources tab — either works.

Only the pages directly in a listed directory are packed, which is the same set register_manual_pages reads from it.