Website Sync

🌐 Website sync

Merge on GitHub, and the pages appear on the staging website. The live site is a separate, manual click.

🧪 Runs on every merge into master. When something does not update, see Troubleshooting.

---

🛣️ What happens after a merge

Step	What	Where
1. 🧾	New pages get their ID, section and breadcrumb	fill_front_matter.py
2. 🖼️	New screenshots are filed	image_bot.py
3. ✅	Every page is checked	check.py
4. 🌐	Sections, shared sections and pages are written to Webflow's CMS; items with no page left are archived	sync.py --prune
5. 🚀	bforartists.webflow.io is published	Webflow API, staging only
6. 🧭	The sidebar (nav.json) and the search index (search.json) go to GitHub Pages	sync.py --nav
7. 🎛️	Each site script is published as webflow/<name>-<version>.js, with its hash in the job summary	Site scripts

It runs on every push to the publish branch (master) when the checks pass, and from Actions → Docs 2.0 checks and preview → Run workflow.

---

📚 How pages map to the website

In the repository	On the website
A folder under content/ (content/doc-kit/)	📚 A section in the sidebar (Doc Sections)
The section's index.md	The section overview
A page in the section (installation.md)	📄 A chapter
A folder with index.md (my-chapter/index.md)	📄 A chapter
A page inside that folder (my-chapter/part-one.md)	↳ A sub-chapter, indented under its chapter
A file in snippets/	♻️ A shared section (Doc Snippets)
id: doc-kit.my-chapter	Web address /docs/doc-kit-my-chapter

Order: as in nav.yml; new pages follow in folder order; Position in the sidebar (order:) wins.

---

🛡️ Safety

🔑	Items are matched on their IDs, never on names
⏭️	Unchanged pages are skipped
✋	A page edited by hand in Webflow after the last sync is skipped and reported. Fix it in GitHub, then reset it (how)
🧹	Nothing is deleted; Webflow items with no page in the repository are archived and listed
🌐	Publishes the webflow.io address only. Custom domains (bforartists.co) are never published by the sync
🖼️	Images are sent as GitHub links at the exact commit; Webflow copies them to its own CDN

---

🔑 One-time setup (maintainer)

1. Webflow → Bforartists site → Site settings → Apps & integrations → API access → Generate API token. Name Docs sync; permissions CMS: Read and write, Sites: Read and write.
2. GitHub → Bforartists/Manual → Settings → Secrets and variables → Actions → New repository secret, name WEBFLOW_TOKEN.
3. Site and collection IDs are in docs2/tools/webflow.json (no secrets there).

---

💻 Try it without touching Webflow

python3 docs2/tools/sync.py . --plan plan.json     # writes what would be sent; needs no token