CoMapeo Docs

Documentation site and content pipeline for CoMapeo, built with Docusaurus v3 and synced from Notion.

What This Repo Includes

• Docusaurus site code (src/, config, scripts)
• Notion sync and translation tooling (scripts/)

Branch Model

This repository uses two branches:

• main: source code, scripts, workflows, and configuration
  • Includes content-lock.sha: pins approved content SHA for production
• content: generated docs and assets (docs/, i18n/, static/images/)
  • Staging workspace for content review (not directly deployed to production)

Do not manually edit generated content in docs/ or static/; these are synced from Notion.

Production Deployment & Content Approval

Production content deploys use a locked content SHA (stored in content-lock.sha on main) to ensure only reviewed and approved content goes live. Promoting content requires a PR to main — that PR is the approval gate. See context/workflows/PRODUCTION_DEPLOYMENT.md for details.

Content itself (docs/, i18n/, static/images/notion/) is generated by digidem/comapeo-content-pipeline — see that repo's DEPLOYMENT.md for the end-to-end process of getting a Notion edit onto the content branch here.

Quick Start

Prerequisites

• Node.js >=18
• Bun
• Git

1. Clone and install

git clone https://github.com/digidem/comapeo-docs.git
cd comapeo-docs
bun i

2. Pull generated content (recommended)

git fetch origin content
git checkout origin/content -- docs/ i18n/ static/images/

3. Start the local docs site

bun run dev

The dev server runs with live reload for docs and UI changes.

Usage

Preview localized sites

bun run dev:es
bun run dev:pt

Build and serve production output

bun run build
bun run serve

Regenerate docs from Notion

Requires .env values (see Configuration):

bun run notion:fetch

Run translation workflow

bun run notion:translate

Configuration

Copy and edit env vars:

cp .env.example .env

Common required variables:

• NOTION_API_KEY
• DATA_SOURCE_ID (preferred) or DATABASE_ID (fallback)
• OPENAI_API_KEY (for translation workflows)
• DEFAULT_DOCS_PAGE

See .env.example for the complete list and notes.

Development

Targeted checks

# Lint one file
bunx eslint path/to/file.{ts,tsx,js} --fix

# Format one file
bunx prettier --write path/to/file.{ts,tsx,js,md,mdx}

# Run focused tests
bunx vitest run path/to/file.test.ts

Common project commands

bun run test
bun run test:scripts
bun run typecheck --noEmit

Related Docs

• Contribution guide: CONTRIBUTING.md
• Security policy: SECURITY.md
• Repository guidelines: context/repository-guidelines.md
• Production deployment workflow: context/workflows/PRODUCTION_DEPLOYMENT.md
• Content lifecycle: context/workflows/content-lifecycle.md
• Notion architecture: NOTION_FETCH_ARCHITECTURE.md

License

This repository currently does not declare an open-source license (LICENSE file is not present).