Maintainer Guide

🧰 Maintainer guide

Every job a maintainer does, one page each, with the steps in order. Start here when something needs changing.

---

🗺️ The whole system on one picture

flowchart LR
  subgraph W["✍️ Write"]
    PC["🖋️ Pages CMS<br/>(browser)"]
    GH["🐙 GitHub editor<br/>or your own editor"]
  end
  subgraph R["🐙 Repository · master"]
    C["📘 content/ pages"]
    N["🧭 nav.yml · home.md"]
    WS["🗺️ workspaces.yml"]
    I["🖼️ images/"]
    J["🎛️ webflow/*.js scripts"]
  end
  subgraph A["🤖 GitHub Actions"]
    B["🖼️ image bot · ✅ checks · 👀 preview"]
    S["🌐 sync.py"]
    P["📦 GitHub Pages<br/>nav.json · search.json · scripts"]
  end
  subgraph F["🌐 Webflow"]
    ST["bforartists.webflow.io<br/>(staging)"]
    LV["bforartists.co<br/>(live)"]
  end
  PC --> C
  GH --> C
  C --> B
  N --> B
  WS --> B
  I --> B
  B -->|"merge into master"| S
  S --> ST
  S --> P
  J --> P
  P -->|"read by the page scripts"| ST
  ST -->|"👤 maintainer's click"| LV

Loading

Three rules hold everything together

	Rule
🐙	GitHub is the truth. Never edit a docs page in the Webflow Designer or CMS; the next sync would skip it (Troubleshooting).
🌿	Every change goes through a pull request into master. The checks and the preview run on it; merging publishes staging.
🚦	Live is a separate click. Nothing the robots do ever publishes bforartists.co.

---

🙋 "I want to…"

I want to…	Who	Page
✏️ Fix a typo, rewrite a section, add a screenshot	Anyone	Editing the docs online
📄 Add, move, rename or remove a page	Maintainer	Structure and navigation
🏠 Change the Docs home (popular links, teaser, workspace)	Maintainer	Structure and navigation
✅ Mark pages as in review or reviewed	Reviewer	Structure and navigation
🗺️ Change a workspace map, re-shoot the workspaces	Maintainer	Workspace maps
🎛️ Change how the docs look or behave on the website	Maintainer	Site scripts
🚀 Update the manual for a new Bforartists release	Maintainers	Release update
🌐 Publish the docs on the live site	Lead maintainer	Release update
🩺 Something looks wrong on the website	Maintainer	Troubleshooting

---

👥 Who does what

Role	Can	Usually does
✍️ Writer	Edit pages in Pages CMS or GitHub, open pull requests	Fixes and new text, screenshots
👀 Reviewer	Approve pull requests, change page status	Checks text against Bforartists, marks pages reviewed
🧰 Maintainer	Merge into master, edit tools, scripts and structure	Structure, scripts, workspace maps, releases
🚦 Lead maintainer	Publish the live site, hold the Webflow and GitHub secrets	Go-live clicks, tokens, access

---

🗓️ Rhythm

When	What	Page
🔁 Every merge	Staging updates by itself; glance at the Actions summary	Website sync
📅 Weekly	Merge open writer pull requests; check the review progress card on the Docs home	Branches and review
🚀 Each Bforartists release	Version, screenshots, workspace maps, Blender mentions, publish live	Release update

✏️ Edit this page

The Edit this page button at the foot of every page opens GitHub's editor on the current docs branch (master, set as BRANCH in docs-layer.js). GitHub makes your own branch and a pull request for you, so every edit starts from the latest docs and goes through the checks. Pages CMS still works for longer sessions: pick the docs branch there.