Creating Your MkDocs Project Structure
The basic structure of an MkDocs project consists of three main components: your project code, all your Markdown documentation pages inside a
docs/ folder, and a configuration file named
Soon, you’ll edit
index.md and expand your written documentation by adding new Markdown files to the
docs/ directory. But first you’ll explore the
mkdocs.yml settings file, which tells MkDocs how to handle your project documentation.
MkDocs uses a YAML file for configuration. When you create a new project using
new, MkDocs creates a bare-bones YAML file for you. The default settings file only contains one element,
site_name, which defines the default name
My Docs for your documentation. Now, of course you don’t want your project to keep that name, so you’ll change it to
Calculation Docs instead.
01:53 As a connoisseur of Google’s Material Design, you’ll also want your documentation to look great right away. By adding a second element to your YAML settings file, you can replace the default theme with a popular Material for MkDocs theme, which you installed at the beginning of this course.
02:23 As soon as the terminal tells you that it’s serving the documentation, as seen-on screen, you can view it in your browser. As you can see, MkDocs says that it’s serving the documentation at the address seen on-screen.
Open a new browser tab and enter that URL. You’ll see the MKDocs boilerplate index page with your custom title, styled with a Material for MkDocs theme. If you want to know where all the text you see is stored, you can open up
02:55 You can edit this page and see the changes automatically reflected in your browser. While you keep working on your documentation, you can keep going back to the address seen earlier in your browser to view those changes. If you don’t see an update, then stop the server by pressing Control and C with the terminal window in focus and rebuild the site using the mkdocs serve command.
You’ve made two adaptations in the
mkdocs.yml file to change the look and feel of your documentation. However, the content of your docs is still just pre-built boilerplate text that isn’t related to your Python project.
Become a Member to join the conversation.