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.

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