Skip to content

theme

Generates brand-coloured CSS/JS theme files and extension config blocks for your docs framework.

mode="css" produces a ready-to-use extra.css and matching extra.js with your brand colours wired into CSS custom properties. mode="extensions" produces a TOML or YAML config block for Zensical/MkDocs extensions you can paste directly into your config file.

Modes

Mode What it produces
css docs/stylesheets/extra.css with brand colours (default)
extensions A config block for Zensical/MkDocs extensions

When to use it

Run theme after onboard to apply a brand identity, or standalone when you need to update colours without touching the framework config. onboard calls theme internally during full pipeline runs.

Parameters

Parameter Type Required Description
mode string No Output type. Default: "css"
framework string No Target framework. Default: "zensical"
primary_color hex No Primary brand colour. Default: "#1de9b6"
accent_color hex No Accent / highlight colour. Default: "#7c4dff"
dark_mode bool No Include a dark mode palette block. Default: true
font_body string No Body font family, e.g. "Inter"
font_code string No Code font family, e.g. "JetBrains Mono"
output_dir path No Where to save the CSS file. Default: "docs/stylesheets"
theme_name string No Theme identifier used in class names. Default: "custom"
extensions string[] No Extensions to configure in extensions mode
output_format string No Config block format for extensions mode: "toml" or "yaml". Default: "toml"
include_examples bool No Add usage examples as comments. Default: true
target string No What to write: "css-and-js", "css", "js". Default: "css-and-js"

Examples

Generate a custom CSS theme (mode="css")

{
  "tool": "theme",
  "arguments": {
    "mode": "css",
    "primary_color": "#6750A4",
    "accent_color": "#B58900",
    "font_body": "Nunito",
    "font_code": "Fira Code",
    "dark_mode": true
  }
}

Writes docs/stylesheets/extra.css:

/* =========================================================
   mcp-zen-of-docs — Custom theme
   Generated by zen-of-docs theme tool
   ========================================================= */

:root {
  --md-primary-fg-color:        #6750A4;
  --md-primary-fg-color--light: #9C84C8;
  --md-primary-fg-color--dark:  #4A3882;
  --md-accent-fg-color:         #B58900;
  --md-typeset-a-color:         #6750A4;
}

[data-md-color-scheme="slate"] {
  --md-primary-fg-color:        #9C84C8;
  --md-primary-fg-color--light: #C4B3E4;
  --md-primary-fg-color--dark:  #6750A4;
  --md-accent-fg-color:         #DEB955;
}

:root {
  --md-text-font: "Nunito", sans-serif;
  --md-code-font: "Fira Code", monospace;
}

Reference the file in zensical.toml

Confirm extra_css = ["stylesheets/extra.css"] is set. onboard adds this automatically — if you're running theme standalone you may need to add it manually.

Generate a Zensical extension config block (mode="extensions")

{
  "tool": "theme",
  "arguments": {
    "mode": "extensions",
    "extensions": ["pymdownx.highlight", "pymdownx.superfences", "pymdownx.tabbed", "pymdownx.details"],
    "output_format": "toml"
  }
}

Returns a TOML block ready to paste into zensical.toml:

[project.plugins.pymdownx.highlight]
anchor_linenums = true
line_spans = "__span"
pygments_lang_class = true

[project.plugins.pymdownx.inlinehilite]

[project.plugins.pymdownx.superfences]

[[project.plugins.pymdownx.superfences.custom_fences]]
name = "mermaid"
class = "mermaid"
format = "!!python/name:pymdownx.superfences.fence_code_format"

[project.plugins.pymdownx.tabbed]
alternate_style = true
combine_header_slug = true

[project.plugins.pymdownx.details]

YAML alternative

Pass output_format="yaml" for standard mkdocs.yml-compatible YAML. The content is identical — only the serialisation format differs.

  • copilot

    Create Copilot instruction files to keep AI suggestions consistent with your theme.

    Read copilot

  • generate

    Generate visual badge and header assets to pair with your custom theme.

    Read generate