MKDocs is a documentation tool for generating static webpages from markdown. The tool is incredibly simple to use and install. Here is what you need to do. This is a tool that is to be installed on your workstation to generate content and push it to a webserver.
First as root, you will need to install python and pip, force the upgrade of pip (repos have a rather old version), and then finally install mkdocs.
yum install python python-pip pip install --upgrade pip pip install mkdocs
Using mkdocs is rather simple, once you comprehend their intended workflow. The idea is you generate the project, start the testing service, populate the project with content, validate, then export the site.
CREATE NEW PROJECT
mkdocs new my-project cd my-project
The server will start a localhost bound webserver that you can tap into at any time to see a real time update of your changes (http://127.0.0.1:8000/).
THE CONFIG FILE
mkdocs.yml is your main configuration file for the project. This will detail what is files are to be included, layout, theme, and favicon.
The rough layout will be as follows:
site_name: Documentation Sample Snippet pages: -Home: index.md -About: about.md -WoW: world-of-warcraft.md -GPL: gpl.md theme: readthedocs
This is the easiest part, it comes in two basic steps.
- Create the content and save it in the project folder as an .md file.
- Edit the yml file appropriately to show it somewhere.
The default favicon will be the mkdocs logo/favicon. To change this:
- Create the a subdirectory img in the docsdirectory
- Place in img directory your new favicon, saved as favicon.ico
EXPORTING & DEPLOYMENT
Run in the project's root directory:
A subdirectory called 'site' will be generated. You can copy over the contents to your webserver as you see fit. This can be in your web root, or in a subdirectory there.