Writing Rule Files

rule is the plainest file type in the project: name, an optional image, and a description textarea, rendered with no fixed layout beyond a hero image and the description as markdown. Every prose chapter of the SRD — the Introduction, the whole Combat folder, Fatigue, Falling, Hit Locations — is one rule file. This is also the type you reach for when a folder of entries needs a shared introduction, like <@Creature Abilities.rule> or <@Professional Skills Overview.rule>.

What goes in description versus name

name is the chapter or topic title, matching the SRD section it covers — "Falling," "Combat Styles," "Asphyxiation." Keep it short enough to read comfortably as a file listing entry. Everything else — including sub-headings — goes in description as markdown. There is no separate summary field distinct from the frontmatter description used for context visibility; the same text does double duty as the file's searchable summary and its rendered body, so open with a sentence that stands alone if only the summary is ever shown.

Splitting one topic across files

The project already shows the pattern: /Combat/ is one SRD chapter split into twelve files (Combat Overview, Combat Actions, Close Combat, Special Effects, and so on) rather than one enormous file. Split along the same lines the SRD itself uses — a reader should be able to guess which file covers a given rule from its name alone. Don't split so finely that a single mechanic (say, the attack-parry exchange) gets scattered across three files; How Skills Work and Skill Rules for Different Circumstances and Situations show the right grain — one file per genuinely separate concern, not one file per paragraph.

Tables and formatting

Rule files lean on markdown tables constantly — Difficulty Grades, Hit Location rolls, the Competency Level table. Keep using them: a Games Master scanning mid-session wants the table, not three sentences of prose restating it. Bullet lists work well for named sub-cases (Magic Traits, Creature Abilities) where each item is short and mostly independent.

Rules versus the Player's Handbook

This SRD's rule files are the raw reference — comprehensive, exhaustive, written once. The Player's Handbook is a curated retelling of a subset of that material, written to teach a new player rather than to be complete. When you add or change a rule file, ask whether the change also affects what a player needs to know at the table:

• A new spell, skill, or piece of equipment — add the entry (see the relevant chapter below); the handbook doesn't need editing unless it changes a procedure rather than adding a list item.
• A new or changed mechanic — a new Wound tier, a new combat action — update the rule file that owns it, and update the matching Player's Handbook chapter so the taught procedure doesn't drift out of sync with the reference. Never paste the rule prose into the handbook verbatim; the handbook restates it in second person, at a length a player will actually read before a session.

GM-only material does not belong here

rule files are public reference, read by anyone browsing the project — same audience as the Player's Handbook. Secrets, adjudication guidance, or "how hard should the GM actually make this" belongs in a gm-instructions file instead (see Locations, Starts, and GM Instructions), never folded into a rule file's description.