Writing your docs

Configure Pages and Navigation

The pages configuration in your mkdocs.yml defines which pages are built by MkDocs and how they appear in the documentation navigation. If not provided, the pages configuration will be automatically created by discovering all the Markdown files in the documentation directory.

A simple pages configuration looks like this:

pages:
- 'index.md'
- 'about.md'

With this example we will build two pages at the top level and they will automatically have their titles inferred from the filename. Assuming docs_dir has the default value, docs, the source files for this documentation would be docs/index.md and docs/about.md. To provide a custom name for these pages, they can be added before the filename.

pages:
- Home: 'index.md'
- About: 'about.md'

Multilevel documentation

Subsections can be created by listing related pages together under a section title. For example:

pages:
- Home: 'index.md'
- User Guide:
    - 'Writing your docs': 'user-guide/writing-your-docs.md'
    - 'Styling your docs': 'user-guide/styling-your-docs.md'
- About:
    - 'License': 'about/license.md'
    - 'Release Notes': 'about/release-notes.md'

By convention your project homepage should always be named index. Any of the following extensions may be used for your Markdown source files: markdown, mdown, mkdn, mkd, md.