How This Wiki Works

e2d5810c9270cad69a2ff020a89583059fc831fe This document explains how this wiki is built, how content is edited and published, and how the architecture is intended to evolve over time.

It also serves as a record of the initial design decisions made when the wiki was created.

Goals

The initial requirements for the wiki were:

• Keep the site technically simple.
• Make editing convenient for a nontechnical or lightly technical editor.
• Store content in a portable format rather than a proprietary database.
• Maintain revision history through Git.
• Make it easy for one editor to manage initially.
• Allow a small number of contributors to be added later.
• Host the site using the existing Cloudflare-managed domain.
• Leave a clean path toward company-wide authentication using Microsoft accounts.

The architecture deliberately separates four concerns:

1. Wiki presentation
2. Content storage and version history
3. Content editing
4. Hosting and user access

Keeping those concerns separate makes it possible to change one layer later without rebuilding the others.

Architecture

The basic publishing system is:

Pages CMS
    |
    | edits Markdown
    v
GitHub repository
    |
    | source change triggers build
    v
Astro / Starlight
    |
    | generates static website
    v
Cloudflare Workers
    |
    v
<<<<<<< HEAD
Published wiki

The major components are described below.

Starlight

Starlight is the documentation framework used to render the wiki.

It runs on Astro and turns Markdown documents stored under:

src/content/docs/

into web pages.

Starlight provides the documentation-oriented user interface, including navigation, page layout, responsive design, and other features commonly expected from a documentation or wiki site.

The wiki is generated as a static website. Pages are converted to HTML during the build process rather than generated from a database every time someone visits them.

This keeps the deployed site simple and minimizes the amount of application infrastructure that needs to be maintained.

Markdown content

The wiki’s actual documents are stored as Markdown files.

For example:

src/
└── content/
    └── docs/
        ├── index.md
        └── wiki/
            ├── example-page.md
            └── how-this-wiki-works.md

A normal page contains frontmatter followed by Markdown content:

---
title: Example Page
description: A short description of the page.
---

Page content begins here.

The frontmatter stores structured information about the document, while the body contains the document itself.

Because the content is stored as ordinary files, it can be edited through the CMS, GitHub, a local text editor, or another compatible tool in the future.

GitHub

GitHub is the authoritative storage location for the wiki’s source code and content.

The repository contains:

• The Markdown documents
• Starlight configuration
• Pages CMS configuration
• Cloudflare deployment configuration
• Static assets such as images
• Package and dependency information

Git provides revision history for the wiki.

Every committed change becomes part of the repository’s history, making it possible to inspect changes, identify when something changed, and recover earlier versions when necessary.

The wiki content is therefore not dependent on Pages CMS. Pages CMS is an editing interface for the files stored in GitHub rather than the permanent storage location for the content.

Pages CMS

Pages CMS provides the browser-based editing interface.

The hosted Pages CMS application is connected to the GitHub repository through GitHub authentication and the Pages CMS GitHub App.

Its behavior is configured by:

.pages.yml

at the root of the repository.

The configuration tells Pages CMS where the wiki documents live and which parts of each document should appear as editable fields.

For an editor, the workflow looks approximately like:

Open Pages CMS
    ↓
Choose a wiki page
    ↓
Edit title, description, or body
    ↓
Save

Behind the scenes, the workflow is:

Open Markdown file
    ↓
Modify file
    ↓
Commit change to GitHub

There is no separate content database.

This means Pages CMS can be replaced later without migrating the wiki’s documents out of a proprietary content store.

Editing workflow

For the initial version of the wiki, there is one primary editor.

The normal editing workflow is:

1. Sign in to Pages CMS.
2. Open the wiki repository.
3. Select an existing page or create a new one.
4. Edit the page in the CMS.
5. Save the page.
6. Pages CMS commits the corresponding Markdown change to GitHub.
7. The published site is rebuilt and deployed automatically.

Direct editing through GitHub or a local development environment remains available when necessary.

Routine content editing should normally happen through Pages CMS, while changes to the wiki software, configuration, or appearance are better handled through the repository and local development environment.

Adding contributors

Editing permission and reading permission are separate concepts.

A person who can read the wiki does not necessarily need permission to change it.

If additional contributors are added, they can receive access to the GitHub repository and Pages CMS without changing how ordinary readers access the wiki.

For the initial small group of editors, direct publishing is sufficient.

If stronger editorial controls become useful later, the Git workflow can be expanded to use branches and pull requests.

A possible future workflow would be:

Contributor edits page
    ↓
Change submitted for review
    ↓
Editor approves change
    ↓
Change merged into main branch
    ↓
Site automatically deploys

This approval process is intentionally not required for the initial implementation.

Navigation

Starlight’s sidebar is configured in:

astro.config.mjs

The wiki section is generated from the documents stored under:

src/content/docs/wiki/

This means new wiki documents can automatically appear in the navigation without requiring every page to be manually added to the site configuration.

Individual documents can later specify additional navigation information, such as ordering or alternate sidebar labels, if required.

Media and attachments

Images and other simple static assets can initially be stored with the site’s source files.

The planned media directory is:

public/uploads/

Files under the public directory become static files in the generated website.

This keeps ordinary wiki content and media together and allows them to be versioned through Git.

