Documentation Guidelines

General Information

The primary rule is simple: documentation must actually be maintained. 😏

All documentation is stored directly in the git repository as .md files.
Whenever changes are pushed to the game's codebase, changes to the corresponding documentation articles must be pushed simultaneously.

A static site generator, MkDocs, is used to generate the documentation website from these article files.

Public and Internal Documentation

The documentation website has two versions:

• Public — contains only public documentation.
• Full — contains both public documentation and internal documentation.

Because of this, when writing documentation, keep the following rule in mind:

• Links from internal documentation to public documentation are allowed.
• Links from public documentation to internal documentation are strictly prohibited.

Public documentation serves as the player knowledge base. It describes the entities available in the game, their characteristics, gameplay mechanics, and may also include guides, tutorials, and similar materials.

Internal documentation contains technical documentation for the development team as well as various development rules and guidelines.

Documentation Directory Structure

The directory structure is designed so that a static website can be generated from it automatically. Since the website is the primary output of the documentation system, the established directory structure must be followed precisely, strictly, and without exception.

The structure also includes built-in multilingual support. 😎

Overall Structure

docs/
│
├── articles/                                # Source articles
│   │
│   ├── index.md                             # Home page
│   ├── index.en.md                          # English home page
│   │
│   └── 01-some-section/                     # Documentation section
│       ├── 001-some-article.md              # Article
│       ├── 001-some-article.en.md           # English translation
│       └── _attachments/                    # Section attachments
│           ├── some-pic.png
│           └── some-pic.en.png
│
├── _assets/                                 # Styles, icons, etc.
│
└── site/                                    # Website build directory
    │
    ├── config/
    │   ├── mkdocs.template.yml              # MkDocs configuration template
    │   └── requirements.txt                 # Python dependencies
    │
    ├── ShadowCell.SiteBuilder/              # Website builder project
    │   ├── ShadowCell.SiteBuilder.csproj
    │   └── Program.cs
    │
    └── build/
        ├── mkdocs.yml
        ├── public/
        └── full/

Article Source Directory

Documentation sections are represented by directories, while the articles themselves are .md files.

Directory and file names must begin with an index.

This index determines the order of sections and articles during automatic website generation.

Since directory and file names also define the page URL, they must use kebab-case.

Both the numeric index and the words in the name are separated with hyphens (-).

Documentation Sections

Section directory names must use two-digit indices (01, 02, etc.).

Nested sections are allowed.

Nested directories follow the same numbering scheme independently—the parent directory index is not included in the child index.

Article Files

Article filenames must use three-digit indices (001, 002, etc.).

Each article must contain exactly one H1 heading, which becomes the page title on the generated website.

Additional Markdown formatting rules can be found in the Markdown linter configuration (see the config/ section).

YAML Front Matter may be placed at the beginning of the file before the H1 heading.

Primary File

Russian is the default language for the documentation.

Therefore, the Russian version does not use a language suffix:

001-some-article.md

Translation File

Translated files must be placed alongside the primary language file.

Their filenames must match the original filename with an additional language suffix.

For example:

• Russian: 001-some-article.md
• English: 001-some-article.en.md

There is no translation "magic" involved. 🧙‍♂️

Each translation file must contain the complete article written in the target language.

Attachments

All attachments belonging to a documentation section (that is, a single article directory) must be stored in the _attachments/ folder.

If an attachment—for example, an image—contains Russian text, a separate localized version should be created for other languages.

In this case, the localized image should also receive the language suffix:

some-pic.png
some-pic.en.png

Diagrams and Visualizations

Recommended Standard: Mermaid

For diagrams and other visualizations, using Mermaid blocks directly inside Markdown files is strongly recommended, since Mermaid is supported out of the box by most Markdown editors and by MkDocs during website generation.

Mermaid can be used to create:

• Flowcharts — gameplay logic, upgrade trees, purchasing conditions.
• Sequence Diagrams — client/server/database communication, authorization flows, match log submission, etc.
• State Diagrams (State Machines) — defense node behavior, animation phases, lobby connection states.
• Class Diagrams — core architecture and relationships between entities.
• User Journey / UI Flow — navigation between game menus and interface screens.

Complex Diagrams

If Mermaid is insufficient (for example, when custom graphics, advanced UML, or very large mind maps are required), specialized tools such as Draw.io or PlantUML (.puml) may be used.

Rules for complex diagrams:

1. Source files (.drawio, .puml) must be stored in the repository inside the _attachments directory.
2. Export the final diagram as a vector SVG file (bitmap images lose quality when scaled).
3. Insert the SVG into the Markdown document using the standard Markdown image syntax.

Website Build Directory

config/

The docs/site/config/ directory contains the following configuration files:

• requirements.txt — Python dependency list used to install MkDocs plugins.
• mkdocs.template.yml — template for generating the MkDocs configuration file.
• .markdownlint.yaml — Markdown linter rules for documentation articles.

