Codex Documentation Manager
What is Codex

Codex

Codex is an opinionated, but flexible, static site generator; built specifically for technical documentation.

Its primary goal is minimal configuration, quick deployment, and easy modification. In order to do this, it is very opinionated by default. However, almost all parts of the system can be ejected from defaults and overwritten. This gives the ability to setup quickly with a sane, and recommended, configuration; or reconfigure everything to suit additional needs.

Features
  • Easily edit documentation projects using markdown-like syntax.

  • Store projects as plain text and version them with the parent project.

  • Build static websites from documentation

  • Build typesetted PDF documents from documentation

  • Build LaTeX files from documentation

  • Shipped as a single binary and needs no external tools

Philosophy

Store documentation with the project

Codex uses simple markdown files that can be stored alongside the actual project. This makes it much easier to keep documentation in sync with the project, doesn't require another storage system, and allows it to benefit from the project's version control.

Portable

Codex is meant to build & publish documentation via CI/CD. It is shipped as a single binary that is less than 5Mb in size. This makes it easy to download and use within a pipeline.

Minimal configuration

Codex is meant to be able to setup and modify quickly without worrying to much about configuration and styling. It tries to provide a default configuration that will work for most use cases with as little configuration as possible.

Markdown

Codex uses markdown for article writing. Markdown has several pros and cons:

Benefits of markdown
  • Easy to write without any specialized software

  • Non technical and obvious even in a basic text editor or output

  • Easy to read without any specialized software

Cons of markdown
  • Extremely simple formatting, which is insufficient for technical documentation

  • No separation of formatting and semantic meaning.

Complicating markdown for technical writing

There are some additions to markdown to help mitigate its limited styling like CommonMark and GitHub Flavored Markdown. These are helpful but don't go far enough.

Codex makes a choice, good or bad, to add additional complexity to markdown to help facilitate more technically structured writing. It still maintains backwards compatibility with markdown, but adds an additional Component Architecture based on JSX.

Frequently Asked Questions

Can the color scheme, themes, and other visual styling by modified.

Codex has no theme engine. It has a single default visual style. There are no configurational options for altering the visual style of the built pages.

However, all the templates that are used to build the final site can be overwritten, effectively making the entire site 100% customizable.

Does codex support writing formats other than Markdown, such as OrgMode

Currently, it does not.

Can custom JSX components be used

Yes, additional components can be written using a handlebars syntax for the component template and used in markdown with JSX syntax.

See Custom Components.

What kind of documentation is codex suited for.

Codex can be used for most technical documentation but the use cases that are front most from the perspective of it's development are:

  • API Documentation

  • Object/Class documentation

  • Project overview and usage documentation

Generated by Codex