Skip to content

Contributor Style Guide

This guide defines writing and formatting conventions for PlayMaker documentation. It helps ensure consistency, clarity, and accessibility across all pages.

Writing Style

  • Audience: Assume the reader is a Unity user with varying coding experience. Favor clarity over technical depth.
  • Tone: Friendly, direct, and practical. Avoid jargon unless it’s essential or explained.
  • Voice: Use active voice whenever possible.
  • Tense: Use present tense for explanations (e.g., "The FSM runs actions.").

Content Structure

  • Start pages with a brief, one-line summary of what the feature does.
  • Use task-based headings (e.g., "Selecting Nodes", "Moving States") for UI-related features.
  • Use bulleted lists for options, tips, or behaviors.
  • Use tables to compare items or label numbered diagrams.
  • Keep paragraphs short (1–3 sentences max).

Example:

## :material-select: Selecting Nodes

Click or drag a marquee to select nodes. Hold ++Shift++ to add to the selection.

Index Page Rules

Use these rules for section index.md pages (especially under docs/actions):

  • Keep the index focused on navigation, not deep detail.
  • Use a short summary intro, then section headings, then link lists.
  • Always put a heading above each group of links.
  • Use <div class="grid cards" markdown> for action/category lists.
  • Inside each grid row, use exactly two elements: link/title first, short description second.
  • Keep link labels short and scannable; remove repeated prefixes already implied by the heading.
  • Match link labels to sidebar labels where possible.
  • Keep index list order aligned with sidebar order.
  • If page order is intentional/logical, enforce matching sidebar order via .pages nav.
  • Only add .pages nav when default ordering is not what you want (to reduce maintenance).
  • In sidebars, avoid repeating actions at every level; keep labels concise.
  • For Unity-wrapper categories, add a standard !!! tip "Unity API" callout with the relevant API link.

Terminology

  • Use FSM (not "finite state machine") after first mention.
  • Use state, transition, action, event, and template consistently.
  • Capitalize UI elements exactly as they appear (e.g., PlayMaker → FSM Editor).
  • Format menu paths and UI references using backticks and the Menu → Submenu → Command pattern.

Example:

Use the `PlayMaker → FSM Editor` menu to open the editor.
Choose `GameObject → Create Empty` to add a new GameObject to the scene.

Markdown Formatting

  • Use **bold** for emphasis or important terms.
  • Use inline code for action names, variable names, and code elements.
  • Use standard Markdown links for internal references: [Graph View](../fsm-editor/graph-view.md)
  • Use !!! tip, !!! note, and !!! warning for callouts.
  • Prefer {.ui-image} class for screenshots.
  • Action page titles/headings should use plain names (for example Replace Tile), not arrow-style prefixes like Tilemap -> Replace Tile.

Example:

Use the `Set Position` action to move the object using the `Position` variable.

[Graph View](../fsm-editor/graph-view.md) is where you build your FSM visually.

!!! tip "Quick Tip"
    Use `++F++` to frame selected nodes in the Graph View.

Keyboard Shortcuts

  • The docs use the PyMdown Keys Extension
  • Format shortcuts using ++Key+Action++ (e.g., ++Ctrl+f++, ++Alt+c++)
  • Use + to separate keys and actions (not hyphens)
  • Note: Actions like click, drag, or double-click are not recognized by pymdownx.keys
  • For unrecognized actions, wrap the action in quotes (e.g., ++Ctrl+"Click"++, ++"Double Click"++)

Example:

Hold ++Shift++ to temporarily override snapping.
++"Double Click"++ the canvas to add an FSM.

Icon Usage

  • Use icons to visually reinforce section headings or UI references.
  • Prefer using icon codes (e.g., :material-icon:) instead of inline emojis (e.g., 😄) for consistent rendering in MkDocs.
  • Prefer Material Design icons (:material-*:) and Octicons (:octicons-*:) supported by MkDocs Material (MkDocs icon reference).
  • Icons should match the purpose of the section or element they represent.
  • Place icons before headings with a space, not embedded inside the heading text.
  • Use consistent icon placement across similar pages.
  • Don’t overuse icons - limit them to section headers, toolbar references, or UI concepts for visual scanning.

Example:

## :material-cursor-move: Moving Nodes
## :material-lightning-bolt: Shortcuts
## :octicons-lock-16: Locking the Selection

Renders as:

  • Moving Nodes
  • Shortcuts
  • Locking the Selection

Custom Icons:

  • Mkdocs can import custom svg icons. Make sure the svg file uses currentColor for the fill so it works properly in light and dark themes:
<svg width="128" height="128" viewBox="0 0 128 128" fill="currentColor" xmlns="http://www.w3.org/2000/svg">

Image Usage

Use screenshots and diagrams to illustrate UI features, workflows, or complex behavior.

  • Crop images to focus on relevant areas and reduce clutter.
  • Prefer landscape orientation and standard aspect ratios for consistency.
  • Save images as optimized PNG or JPEG files to reduce page load time.
  • Name image files using lowercase, hyphen-separated names (e.g., graph-view-nodes.png).

Placement and Formatting

  • Place images directly under the paragraph or list they illustrate.
  • Use the {.ui-image} class to apply consistent styling:
![Graph View](../fsm-editor/images/graph-view-nodes.png){.ui-image}
  • Add alt text when meaningful to support accessibility and searchability.
  • Avoid image captions entirely unless absolutely necessary, as they shift image positioning in the layout.

Numbered Images

Use numbered markers in images to label key parts of a UI or diagram. Pair them with a corresponding table below the image.

  • Ensure visual markers in the image are clear and match the order in the table.
  • Use :numbers-1:{.number} through :numbers-9:{.number} in tables if the image uses styled numerals.
  • Keep table descriptions concise and scannable.
  • Avoid repeating details already explained directly above or below the image.
  • To avoid a wide first column, leave the header blank (e.g., | | Element | Description |).

Example

![Graph View](../fsm-editor/images/graph-view-nodes.png){.ui-image}

| # | Element         | Description                                      |
|---|------------------|--------------------------------------------------|
| :numbers-1:{.number} | Graph View       | Build and edit the FSM visually.                |
| :numbers-2:{.number} | State Node       | Represents a unit of behavior.                  |
| :numbers-3:{.number} | Transition Arrow | Connects one state to another via an event.     |

Download Stylized Number Icons

Download SVG number markers to use in Photoshop or Figma:

Download all as ZIP

Tools

Some tools we find useful:

Coming Soon

Future sections may include:

  • ✅ Code block formatting and annotations
  • ✅ Contributor workflow (e.g., pull requests, style review, file naming)

Feel free to propose edits or additions to help improve this guide!