Website publishing (lcdl.forgesdlc.com)

The handbook HTML for Forge LCDL is produced by forge-lcdl-website, not this repository’s standalone generator. Canonical Markdown contracts and narrative docs remain in forge-lcdl; the website repo embeds forge-lcdl as a git submodule and runs forge-autodoc via:

pip install markdown
python3 generator/build-site.py

Firebase project lcdl-542d8 backs Hosting (see forge-lcdl-website/README.md).

  forge-lcdl docs + contracts commit
      |
      v
  bump forge-lcdl submodule in forge-lcdl-website
      |
      v
  python3 generator/build-site.py
      |
      v
  firebase deploy → lcdl.forgesdlc.com

Navigation metadata (why there is no site.yml)

The generated handbook groups pages by nested folders under docs/ and uses per-file YAML frontmatter consumed by Kitchen Sink forge-autodoc. A separate docs/site.yml manifest is optional and was not introduced to avoid duplicating titles and nav order in two places.

Hints-only file: docs/site-meta.json — machine-readable notes for agents; not read by the site generator today.

Updating after doc or contract edits

Preferred order:

1. Commit and push changes in forge-lcdl (this repo).
2. In forge-lcdl-website, move the forge-lcdl submodule to that commit (git submodule update --remote forge-lcdl or checkout the pinned SHA).

If you maintain a sibling checkout (Code/forge-lcdl) and cannot wait on the submodule SHA, mirror content into forge-lcdl-website/forge-lcdl using tar or rsync scoped to subtrees, never deleting the submodule .git/ directory — see workspace rule forge-lcdl-handbook.mdc (forge-lcdl handbook).

Destructive-example mirror (scoped to docs/ + src/):

rsync -a --delete forge-lcdl/docs/ forge-lcdl-website/forge-lcdl/docs/
rsync -a --delete forge-lcdl/src/ forge-lcdl-website/forge-lcdl/src/
cp forge-lcdl/README.md forge-lcdl-website/forge-lcdl/README.md

1. From forge-lcdl-website, python3 generator/build-site.py emits HTML under website/.
2. Deploy from the workspace root:

./deploy-websites.sh --only forge-lcdl-website

Manual equivalent:

cd forge-lcdl-website && firebase deploy --only hosting --project lcdl-542d8

FIREBASE_TOKEN enables non-interactive deploys (firebase login:ci). CI pushes to forge-lcdl-website main with the FIREBASE_TOKEN repo secret deploy automatically.

Handbook information architecture

Narrative docs live under nested folders (docs/start/, docs/tutorials/, docs/guides/, docs/reference/, etc.). The site builder (forge-autodoc run_simple_build) groups the sidebar by directory and omits src/forge_lcdl/contracts/** from the primary rail (contracts remain published as HTML and are linked from the task catalog).

Optional: python3 generator/build-site.py --link-check reports unresolved internal .md links (stderr).

Docs QA (this repo)

cd forge-lcdl
python3 scripts/audit_docs_site.py
# optional: python3 scripts/audit_docs_site.py --strict

Helper scripts after large doc moves: scripts/fix_docs_internal_links.py, scripts/resolve_doc_basenames.py.

ContractSpec maintenance gate

cd forge-lcdl
python3 scripts/generate_contract_sidecars.py
python3 scripts/audit_contract_docs.py --strict

Canonical URL

https://lcdl.forgesdlc.com

Crawl hints (robots.txt / sitemap.xml)

Every generator/build-site.py run writes website/robots.txt and website/sitemap.xml at the handbook root so crawlers discover emitted HTML. Paths resolve against the production origin above.

Canonical meta / Open Graph / JSON-LD URLs come from seo_public_origin in forge-lcdl-website/generator/build-site.py — keep that aligned with Hosting.

There is no bundled client-side search index in-tree today; readers rely on navigation hubs plus Documentation sitemap.

UX go-live checklist

After navigation or handbook IA changes, follow UX go-live checklist before tagging a release or deploying Hosting.