Hosting - your GitHub, your Cloudflare, private by default

A Glassdocs knowledge base is Markdown - docs/*.md plus a mkdocs.yml - built with Zensical and published to your own Cloudflare account. Glassdocs is a control plane: it configures your repo and deploys from your GitHub Actions. It never creates repos, never holds your Cloudflare token, and never stores your content. Your docs never leave your GitHub and your Cloudflare.

What Glassdocs does - and doesn't

Everything runs in your accounts. Glassdocs orchestrates; the content, the build, and the published site all stay on infrastructure you own.

What you need before you start

• A GitHub organization where you're an admin/owner (that's what the Glassdocs admin authorizes against)
• A Cloudflare account (the free tier is fine) - pick the one account you want all your KBs to live in
• Optionally, an email domain or a list of client emails for who may read the published site

The end-to-end flow

You'll do this from the Glassdocs admin dashboard. Each step below maps one-to-one to what the admin UI walks you through.

1. Install the Glassdocs GitHub App on your org

   Glassdocs needs its GitHub App installed to list repos, set up knowledge bases, and manage who can read them. It asks for least-privilege access - read code, and read/write Actions variables and workflows. It never creates or deletes repos, and never stores your content. Pick your org, choose which repos to grant, and approve.

2. Create a repo from the Glassdocs KB template

   A KB is Markdown: docs/*.md plus a mkdocs.yml, built by Zensical (the MkDocs successor from the Material team). Generate a fresh repo from the template at github.com/Glassdocs/kb-template/generate. Glassdocs configures an existing repo and publishes it - it never creates repos on your behalf.

3. Select the org, repo, and Pages project name

   In the Glassdocs admin, pick your organization, choose the repo (only repos the app can access appear here), and set a Cloudflare Pages project name. That name becomes <name>.pages.dev.

   If this KB already has a live Cloudflare Pages site, type that project's exact name. A new name spins up a second, separate site and orphans the real one. After you connect Cloudflare in the next step, the admin lists the account's existing projects and warns you if the name you chose isn't one of them.

4. Connect Cloudflare - one paste, no manual setup

   Click Create token. The link pre-selects exactly the two permission groups the publisher needs (Cloudflare Pages: Edit and Access: Edit) - you don't pick permissions yourself. Create the token, paste it in, and press Connect. Glassdocs verifies it and seals it into the repo as an Actions secret; the token is never stored here.

5. Set read access - staff domain, plus optional clients

   Set a staff domain - your own org's email domain (e.g. yourcompany.com) - to grant your whole team SSO access. This is what makes a KB “staff-only”. Optionally add a client domain (everyone at an external email domain) and/or specific client emails for outside readers.

   Access is fail-closed with no default: an access field left blank grants no one through that channel. Leaving every field blank deploys the site locked to nobody - not “staff-only”. To let your team in, set the staff domain. You can change any of this later per KB from the Access panel, and that's how you recover a locked-out KB.

6. Set up & deploy

   Press Set up & deploy. Your GitHub Actions builds the KB with Zensical and deploys it to your Cloudflare Pages. On that first run, Cloudflare Access is created to gate the site, so unauthenticated visitors are bounced to a login before they can see anything.

7. Verify

   The admin dashboard shows live deploy status, linked to the run on GitHub. Then visit the site in a private window while signed out - you should be redirected to the Cloudflare Access login rather than seeing the docs. That redirect is the proof the gate is live.

Why it's private by default

The deploy workflow doesn't just push files - it enforces the gate. It fails closed if the Access app can't be created, and after deploying it probes the live site: it only reports success when an unauthenticated request is redirected to the Cloudflare Access login. If it can't positively confirm that gate - the site answers publicly, or the check can't verify it - the workflow rolls the deployment back rather than leave it up. The upshot is that "the KB is live" and "the KB is gated" are the same event - you can't accidentally ship an ungated site.

Good to know

pages.dev subdomains are globally unique

A <name>.pages.dev subdomain is unique across all of Cloudflare, not just your account. If the name you chose is already taken by someone else in the world, Cloudflare gives you a suffixed URL instead. The KB still works and is still gated - only the exact hostname differs. The admin dashboard always links you to the real published URL.

Deleting and recreating a project has a cooldown

If you delete a Cloudflare Pages project and then recreate one with the same name, Cloudflare enforces a short name-reuse cooldown before that name is available again. If a recreate seems to stall on the name, that cooldown is usually why - wait a little and retry, or pick a different project name.

Adding another repo later

The repo picker only lists repos the Glassdocs app can access. If you create a new KB repo after installing the app, grant the app that repo on GitHub, then click Reload in the admin - it'll appear in the list.

Summary

Install the GitHub App, create a repo from the KB template, connect Cloudflare with one paste, and set up & deploy. Your GitHub Actions builds the Markdown with Zensical and publishes it to your Cloudflare Pages behind Cloudflare Access. Glassdocs never creates repos, never stores your content, and never holds your token - your docs live entirely in your GitHub and your Cloudflare.