Mkdocs

What it does

When your agent uses it

• Initializing a MkDocs site
• Configuring mkdocs.yml
• Customizing the Material theme
• Integrating plugins

Example prompts

• “Use the mkdocs skill to mkdoc documentation project reference covering CLI commands, mkdocs.yml configuration, Material theme setup, and plugin…”
• “/mkdocs”

Requirements

• Python 3

What it can do on your machine

Read from SKILL.md and the folder at commit b463563. It shows what the files ask for, not the result of running them.

• Tool permissions

  Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

  From allowed-tools in the SKILL.md frontmatter.

• Runs code

  Ships 1 file in scripts/ (Python), which the agent can run.

  Shell commands in SKILL.md call:

  • pip

  From the folder's file list and the shell code blocks in SKILL.md.

• Network

  Hosts in commands or code, which the agent is likely to contact:

  • github.com
  • unpkg.com

  From URLs in SKILL.md, links to its own repository left out.

• Credentials

  Names no API keys, tokens, secrets or passwords.

  From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Mkdocs loads about 2k tokens when it runs, and up to ~24k if it reads all its reference files. Until then it costs about 146 tokens; SKILL.md has 366 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it

~146

When it runs · the whole SKILL.md, loaded when a task matches

~2k

With references · SKILL.md plus every file in references/, read only if the agent opens them

~24k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from jeka-dev/jeka at commit b463563, republished under its Apache-2.0 licence (© jeka-dev). 366 words, ~1,980 tokens.

name

mkdocs

description

MkDocs documentation project reference covering CLI commands, mkdocs.yml configuration, Material theme setup, and plugin integration. Bundled references include complete CLI parameters, all mkdocs.yml settings with valid values, Material theme customization options, and plugin configs for mkdocstrings, mermaid2, mkdocs-gen-files, mkdocs-literate-nav, and mkdocs-typer2. Use when initializing a MkDocs site, configuring mkdocs.yml, customizing the Material theme, integrating plugins, building static docs from Markdown, or generating API documentation from Python docstrings.

What do you need to do?
│
├── Initialize a new site ──────────────────→ [Init]
├── Fix / improve mkdocs.yml ───────────────→ [Configure]
├── Customize the Material theme ───────────→ [Theme]
├── Add or configure plugins ───────────────→ [Plugins]
├── Improve doc content / structure ────────→ [Content]
└── Deploy (GitHub Pages, CI) ──────────────→ [Deploy]

pip install mkdocs-material
mkdocs new my-project
cd my-project
mkdocs serve   # preview at http://127.0.0.1:8000

site_name: My Project
theme:
  name: material
  font:
    text: Roboto
    code: Roboto Mono
  features:
    - navigation.instant
    - navigation.tracking
    - content.code.copy

repo_url: https://github.com/org/repo
edit_uri: edit/main/docs/

# ✅ Correct
repo_url: https://github.com/org/repo
edit_uri: edit/main/docs/

# ❌ Wrong — edit_url under theme: is ignored
theme:
  edit_url: https://github.com/org/repo/main/docs/

nav:
  - Home: index.md
  - Installation: installation.md
  - Tutorials:
      - Basics: tutorials/basics.md
  - Migration Guide: migration-guide.md   # don't forget orphan files

not_in_nav: |
  api/**
  tags.md

strict: true

theme:
  name: material
  palette:
    - scheme: default
      primary: deep purple
      accent: purple
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode
    - scheme: slate
      primary: deep purple
      accent: purple
      toggle:
        icon: material/brightness-4
        name: Switch to light mode

theme:
  font:
    text: Inter          # body text — any Google Font
    code: Fira Code      # monospace — must be a valid Google Font name

theme:
  font: false

theme:
  features:
    - navigation.instant       # SPA-style instant loading
    - navigation.tracking      # anchor tracking in URL
    - navigation.tabs          # top-level sections as tabs
    - navigation.sections      # render sections in sidebar
    - navigation.expand        # expand all sections by default
    - navigation.top           # back-to-top button
    - navigation.footer        # prev/next links in footer
    - toc.follow               # sidebar TOC follows scroll
    - content.code.copy        # copy button on code blocks
    - content.action.edit      # "Edit this page" button (requires edit_uri)
    - search.suggest           # search autocomplete
    - search.highlight         # highlight search terms on page

theme:
  logo: images/logo.svg
  favicon: images/favicon.png
  icon:
    repo: fontawesome/brands/github

markdown_extensions:
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
extra_javascript:
  - https://unpkg.com/mermaid@10/dist/mermaid.min.js

plugins:
  - search:
      separator: '[\s\-\.]+'
      lang: en

plugins:
  - git-revision-date-localized:
      enable_creation_date: true
      type: timeago

plugins:
  - mkdocstrings:
      handlers:
        python:
          options:
            docstring_style: google
            show_source: true

!!! note
    Use for supplementary information.

!!! tip
    Use for helpful hints.

!!! warning
    Use for potential pitfalls.

??? example "Collapsible example"
    Hidden by default, click to expand.

```python title="my_module.py" hl_lines="2 3"
def hello():
    name = "world"
    print(f"Hello {name}")
```

=== "Python"
    ```python
    print("hello")
    ```

=== "Java"
    ```java
    System.out.println("hello");
    ```

# .github/workflows/docs.yml
name: Deploy docs
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0   # needed for git-revision-date plugin
      - uses: actions/setup-python@v5
        with:
          python-version: '3.x'
      - run: pip install mkdocs-material
      - run: mkdocs gh-deploy --force

© jeka-dev, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 8 other files (scripts, references, assets) in .claude/skills/mkdocs of jeka-dev/jeka.

• SKILL.md
• .skillfish.json
• assets/example_asset.txt
• references/cli_reference.md
• references/configuration_reference.md
• references/material_theme_reference.md
• references/plugins_reference.md
• references/real_world_examples.md
• scripts/example.py

Open the folder on GitHubat commit b463563