Quick Configuration¶

A minimal working mkdocs.yml and how to grow it step by step.

Minimal setup¶

site_name: My Project
site_url: https://example.com

theme:
  name: null
  custom_dir: themes/dap

Recommended setup¶

site_name: My Project
site_url: https://example.com
site_description: Short description of your project
site_author: Your Name
repo_url: https://github.com/user/repo
repo_name: user/repo
copyright: "© 2024 Your Name"

theme:
  name: null
  custom_dir: themes/dap

extra:
  language: en
  color_scheme: dark
  accent_color: green

  sidebar:
    image: assets/img/avatar.png
    name: My Project
    tagline: Great docs
    links:
      - platform: github
        url: https://github.com/user/repo

  social:
    - platform: github
      url: https://github.com/user

plugins:
  - search

markdown_extensions:
  - pymdownx.highlight:
      anchor_linenums: true
      use_pygments: true
  - pymdownx.superfences
  - admonition
  - pymdownx.details
  - tables
  - toc:
      permalink: true

Adding content¶

Create Markdown files in your docs/ folder and reference them in nav:

nav:
  - Home: index.md
  - Guide:
    - Overview: guide/index.md
    - Advanced: guide/advanced.md

The nav key drives the sidebar navigation. For the top navigation bar, use extra.navmenu — see Navigation.

What to configure next¶