In this article, I am going to quickly walk you through how to generate your own online project documentation.
Creating a project
First of all, we need to install the MkDocs Python library.
pip install mkdocs
Once installed the library, we can then create a folder for our project and open a command prompt from that location. Running the following command, will then automatically create for us a Mkdocs project.
mkdocs new my-project-name
The project will then have a structure like the following:
The mkdocs.yml file will be used in order to design the structure of our website, while all the Markdown files in the docs folder will be used to create the content of each of the different pages of the website. If you are not familiar with how to create text files using Markdown, you can find an introduction guide here.
A simple mkdocs.yml file automatically generated by creating a Mkdocs project will look something like this:
- Home: index.md
We can then modify it to choose our desired website name (instead of MkLorum) and add multiple pages on the website navigation bar by simply adding new pages under the nav tag (specifying on the left the nav button name and on the right the file name in the docs folder). Finally, it is also possible to stylise our website either making use of a pre-installed theme (eg. readthedocs) or choosing a theme from the ones available in the Mkdocs community.
An example, of a more personalised mkdocs.yml file, is available below.
- Home: index.md
- About: about.md
- Contacts: contacts.md
In the docs folder, we can instead find an automatically created index.md file, which we can then personalise for our own website. We can then add as many pages as we want to the website by simply adding new Markdown files in the docs folder and then reference them in the mkdocs.yml file.
At each point in the development stage, we can then always observe how our website looks like by running the following command in the command line from our project location:
This will activate a local server and we would then be able to see our website at this address: http://127.0.0.1:8000 . As soon as our local server is running, in case we modify any file (and save the changes), they will be automatically displayed on the website.
Once added all the content to the website and checked that it is displayed correctly, we can then build the HTML and CSS files by running the following command:
At this point, we are now ready to initialise our project with a GitHub repository. After that, we can then just run from the command our last command and our project will be then deployed online:
On the command prompt, will then be displayed the link at which our website will then be live. Alternatively, we can find this same link by going to our repository settings and looking for the GitHub pages options (running the command shown above, will in fact automatically generate a new branch called gh-pages, which will then be used to by GitHub to host our documentation website).