Install

Add the package to your project.

pip install mkdocs-shadcn

uv add mkdocs-shadcn

poetry add mkdocs-shadcn

If you want to use pymdown extensions, you can also install the pymdown-extensions package:

pip install pymdown-extensions

uv add pymdown-extensions

poetry add pymdown-extensions

Configure

The theme configuration is roughly the contract with the users. When it changes, we increment the major version of the package (or minor in the 0.X.Y case). Currently the theme does not provide so many options.

# mkdocs.yml
site_name: "awesome-project"
theme:
  name: shadcn
  show_title: true # show the title in the top bar
  show_stargazers: true # show the stargazers in the top bar
  pygments_style: # default styles 
        light: shadcn-light
        dark: github-dark
  icon: heroicons:rocket-launch # use the shadcn svg if not defined
  topbar_sections: false # NEW!
  katex_options: # optional
    macros: # example of macros
      "\\RR": "\\mathbb{R}" 
      "\\dx": "\\mathrm{d}x"
  show_datetime: false 

show_title: bool

If false, only the icon will be visible in the top bar (left-side). Default to true.

show_stargazers: bool

If false, hides the GitHub stargazers besides the repo icon in the top bar (right side). Default to true.

pygments_style: str | dict

Define the pygments style for the code blocks. Supported styles are given below. If a single theme is provided, it is applies for both light and dark themes. If a dictionary is provided, it should contain light and dark keys with the respective styles.

a11y-dark a11y-high-contrast-dark a11y-high-contrast-light a11y-light abap algol algol_nu arduino autumn blinds-dark blinds-light borland bw coffee colorful default dracula emacs friendly friendly_grayscale fruity github-dark-colorblind github-dark github-dark-high-contrast github-light-colorblind github-light github-light-high-contrast gotthard-dark gotthard-light greative gruvbox-dark gruvbox-light igor inkpot lightbulb lilypond lovelace manni material monokai murphy native nord nord-darker one-dark paraiso-dark paraiso-light pastie perldoc pitaya-smoothie rainbow_dash rrt sas shadcn-light solarized-dark solarized-light staroffice stata-dark stata-light tango trac vim vs xcode zenburn

def fibonacci(n):
    a, b = 0, 1
    for _ in range(n):
        yield a
        a, b = b, a + b

for num in fibonacci(10):
    print(num)

icon: str

Sets the top-left icon. If not defined, the default shadcn icon is used. You can either pass an image URL or an iconify class.

topbar_sections: bool

If true, the top level sections (i.e. top level directories of the docs) will be displayed in the top bar (and not in the sidebar). It allows to have a deeper navigation tree within the website (basically 2 levels of nesting), but it can be used in any cases. Default to false.

katex_options: dict

null by default. This theme options allows to configure the KateX rendering options. It is useful if you want to define macros or change the rendering behavior.

katex_options:
  displayMode: true
  macros:
    "\\RR": "\\mathbb{R}" 
    "\\dx": "\\mathrm{d}x" 

show_datetime: bool

If true, the last update date of the page (source: last git commit involving the current page) will be displayed at the top right corner of the page (see above). Default to false. The date is displayed in the local timezone of the user.

This options allows to enable the date display for all the pages of the documentation. If you want to disable it for a specific page, you can set show_datetime: false in the front-matter of the page.