MkDocs is a great documentation framework, and Drupal is a great backend CMS. While you can use Drupal's hook_help()
, if you have a lot of application-specific documentation, you may want to use a dedicated documentation tool. But how to integrate the documentation into the CMS?
I wanted a solution which would:
- Use the same Git repository for docs (e.g., for MkDocs) as for Drupal. Being on the same repository ensures that we can write docs for MkDocs as we also write code for Drupal.
- Commit only the docs source to Git, not the compiled docs from MkDocs
- This means the docs would need to be compiled and then deployed to the production server.
- Protect the compiled docs behind user access. Ideally, could use Drupal user system to only allow access to specific users.
We tried a few approaches, but each violated the above rules. Then someone suggested using Drupal's private file system ("private://") to control access. This actually worked! Here is the overview of how we se