mkdocs-quickstart/docs/tutorial/setup_project.md

Setup 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 Setup 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.

Optionally add requirements.txt at the root or in docs. This can have mkdocs in it and also any themes if needed. Otherwise just make sure those are handled with a pip install mkdocs and pip install THEME lines in your instructions.

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.

Setup a docs site

Tip: Optionally use the new command covered above to setup 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. Setup config.

   1. Create mkdocs.yml at project root.
   2. Setup navbar there. e.g.

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

   3. Choose a theme.
      • An example of choosing a theme which is builtin:

        theme: 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.

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.
   • e.g.

     site/
     
     venv
     

You project should now look this this:

• docs/
  • index.md
  • Other pages...
• mkdocs.yml
• .gitignore
• venv