Website Builder Project

A small .NET project responsible for building the documentation website.

Its primary purpose is to generate the final mkdocs.yml configuration file from the mkdocs.template.yml template by applying the selected build settings.

Before generating the website, the builder also validates all Markdown articles according to the configured Markdown linter rules.

build/

This directory contains:

• the generated mkdocs.yml configuration file;
• the generated public documentation website (public/);
• the generated full documentation website (full/).

Naturally, these build artifacts must not be committed to the repository.

Website Generation

Formatting Details

Website Navigation Menu

The website navigation menu is generated automatically from the directory structure and Markdown files in alphabetical order.

This is why directory and file names must include numeric indices—they define the order of menu items.

Article titles are automatically taken from the H1 heading inside each Markdown file.

Section titles are derived from directory names by default.

However, folder names such as 03-gameplay are not suitable as navigation labels.

Therefore, human-readable section names must be defined manually in the MkDocs template file:

docs/site/config/mkdocs.template.yml

Specifically, in the translation plugin configuration:

• the key is the folder name with - and _ replaced by spaces (for example, 03 gameplay);
• the value is the display name shown in the navigation menu (for example, Gameplay).

At first glance this may seem confusing, but the template file itself should make the configuration much clearer.

As a result:

• article order is determined automatically by the directory structure;
• section order is determined automatically by the directory structure;
• article titles are taken automatically from H1 headings;
• section titles are defined manually in the MkDocs configuration template.

Additional Formatting Features

Admonition Blocks

To highlight information inside framed callout blocks (information, warnings, notes, etc.), use MkDocs admonitions.

Examples:

!!! info "Gray background with a blue information icon"

!!! terminal "Blue background with a pencil icon"

!!! danger "Red background with a lightning icon"

Most Markdown editors do not render these blocks.

However, they are displayed correctly on the generated MkDocs website.

Console Commands

Installing MkDocs Dependencies

Run the following command from the repository root:

pip install -r docs/site/config/requirements.txt

Building and Running the Documentation

All examples below assume that the commands are executed from the repository root.

General Syntax

dotnet run --project docs/site/ShadowCell.SiteBuilder -- <command> <mode> [options]

Where:

• <command>
• serve — starts the local documentation web server.
• build — generates the static documentation website.
• <mode>
• public — builds or serves only the public documentation.
• full — builds or serves the complete documentation.
• [options]
• --no-lint — disables Markdown lint validation during build or startup.

Examples

Start the Local Documentation Server

dotnet run --project docs/site/ShadowCell.SiteBuilder -- serve public
dotnet run --project docs/site/ShadowCell.SiteBuilder -- serve full

Build Static Documentation

dotnet run --project docs/site/ShadowCell.SiteBuilder -- build public
dotnet run --project docs/site/ShadowCell.SiteBuilder -- build full

Start Without Markdown Linting

dotnet run --project docs/site/ShadowCell.SiteBuilder -- serve public --no-lint
dotnet run --project docs/site/ShadowCell.SiteBuilder -- serve full --no-lint

Build Without Markdown Linting

dotnet run --project docs/site/ShadowCell.SiteBuilder -- build public --no-lint
dotnet run --project docs/site/ShadowCell.SiteBuilder -- build full --no-lint

Recommended Tools

Obsidian is the recommended editor for writing and maintaining documentation.

Why Obsidian:

• Convenient Markdown editing.
• Simple attachment management.
• Reliable handling of links between articles.
• Automatic link updates when files are renamed.
• Easy navigation through the documentation structure.
• Interactive graph view showing relationships between articles.

Of course, other editors may also be used.

In some cases, editing Markdown files directly in an IDE may even be more convenient, since Git changes are immediately visible.

Regardless of the editor used, the author of the changes is responsible for ensuring that:

• the directory structure has not been altered;
• links between articles remain valid;
• all attachments are stored in the _attachments directory of the corresponding documentation section;
• the documentation is rendered correctly by MkDocs and passes Markdown lint validation.

Initial Obsidian Setup

Step 1

Open Obsidian.

Choose:

Open folder as vault

Then select the following directory from the game repository:

docs/articles/

Step 2

Configure Attachments

Navigate to:

Settings → Files and links

Locate:

Default location for new attachments

Select:

In subfolder under current folder

Specify the folder name:

_attachments

From now on, whenever an image is pasted into an article, Obsidian will automatically create the _attachments directory (if necessary) and place the image there.

Step 3

Configure Links

Navigate to:

Settings → Files and links

Locate:

New link format

Select:

Relative path to file

This ensures that links remain portable and continue to work correctly when the documentation is moved or cloned.

Step 4

Enable Recommended Core Plugins

Navigate to:

Settings → Core plugins

Enable the following plugins:

• Backlinks
• Page Preview
• File Recovery
• Outline (automatically generates the article table of contents from headings)