Privacy Guides: a community-maintained MkDocs site for privacy tool recommendations

What Privacy Guides actually is, and who the repository is for

Privacy Guides describes itself as "a socially motivated website that provides information for protecting your data security and privacy," run by a non-profit collective of volunteers. The repository is the source of that website: Markdown pages under docs/, an MkDocs configuration, a theme directory, and build tooling. That distinction matters more than it sounds. Someone searching for a privacy tool will land on the rendered site; someone cloning this repository is getting a content pipeline, not a security utility.

The audience splits cleanly. First, readers and translators: the README points to Crowdin for translation and to the site's writing style guide for contributors. Second, people who want to host or mirror the content themselves, which the README already does in three places (GitHub Pages, BunnyCDN, and a Tor onion service). Third, contributors who file issues or open pull requests against individual recommendations. If you are none of those, the repository has little to offer you directly, though the site it produces might.

How the site is assembled: MkDocs, Pipenv and a vendored Material theme

The build is a Python static site generator with a Node sidecar. The Dockerfile lays the stages out explicitly. A base stage on python:3.12-slim-bookworm sets LANG and LC_ALL to C.UTF-8 and disables bytecode writing. A python-deps stage installs pipenv, adds gcc, libffi-dev and build-essential, copies modules/mkdocs-material, Pipfile and Pipfile.lock, then runs pipenv install --deploy with PIPENV_VENV_IN_PROJECT=1, which places the virtual environment at /.venv. A nodejs-deps stage on node:24-bookworm-slim installs all-contributors-cli globally and compiles it into a standalone binary with pkg. A runtime stage installs the GTK and Cairo image libraries and Git.

The interesting detail is that mkdocs-material is vendored under modules/ and copied in before dependency resolution, rather than pulled from PyPI. The README's badge row links to the upstream Material for MkDocs project, so the theme is a fork kept in-tree. That is a deliberate trade-off: it lets the site pin theme behaviour and patch it, at the cost of tracking upstream changes by hand. The multiple mkdocs configuration files (mkdocs.yml, mkdocs.blog.yml, mkdocs.insiders.yml) plus crowdin.yml suggest separate build targets for the main site, the blog and translated content. The README does not document which configuration each deployment uses.

Installing the repository and generating the site locally

The repository ships run.sh at the top level, which is the project's own entry point for building or serving the site. The Dockerfile is the reproducible path, and it is the one the maintainers maintain for CI. If you have Docker available, build the image from the repository root:

docker build -t privacyguides .

The build compiles Python dependencies into a virtual environment inside the image and produces the all-contributors binary in a separate stage, so expect the first build to take a while. If you prefer to work without Docker, the Pipfile and Pipfile.lock define the Python dependencies, and pipenv is the tool the Dockerfile uses:

pipenv install --deploy
pipenv run mkdocs serve

The --deploy flag makes pipenv fail rather than silently update the lock file, which is what you want when reproducing the site. mkdocs serve starts the local development server; the default MkDocs port is 8000, though the repository does not state a port anywhere, so confirm it in the output. Note that the Dockerfile copies a local modules/mkdocs-material directory before installing dependencies, and that directory is a git submodule. A plain clone without submodules will not have it.

Where this repository is the wrong tool

The most common misunderstanding is treating Privacy Guides as software you run to become private. It is not. Nothing in the repository filters DNS queries, blocks trackers in a browser, or encrypts a disk. It recommends other projects that do those things. If that is what you need, you want one of the tools the site lists, not this repository.

A second limitation is the contribution model. The README states the project is operated by volunteers and that the site is free of advertisements and not affiliated with the listed providers. That independence is the point, but it also means recommendation changes move at the speed of volunteer review. The README directs contributors to open issues and to a forum tag for approved topics waiting for a pull request, which implies a queue between approval and publication. There is no documented service level, and the README does not describe a rollback procedure for a bad recommendation once merged. If you need a vetted tool list with contractual review guarantees, this is not that.

Self-hosting has its own ceiling. The README's note on alternative networks says most hidden service providers are "not very extensively used or tested," and recommends Tor instead. That is an unusually candid statement for a project to publish about its own mirrors, and it should temper any plan to treat the onion address as a hardened distribution channel.

Alternatives and how their approach differs

The closest alternative is the upstream Material for MkDocs project that this repository vendors. Upstream is a general-purpose theme and documentation framework for any MkDocs site; Privacy Guides is one specific site built on a fork of it. If your goal is to publish your own documentation, start with upstream Material for MkDocs and skip the fork. You get a maintained theme without inheriting a vendored copy that you would have to rebase.

A different kind of alternative is the set of curated link lists that live entirely on a code forge, with no build pipeline at all: a single Markdown file, edited by pull request, rendered by the forge's own viewer. That approach removes the entire Python and Node toolchain, the submodule, and the container build. What it loses is everything the MkDocs setup buys: search, a blog, translation through Crowdin, and a consistent theme. Privacy Guides chose the heavier path because it publishes a full site in many languages, not a README. For a list of twenty links, the heavier path is not worth it.

Maintenance, releases and licence obligations

The repository is not archived, and the last push was on 2026-09-22. Releases are dated and appear roughly monthly: 2026.09.17, 2026.08.12 and 2026.07.22. The version scheme is calendar-based, so a release identifier tells you the date it was cut rather than a semantic major or minor number. There is no documented long-term support branch, and the README does not describe an upgrade path between releases; the practical upgrade is to pull main and rebuild, which is why the lock file and the vendored theme matter.

Licensing is split. The README states the content is licensed under the Creative Commons Attribution-ShareAlike 4.0 International Public License, and the repository carries separate LICENSE and LICENSE-CODE files, which implies the source code used to format and display the content is under a different licence than the prose. If you fork and republish, the share-alike term on the content is the one to read carefully, and the code licence is a separate question. This is not legal advice; read both files before redistributing.

Editorial conclusion

Adopt the Privacy Guides repository if you want to read, translate or contribute to a Markdown-based recommendations site, or if you need a self-hosted mirror of its content under a share-alike licence. Do not adopt it if you are looking for software that filters DNS, blocks trackers or hardens a device; the site recommends such tools but does not perform those functions. Before committing to a fork, verify three things: whether the vendored modules/mkdocs-material submodule resolves, whether pipenv install --deploy succeeds against the pinned Pipfile.lock on your Python version, and whether the Creative Commons Attribution-ShareAlike 4.0 International terms on the content fit how you intend to redistribute it. The repository's own answer to the question of what to run is in run.sh, so start there rather than guessing at an mkdocs invocation.

Frequently asked questions

Official sources

1. License: CC-BY-SA-4.0
2. privacyguides/privacyguides.org on GitHub
3. Project website
4. README
5. Releases