codex.docs: a self-hosted docs app built on the Editor.js ecosystem

Editor.js blocks are the unit of content, not a Markdown file

The architecture of CodeX Docs starts with its dependency on the Editor.js ecosystem, which the README describes as giving all modern opportunities for working with content. That choice has consequences. A block editor stores a document as structured JSON rather than as text in a file, so every piece of content in the app is an Editor.js block with its own type and data. The plugin set is visible in package.json, where the editor-upgrade script names the packages the project treats as first class: header, code, delimiter, list, link, image, table, inline-code, marker, warning, checklist and raw. If a block type you need is not in that list, adding it is a dependency change and an editor-upgrade run, not a configuration toggle. The alternative approach, a static site built from Markdown files in a git repository, gives you a diffable text format and no runtime editor. CodeX Docs trades that away for in-browser editing and hierarchical structure, which is the right trade for a documentation site with several non-engineer contributors, and the wrong one for a repository where every change is expected to go through a pull request.

Static rendering sits next to a running backend

The feature list advertises static rendering, and the package scripts show how it is produced. The build-static script runs the backend entry point with the ts-node ESM loader and passes a build-static subcommand with two configuration files. The main start script is a concurrently invocation that runs the backend and a frontend webpack build in production mode, while the dev script swaps in build-frontend:dev, which runs webpack in development mode with watch enabled. The build-backend script compiles TypeScript with tsc and then copies twig templates into the compiled views directory and svg assets into the output. So the shape is a server-rendered application that can also emit a static build, with webpack producing the client bundle and twig handling the views on the server. The static build is what makes the project cheap to host, and it is also the part to test carefully, because a static export of an application whose content normally lives in a database has to have captured that content at build time.

docs-config.yaml is the single knob, and the CLI accepts several files

Configuration is a yaml file named docs-config.yaml, and the README points to a Configuration guide for the available options rather than listing them, which tells you the option surface is large enough to need its own page. The interesting detail is in the command line, where both the static build and the development server pass the same two files: docs-config.yaml and docs-config.local.yaml. Every script that starts the application therefore loads a base file and a local override, which is a sensible arrangement for keeping machine-specific values, such as credentials or host settings, out of the committed file. The development server is started with cross-env NODE_ENV=development and npx nodemon reading nodemon.json, so nodemon restarts the process whenever watched files change. One constraint to check before you design your config: the project does not document the schema in the repository itself, so the Configuration page in the hosted docs is the reference you will be coding against.

Three ways to run it: yarn, docker-compose and a Helm chart

The getting started path is short. You clone the repository, fill the config, and run the app:

git clone https://github.com/codex-team/codex.docs

yarn && yarn start

For a containerised run there is a compose file in the repository root:

docker-compose build
docker-compose up

The compose definition itself is short enough to read in full, and it is where the deployment assumptions show up:

version: "3.2"
services:
  docs:
    image: ghcr.io/codex-team/codex.docs:v2.0.0-rc.8
    ports:
      - "3000:3000"
    volumes:
      - ./uploads:/usr/src/app/uploads
      - ./db:/usr/src/app/db
      - ./docs-config.local.yaml:/usr/src/app/docs-config.yaml

The image is pinned to an old release candidate, v2.0.0-rc.8, while package.json in the same repository declares version 2.3.3, so the compose file is out of step with the source tree. The compose file also mounts a db directory, which sits oddly against the README line about deploying easily with no DB and other deps required. For Kubernetes there is a separate ready-to-use Helm chart at codex-team/codex.docs.chart. A developer running this locally needs Node and Yarn, a deployment needs a container or a chart, and the two paths can drift apart exactly as the version tag shows.

Hawk, Misprints and Metrica are wired in by default

Three integrations are listed as built in rather than left to the user. Hawk is described as hunting, with error tracking integrated, and the dependency list backs that up with both @hawk.so/javascript and @hawk.so/nodejs packages, so errors from the browser and from the server are collected by the same service. Misprints is a companion project that reports to Telegram or Slack, which turns a typo into a message rather than a silently wrong page. Yandex Metrica is listed as integrated, and the project documentation carries a guide on enabling analytics. These are the parts of the product that a self-hosted docs instance would otherwise have to wire up by hand, and they are also the parts that need a decision at install time, because each one sends data to a third-party service. If your organisation has a policy against external telemetry, you need to know these three exist in the default configuration before you deploy, and the guides are the place to find out how to turn them off.

Uploads, S3 and the authentication surface

The dependency list shows that the backend handles more than text blocks. There is a client for Amazon S3 at @aws-sdk/client-s3, with @types/multer-s3 alongside it, which together describe a file upload path where a multipart middleware hands files to object storage. The express stack is present with cookie-parser and csurf for cookie handling and cross-site request forgery protection. The project documentation also has a dedicated Authentication guide, and the feature list mentions collapsing sections and hiding the sidebar as things you can tune in the interface. What the repository does not document is what the authentication model actually is, whether it is pluggable, or how it interacts with the static build, and that is a genuine gap. If you plan to run this behind a corporate identity provider, you have to read the hosted Authentication page and the Configuration page rather than infer the design from the dependencies. The same applies to uploads: S3 support exists in the dependency tree, but no configuration key for it appears in the files here.

Apache-2.0, and a release history with a long gap

The repository is licensed under Apache-2.0, which is the licence declared in package.json and the LICENSE file at the root, and it carries the standard obligations of that licence including the notice requirements, so redistribution in a modified form is permitted with attribution. The package name is codex.docs and the project also publishes a command line entry point named codex.docs that points at dist/backend/app.js, which means the built server can be invoked as a binary rather than only through a script. On maintenance, the repository is not archived and the last push was on 2026-08-25. The release list is a different story: v2.2.5 on 2026-04-15, v2.2.4 on 2026-04-04, then v2.2.3 dated 2024-05-03, a gap of close to two years between the last two of those, and the package version in the tree has moved on to 2.3.3 without a matching tag in the list. Treat the version numbering as unstable and read the CHANGELOG-equivalent history in the repository before each upgrade.

Editorial conclusion

Adopt codex.docs if you want a documentation site your team can edit in the browser through Editor.js blocks, you can live with Editor.js plugins as the unit of content, and you are prepared to own the deployment. Do not adopt it if you need revision history, a database-backed search index, or a publishing workflow that goes through review, since the project advertises no database requirement and does not document those features. Before you commit, read docs-config.yaml in your own fork, check that the Editor.js plugin list in package.json covers the block types you need, and verify the container image tag in docker-compose.yml matches the version you intend to run, since the file still pins v2.0.0-rc.8 while package.json declares 2.3.3.

Frequently asked questions

Official sources

1. codex-team/codex.docs on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases