Docs Site (docs.arlyn.io)¶

Project: Arlyn Labs Docs (docs.arlyn.io)
Date: April 2026

Overview¶

The Arlyn Labs documentation library at docs.arlyn.io is a static site generated by MkDocs with the Material theme. Like the company website, it is hosted on Cloudflare Pages and deployed automatically on every push to the main branch of its GitHub repository.

The key difference from the company website is the build step: the company website is plain static HTML and requires no build command, whereas the docs site must run MkDocs to compile Markdown source files into a static site before Cloudflare can serve it.

How It Works¶

Source repository¶

All documentation is written in Markdown and lives in the ArlynLabs/arlyn-docs GitHub repository. The repository structure is:

arlyn-docs/
├── docs/                   # Markdown source files (one per doc page)
│   ├── index.md            # Home page
│   ├── hosting/            # Hosting & Deployment section
│   ├── access-control/     # Access Control section
│   └── credentials/        # Credentials & Connections section
├── mkdocs.yml              # Site configuration: nav, theme, plugins
├── requirements.txt        # Python dependencies (MkDocs + Material theme)
└── _worker.js              # Edge worker: redirects .pages.dev → docs.arlyn.io

Build pipeline¶

When a push lands on main, Cloudflare Pages runs the following build command inside a managed build environment:

pip install -r requirements.txt && mkdocs build

This installs MkDocs and the Material theme, then compiles all Markdown files into a complete static site in the site/ output directory. Cloudflare then deploys that directory globally across its CDN.

There is no separate CI step — the entire build happens inside Cloudflare Pages.

Custom domain¶

The site is served at docs.arlyn.io via a CNAME DNS record in the Cloudflare dashboard pointing to arlyn-docs.pages.dev. The DNS setup follows the same pattern as the company website — see Cloudflare Pages & GitHub Setup for detail on how custom domains are connected.

.pages.dev redirect¶

As with the company website, the .pages.dev URL (arlyn-docs.pages.dev) permanently redirects to the canonical domain (docs.arlyn.io) via a _worker.js edge worker in the repo root. This prevents search engines from indexing the .pages.dev URL as a duplicate. The worker pattern is identical to the one documented in Cloudflare Pages & GitHub Setup.

Adding or Updating Documentation¶

Making a change to the docs site is a two-step process: write the content, then register it in the nav.

1. Write the Markdown file¶

Add a .md file to the appropriate subdirectory under docs/. Each section has its own directory (hosting/, access-control/, credentials/). Use the existing pages as a template — every page should open with:

**Project:** [project name]<br>
**Date:** [Month Year]

2. Register it in mkdocs.yml¶

Add the new file to the nav: block in mkdocs.yml:

nav:
  - Section Name:
    - Overview: section/index.md
    - Your New Page: section/your-new-page.md

The nav: block controls the order and grouping of pages in the sidebar. If a file exists in docs/ but is not listed in nav:, MkDocs will still build it but it won't appear in the navigation.

3. Push to publish¶

git add docs/section/your-new-page.md mkdocs.yml
git commit -m "Add doc: page title"
git push

The site updates within about a minute of the push landing on main.

Local Development¶

You can preview the site locally before pushing. This requires Python 3.

# Install dependencies (once)
pip install -r requirements.txt

# Start the local dev server with live reload
mkdocs serve

The server runs at http://127.0.0.1:8000 and automatically rebuilds whenever you save a file. This is the recommended way to check formatting and navigation before committing.

Shared Infrastructure¶

The docs site shares the following infrastructure with the company website (arlyn.io):

Component	Company website	Docs site
Hosting platform	Cloudflare Pages	Cloudflare Pages
Source control	ArlynLabs/arlyn-website	ArlynLabs/arlyn-docs
GitHub integration	Cloudflare GitHub App on ArlynLabs org	Same app installation
Cloudflare account	e3874665bc48a0819bc5be1dfbdf454d	Same account
Custom domain DNS	arlyn.io (CNAME @ → arlyn-website.pages.dev)	docs.arlyn.io (CNAME → arlyn-docs.pages.dev)
.pages.dev redirect	`_worker.js` → arlyn.io	`_worker.js` → docs.arlyn.io
Build command	None (plain static HTML)	`pip install -r requirements.txt && mkdocs build`
Output directory	`/` (repo root)	`site/`
Access control	Public	JumpCloud SSO via Cloudflare Access

The main operational difference is that the docs site is SSO-protected. Visitors to docs.arlyn.io must authenticate via JumpCloud before the page is served. The company website has no such gate. See Access Control for how that is configured.

Key References¶

Item	Value
Live site	docs.arlyn.io
GitHub repository	ArlynLabs/arlyn-docs
Cloudflare Pages URL	arlyn-docs.pages.dev
Cloudflare Account ID	e3874665bc48a0819bc5be1dfbdf454d
MkDocs documentation	mkdocs.org
Material theme docs	squidfunk.github.io/mkdocs-material
Company website hosting guide	Cloudflare Pages & GitHub Setup