Welcome¶

You have successfully started mkdocs.

Tutorial 1.1 Creating a new file in the root directory¶

Create a new file called example.md in the root docs folder either through your code editor or console:

$ cd docs
$ echo 'testing' > example.md

Update the root mkdocs.yml's Nav to the following:

nav:
  - Intro: 'index.md'
  - Example: 'example.md'

The mkdocs.yml always looks for the closest sibling docs folder by default.

After saving you should see the new article > here <. Once you have visited return to this page.

Tutorial 1.2 Linking Mkdocs.yml files¶

I have already created the sub folders and initialised mkdocs within them (by using mkdocs new .). We just have to link them to the root mkdocs.yml

Simply add the following to your mkdocs.yml navigation (Nav:)

nav:
  - Intro: 'index.md'
  - Example: 'example.md'
  - SubPages: '*include ./example-subpage/*/mkdocs.yml'

So now you have linked subfolders - useful for monorepos.

Tutorial 1.3 Linking an entirely separate repository¶

Let's do an example where you want to have another repository added to your centralised documentation. Simply modify the root mkdocs.yml of this repo to read as follows:

In the root repository run:

$ meta git update

nav:
  - Intro: 'index.md'
  - Example: 'example.md'
  - SubPages: '*include ./example-subpage/*/mkdocs.yml'
  - External Repository: '*include ./second-repo/mkdocs.yml'

Note

In a real-world application you would have the external repository outside of the root directory and not as a sub folder as shown in this example.

That concludes the basic tutorial¶

So you can now document various parts of your application, collaborate with other repositories that utilise Mkdocs. Cartman says it best:

We Need To Work Together Eric Cartman GIFfrom We Need To Work Together GIFs

Wait, is that it?¶

NO! If you want to see other amazing features click the following: