# Set up project

> How to create a MkDocs site from scratch

This is a summary of the tutorial on mkdocs.org.

## How to use this guide

Use one of the approaches below:

- Create a quickstart project with the `new` command covered in Create a starter site.
- Follow the extended guide to create a Set up up docs site by hand.

### Basic structure

This is the simplest MkDocs site you can make:

- `docs/`
  - `index.md` - Homepage in the `docs` directory (by default).
- `mkdocs.yml`
  - Config at the root - control appearance and navigation of your site.
  - See this project's docs/mkdocs.yml file on GitHub.

Notes on fields for the config:

- `site_name` - title of your site.
- `site_description` - used as a description for SEO and you could use it somewhere in your template.
- `site_url` - now a required field when running a deploy. Include the subpath on the domain. If your site is not ready to be hosted, set this field to an empty string.
- `repo_url` - for Edit on GitHub button. See docs.
- `edit_uri` - defaults to `edit/master/docs/`, which includes `docs` directory of markdown files inside your repo root. But, if the site's root is in an outer `docs` directory, then you need to also add that, so paths do not break. e.g. `edit/master/docs/docs`. See docs

### Requirements file

A requirements file is optional but it can make it easier to manage dependencies. If you choose not use the file, make sure `pip install mkdocs` and `pip install THEME` lines are your instructions.

If you want to add, then include `requirements.txt` at the root. If your project is already a Python project, you might prefer to add `mkdocs` in `requirements-dev.txt` or at `docs/requirements.txt` to keep it isolated.This file should have `mkdocs` in it and also any themes if needed.

### Create a starter site

Run this command to create a starter site. This make the steps below go quicker.

    cd my-project
    mkdocs new PATH

The result will be same as the Basic structure defined above and will include minimal text content generated by the MkDocs CLI. This text is defined in the project's new.py module.

### Set up a docs site

Tip: Optionally use the `new` command covered above to set up the config and index page first and then continue.

1. Create doc pages.
   1. Create a `docs` directory.
   2. Create `index.md` as your homepage.
   3. Create other markdown pages (optional).
      - Use placeholder content if you want to move on and then come back to expand them.
      - If you have any existing markdown docs, these will work too.
2. Set up config.
   1. Create `mkdocs.yml` at the project root.
   2. Set up a navbar there.
   3. Choose a theme.
3. Create a favicon (optional).
   - It will be picked up at this path: `docs/img/favicon.ico`.
4. Add to your `.gitignore`.
   - Add build directory. This will prevent it from being versioned on `master` branch.
   - Add virtual environment, if using one.

You project should now look this this:

- `docs/`
  - `index.md`
  - More pages...
- `mkdocs.yml`
- `.gitignore`
- `venv`
- `requirements.txt` - optional

## Sample content

### Ignore file

`.gitignore`

    site/

    venv

### Navbar

`mkdocs.yml`

    nav:
        - Home: index.md
        - About: about.md

### Themes

#### Builtin

Use a builtin theme that comes with MkDocs.

The default.

    theme: mkdocs

Using ReadTheDocs theme and alternative config syntax.

    theme:
      name: readthedocs

Find more supported themes. If it doesn't immediately, you'll have to use `pip` to install it and add to a `requirements.txt` file.

#### ReadTheDocs Dropdown theme

See below using mkdocs-rtd-dropdown.

`requirements.txt`:

    mkdocs-rtd-dropdown

`mkdocs.yml`:

    theme:
      name: 'rtd-dropdown'

### Material for MkdDocs theme

See the MkDocs for Material homepage. See the Set up page for config options.

`requirements.txt`:

    mkdocs-material-extensions>=1.0

`mkdocs.yml`:

    theme:
      name: 'material'

GitHub « Previous Next »