Skip to content

ADR 0006: Document Publishing — Cloudflare Pages + WeCom Auth

Status

Superseded (hosting + auth portions only; Lexiang, WeCom Doc catalog, i18n, and API notes remain valid)

Date

2026-07-24

Context

OVES document sites are built from GitHub markdown repositories using mkdocs and served on Cloudflare Pages. Access is currently gated by Azure AD via Cloudflare Access.

The organization is exiting Microsoft (Azure AD, OneDrive). A new authentication and discovery mechanism is needed that integrates with WeCom, the primary communication and identity platform.

WeCom-native hosting options (WeCom Docs, Smart Docs, Smart Pages, Lexiang) were evaluated and rejected for full-site HTML rendering. Lexiang Enterprise is used for content digests and AI-powered search, not site hosting.

Decision

Cloudflare Pages remains the document host. Authentication switches from Azure AD to WeCom OAuth via Cloudflare Access. WeCom Doc catalogs serve as link directories for discovery.

Architecture

Source: GitHub markdown repos
  → Build: mkdocs (GitHub Actions)
    → Host: Cloudflare Pages (static HTML)
      → Auth: Cloudflare Access → WeCom OAuth IdP
        → Discovery: WeCom Doc catalog (link directory)
          → Notification: WeCom bot (pending Message API scope)

Platform Roles

Platform Role Status
Cloudflare Pages Static HTML hosting for mkdocs sites Production, unchanged
Cloudflare Access Authentication gate; IdP swap from Azure AD to WeCom OAuth Migration guide written, pending execution
WeCom Doc Link catalog (editable ToC pointing to Cloudflare URLs) Active (edit_doc_content API)
Lexiang Enterprise Content digests + AI Q&A for team knowledge consumption Active (17 article digests, AI 问答 enabled)
WeCom Bot Notifications for new/updated documents Pending Message API scope approval

i18n Strategy

  • English is the canonical language; translations lag by design
  • Cloudflare mkdocs sites: mkdocs-static-i18n plugin → /en/ + /zh/ paths with language switcher
  • WeCom Docs and Lexiang entries: bilingual inline content (Chinese/English)

Rejected Platforms

Platform Reason
WeCom Docs Markdown only; no HTML rendering, no search, no site navigation
Smart Docs / Smart Pages Create-only API (no edit); no HTML rendering, no search, no nav tree
Tencent Docs Not WeCom-native; different authentication domain
Lexiang (as site host) Knowledge base, not a static site renderer; no HTML hosting

WeCom Doc API Constraints (discovered during implementation)

  • edit_doc_content performs a full re-render — all visual styles (fonts, themes, colors) reset to factory defaults
  • Template-based workflows do NOT preserve styles through the API
  • get_doc_content is not available in the current wecom-cli version
  • Docs are private by default; sharing permissions are configured manually
  • Default sharing permission is "Allow Edit"; changeable only at WeCom Admin Console (org level)

Consequences

Benefits

  • Cloudflare Pages: proven, performant, full HTML/CSS/JS support
  • WeCom OAuth: single identity provider; no Azure AD dependency
  • WeCom Doc catalog: discoverable from within WeCom; API-updatable
  • Lexiang AI Q&A: team can ask natural-language questions about published content without reading full documents
  • GitHub → mkdocs → Cloudflare pipeline unchanged (zero disruption to authoring workflow)

Trade-Offs

  • WeCom Docs cannot host rendered HTML — catalogs are link directories only
  • WeCom Message API is currently blocked at the enterprise level; bot notifications are unavailable until scope is approved
  • IdP swap (Azure AD → WeCom OAuth) is a manual configuration task
  • Lexiang digests require a separate push pipeline (BFF → LLM → Lexiang) beyond the mkdocs build

Superseded By

ADR 0009 — EdgeOne Pages + Cloudflare Redirect

ADR 0009 replaces Cloudflare Pages as the static site host and replaces Cloudflare Access with Edge Functions + WeCom OAuth. All other content in this ADR (Lexiang AI Q&A, WeCom Doc catalogs, i18n strategy, WeCom Doc API constraints) remains accurate and active.