Working with MkDocs

The MkDocs project that is generated by SQLDocs must be build with MkDocs to get your final documentation website. MkDocs is a static site generator that's geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file.

Setup for Windows

Install MkDocs and its dependencies:

1. Install Python. Go to the Python downloads page and download the latest version for Windows.

2. Launch the installer and follow the on-screen instructions.

3. Run the command prompt as Administrator.

4. Enter the command python --version and pip --version to check the Python installation. In both cases a version number should appear as an output in the command prompt.

5. Enter the command pip install mkdocs mkdocs-material mkdocs-awesome-pages-plugin to install the MkDocs Python package, the Material for MkDocs theme and the MkDocs Awesome Pages Plugin.

6. Final test: Enter the command mkdocs --version. A version nummer in the command prompt will let you know if everything has been installed correctly.

Now you can generate the documentation locally on your computer.

1. Start the command prompt and change to the project directory c:\my-sqldocs-project.

2. Enter the command mkdocs build. The documentation will be generated or regenerated.

3. To display the result, enter the command mkdocs serve and open the URL http://127.0.0.1:8000 in your Web browser.

Configuration can be found in the mkdocs.yml file and the individual chapters are in the docs subdirectory.