Adding & Editing Pages¶

This site is built with MkDocs Material. You can create and edit pages directly from GitHub's web interface — no local setup required.

Edit an existing page¶

Every page has an Edit this page button in the top-right corner. Click it to open the file in GitHub's editor, make your changes, and commit.

Create a new page¶

Go to the repository on GitHub
Navigate to docs/ and then to the relevant section folder
Click Add file → Create new file
Name the file with a .md extension (e.g., my-page.md)
Add the front matter and content (see below)
Commit — the site rebuilds automatically within ~1 minute
Add the page to mkdocs.yml nav section (see below)

Front matter¶

Every page needs a minimal YAML block at the top:

---
title: My Page Title
description: Brief description for search engines.
---

That's it. Navigation order is controlled by mkdocs.yml, not per-file front matter.

After creating a file, add it to the nav: section in mkdocs.yml:

nav:
  - Projects:
      - projects/index.md
      - My New Project: projects/my-new-project.md  # add here

The key is the display name, the value is the path relative to docs/.

File structure¶

docs/
├── index.md                    # Homepage
├── about.md                    # About page
├── projects/
│   ├── index.md                # Projects section index
│   └── *.md                    # Individual project pages
└── guides/
    ├── index.md                # Guides section index
    └── *.md                    # Individual guides

Markdown features¶

Admonitions (callouts)¶

!!! note
    This is a note.

!!! warning
    This is a warning.

!!! tip "Custom title"
    This is a tip with a custom title.

Renders as:

Note

This is a note.

Warning

This is a warning.

Buttons¶

[Primary Button](https://example.com){ .md-button .md-button--primary }
[Default Button](https://example.com){ .md-button }

Tabbed content¶

=== "Linux / macOS"
    ```bash
    your-command
    ```

=== "Windows"
    ```powershell
    Your-Command
    ```

Grid cards (feature lists)¶

<div class="grid cards" markdown>

- :material-tools: **Feature Name**

    Description of the feature.

- :material-shield: **Another Feature**

    Description of another feature.

</div>

Icons¶

Use :material-icon-name: for Material icons, e.g. :material-github: →

Adding a new project page¶

Create docs/projects/my-project.md:

---
title: My Project Name
description: Short description of the project.
---

# My Project Name

Description...

Then add to mkdocs.yml:

nav:
  - Projects:
      - projects/index.md
      - My Project Name: projects/my-project.md

Security considerations¶

When adding content:

No <script> tags — blocked by Content Security Policy
No external resources — only img.shields.io and avatars.githubusercontent.com images are allowed
No <iframe> elements — frames are blocked
Use relative links for internal pages (e.g., ../guides/security.md)