mkdocs-shadcn 0.11.0

Documentation that also shines

[!IMPORTANT]
This is an unofficial port of shadcn/ui to MkDocs, and is not affiliated with @shadcn.

Documentation

Yes, yes, the documentation is built with this theme.

Quick start

mkdocs-shadcn can be installed with pip (you may also need Pygments for syntax highlighting).

pip install mkdocs-shadcn

Add the following line to mkdocs.yml:

theme:
  name: shadcn

[!NOTE]
MkDocs is stale. You can use ProperDocs as a drop-in replacement.

Extensions

The theme tries to support the built-in extensions along with some pymdownx ones.

• admonition
• codehilite
• fenced_code
• footnotes
• pymdownx.tabbed
• pymdownx.blocks.caption
• pymdownx.blocks.details
• pymdownx.blocks.tab
• pymdownx.progressbar
• pymdownx.arithmatex
• builtin shadcn.echarts
• builtin shadcn.iconify
• builtin shadcn.codexec

Plugins

• builtin excalidraw - With this plugin, you can directly edit your excalidraw scene in dev mode (kind of WYSIWYG) while it is rendered as svg at build time
• mkdocstrings - a MkDocs plugin for auto-generating API documentation from docstrings. (alpha)
• taylor-made autonumber plugin to automatically number and reference some elements (figures, tables, equations...)
• mike - A Python utility that makes it easy to deploy multiple versions of your MkDocs-powered docs to a Git branch.

Developers

This project is open to contributions. In general, we need to apply the shadcn/ui style to already existing plugins or extensions.

We recently release the css sources we use to style the theme. It mainly uses tailwindcss.

Setup

First clone the repo:

git clone https://github.com/asiffer/mkdocs-shadcn
cd mkdocs-shadcn

Then you can install python dependencies (uv required):

uv sync --all-extras

Finally, you can install tailwind with your favourite package manager (npm, yarn, bun, etc.):

bun install

Dev mode

We use the project pages to as a test project for this theme. You can run the local server in the pages/ subdirectory.

cd pages/
uv run mkdocs serve --watch-theme -w ..

In parallel, you are likely to run the tailwind watcher to compile the css sources. In the root folder:

bun dev

Testing

Tests are managed by pytest and are located in the tests/ folder.

Currently we only test that there is no browser issue through playwright.