If the amount or size of media becomes substantial later, file storage can be moved to dedicated object storage such as Cloudflare R2 without changing the overall content architecture.

Building the site

Astro builds the source repository into a static website.

The generated site is written to:

dist/

The build process conceptually looks like:

Markdown + Starlight configuration
              ↓
          Astro build
              ↓
            dist/
              ↓
    static HTML, CSS, JS, images

The dist directory is generated output rather than the authoritative source of the wiki.

The source files in GitHub remain the permanent copy.

Cloudflare Workers

Cloudflare Workers is used to publish the generated static website.

The deployment configuration is stored in:

wrangler.jsonc

For this static site, Wrangler is configured to publish the contents of:

./dist

No custom server-side Worker application is required for the initial wiki.

The intended publishing workflow is:

Edit page
    ↓
GitHub commit
    ↓
Cloudflare build
    ↓
Astro generates dist/
    ↓
Cloudflare publishes site

Once continuous deployment is configured, normal content changes should not require a manual deployment.

Repository structure

The repository is organized approximately as follows:

genh-wiki/
├── .pages.yml
├── astro.config.mjs
├── package.json
├── package-lock.json
├── wrangler.jsonc
├── public/
│   └── uploads/
└── src/
    └── content/
        └── docs/
            ├── index.md
            └── wiki/
                ├── example-page.md
                └── how-this-wiki-works.md

The most important distinction is:

src/content/docs/

contains the actual wiki documents, while files such as:

astro.config.mjs
.pages.yml
wrangler.jsonc
package.json

configure the systems around those documents.

Authentication

Authentication for reading the published wiki is intentionally separate from authentication for editing it.

Initially, editors authenticate to Pages CMS through GitHub.

In the future, access to the published wiki and other internal tools on the domain is expected to use the organization’s Microsoft accounts.

The planned architecture is:

Microsoft Entra ID
        |
        | establishes employee identity
        v
Cloudflare Access
        |
        | applies access policy
        v
Published wiki and internal tools

Cloudflare Access will act as the access-control layer in front of the applications.

Microsoft Entra ID will remain the corporate identity provider.

The wiki itself therefore does not need to implement its own Microsoft login system.

This allows the underlying Starlight wiki to remain a static site even after corporate authentication is introduced.

Authorization

Future access rules may be more granular than simply “logged in” or “not logged in.”

For example:

All authorized employees
    -> Read wiki

Selected contributors
    -> Edit wiki through Pages CMS

Repository administrators
    -> Manage source and configuration

Specific employee groups
    -> Access particular internal tools

Editing permission should remain distinct from permission to view the published site.

Why authentication is not built into the wiki

The wiki intentionally does not maintain its own user database, password system, or authentication implementation.

Authentication belongs at the infrastructure and identity-provider layers.

This reduces the amount of security-sensitive application code that needs to be maintained and allows access to multiple internal tools to eventually use the same corporate authentication system.

Security

Repository privacy and website privacy are separate.

Restricting access to the GitHub repository protects the source repository, but the deployed website must have its own access controls if the published content should not be publicly accessible.

Before confidential or internal-only information is placed on the deployed wiki, access to the published hostname should be protected appropriately.

Cloudflare Access is the planned mechanism for this.

Administration

Routine responsibilities are divided between several systems.

Content editor

Normally uses:

Pages CMS

Typical tasks:

• Create pages
• Edit pages
• Upload ordinary wiki media
• Publish changes

Repository administrator

Normally uses:

GitHub

Typical tasks:

• Manage repository permissions
• Review source history
• Manage branches or pull requests if needed
• Change application configuration
• Recover previous versions

Infrastructure administrator

Normally uses:

Cloudflare

Typical tasks:

• Manage deployment
• Manage DNS and the wiki hostname
• Configure access policies
• Review build or deployment failures

Developer

Normally works with a local copy of the repository.

Typical workflow:

Edit source/configuration
    ↓
Run local development server
    ↓
Run production build
    ↓
Commit
    ↓
Push to GitHub
    ↓
Automatic deployment

Decisions intentionally deferred

Several capabilities are deliberately not part of the initial implementation:

• Microsoft Entra authentication
• Complex contributor roles
• Mandatory editorial approval
• A content database
• Custom server-side application logic
• Dedicated object storage for media
• A self-hosted CMS
• Application-specific APIs

These can be introduced when actual requirements justify them.

The objective is to avoid adding infrastructure before there is a demonstrated need for it.

Initial technology choices

Function	Technology
Wiki framework	Astro + Starlight
Content format	Markdown
Source control	GitHub
Content editor	Pages CMS
Hosting	Cloudflare Workers
DNS/domain	Cloudflare
Future access control	Cloudflare Access
Future corporate identity	Microsoft Entra ID

Design principle

The central design principle of the wiki is that each layer should remain replaceable.

Pages CMS can be replaced without converting the Markdown documents.

Starlight can be replaced without retrieving content from a proprietary CMS database.

Cloudflare hosting can be changed without rewriting the documents.

Authentication can be introduced without rebuilding the publishing workflow.

The result is a deliberately simple initial implementation that can grow into a larger internal platform without requiring the wiki content itself to be migrated or rewritten.