On this page

Your first site#

This page builds a small site from scratch: a home page, two guide pages and a blog post.

Create the project
```
mkdocs new my-docs
cd my-docs
```
Lay out the files
- my-docs/
  - docs/
    index.mdHome page
    guide/
    index.mdSection landing, linked from the sidebar title
    install.md
    blog/
    posts/
    hello.mdAny page under blog/ is a post
  - mkdocs.ymlSite configuration

Configure the site

mkdocs.yml

site_name: My Docs
site_url: https://example.com/
repo_url: https://github.com/me/my-docs

theme:
  name: sumi

plugins:
  - search
  - sumi

Preview and build

mkdocs serve        # live preview
mkdocs build        # writes static files to site/

Top-level sections become tabs in the header. Pages inside the active tab appear in the sidebar. A section whose first page is index.md uses that page as its landing: the section title links to it.

Tip

Without a nav: key, MkDocs builds the navigation from your folders. Blog posts are kept out of the sidebar automatically.

Deploy#

mkdocs build writes plain HTML, CSS and JavaScript to site/. Upload that folder to any static host — GitHub Pages, Cloudflare Pages, Netlify, an S3 bucket or an Nginx server. Nothing needs to run after deployment.

mkdocs gh-deploy      # build and push to the gh-pages branch

Your first site#

How navigation is built#

Deploy#