Docs — Publishing Guide

A read-only documentation site for sharing Meridia product specs and strategy docs with partners and collaborators. Docs are authored in Obsidian, filtered and transformed at build time, and published deliberately.

• Site: Cloudflare Pages (TBD URL)
• Access: Cloudflare Access — email-based one-time PIN, no account required
• Codebase: ~/Code/meridia/docs

How to Publish a Doc

Add publish: true to the frontmatter of any doc you want live:

---
type: feature
status: scoping
priority:
  - p0
publish: true
---

Docs without publish: true are excluded. They never touch the docs site.

Publishing Workflow

# 1. Edit docs in Obsidian, add publish: true to what you want live
# 2. From the docs project:
cd ~/Code/meridia/docs
npm run preprocess        # reads vault, transforms, generates pages
npm run dev               # preview at localhost:3000

# 3. When it looks good:
git add .
git commit -m "publish: accommodations update"
git push                  # Cloudflare auto-deploys

What Gets Transformed

The preprocess script handles Obsidian-specific syntax so your partner sees clean docs:

Sidebar Navigation

The left sidebar is auto-generated from your vault folder structure. The mapping is controlled by _publish.config.json:

Excluded folders (never published): Archived/, Docs/, Fly Tyers/

Frontmatter Card

Feature docs with structured frontmatter (status, phase, priority, owner, complexity, estimate) render a metadata card at the top of the page. Fields that are missing are simply hidden.

Locked Links

Wikilinks pointing to unpublished docs show as a greyed-out lock icon with the tooltip "This document hasn't been published yet." This lets your partner see the shape of connected docs without exposing unpublished content.

Configuration

All publish settings live in _publish.config.json in this folder. You can change:

• folder_labels — sidebar section names
• root_label — label for root-level files (currently "Overview")
• strip_frontmatter_keys — frontmatter fields hidden from the published metadata card
• exclude_folders — folders that are never published regardless of flags
• exclude_files — specific files to always exclude
• locked_link_label / locked_link_tooltip — how unpublished links appear

Access Control

Managed via Cloudflare Access (free tier, up to 50 users):

1. Cloudflare dashboard > Zero Trust > Access > Applications
2. Add/remove email addresses as needed
3. Visitors enter their email, get a one-time PIN — no account required

Tips

• The first # heading in your doc becomes the page title — make sure it's there
• The right sidebar TOC is generated from h1/h2/h3 headings — collapsible sections
• Search is built in (Cmd+K) and indexes all published docs automatically
• The site is a static export — all content is baked in at build time, no server