MKDOCS

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.

INSTALLATION

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

USAGE

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

START SERVER

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/).

MKDOCS SERVER

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

ADDING CONTENT

This is the easiest part, it comes in two basic steps.

1. Create the content and save it in the project folder as an .md file.
2. Edit the yml file appropriately to show it somewhere.

FAVICON

The default favicon will be the mkdocs logo/favicon.  To change this:

1. Create the a subdirectory img in the docsdirectory
2. Place in img directory your new favicon, saved as favicon.ico

EXPORTING & DEPLOYMENT

Run in the project's root directory:

    mkdocs build

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.