Set up Codex for Hosting Your Documentation
Writing documentation is hard. Fortunately, there are simple tools that make it a little bit easier. Codex is one such tool. Codex is a Laravel application aimed at making hosting good-looking documentation easy. It's very simple to set up and is quickly gaining many useful features.
This guide assumes you've already got a documentation repository with a decent set of docs in it. For example, here are the Nice PHP Framework docs and accompanying website.
Setting up
First of all, we need to create a toc.md file with a few links in it. It should be an unordered list, such as:
- [Introduction](introduction.md)
- [Installation](introduction.md#installation)
- [Usage](introduction.md#usage)
- [Caching](introduction.md#a-word-about-caching)
- [Session Management](introduction.md#enabling-session-management)
- Appendices
- [Twig](introduction.md#use-with-twig)
- [Stack middlewares](introduction.md#use-with-stack-middlewares)
- [Advanced Usage](introduction.md#advanced-usage)
You can see that Codex supports linking to anchors within pages, so you can build a TOC even if you only have a single page of documentation.
Installation
Installation is very straight-forward. Simply clone Codex into the folder of your choosing and install dependencies using composer.
git clone https://github.com/caffeinated/codex docs-website
cd docs-website
composer install -o --no-dev
Installing your documentation
Next, we need to install your documentation, replacing the existing docs. We also need to change the driver configuration setting in app/config/codex.php from flat-file-based to git-based.
<?php
// ...
/*
|--------------------------------------------------------------------------
| Storage Driver
|--------------------------------------------------------------------------
|
| Codex can support a multitude of different storage methods to retrieve
| your documentation from. You may specify which one you're using
| throughout your Codex installation here. By default, Codex is set to
| use the "flat" driver method.
|
| Supported: "flat", "git"
|
*/
'driver' => 'git',
// ...
Now, remove the existing documentation and clone your own documentation in the configured storage directory. By default, this is public/docs.
cd public/docs
rm -rf ./*
git clone https://github.com/tyler-sommer/nice-docs nice
Your documentation is now and running! You can easily customize the theme in app/views to suit your needs.