|
|
@@ -61,37 +61,18 @@ Features and user-visible behavior changes **must** include matching documentati
|
|
|
1. Open your code PR here in `bambuddy`
|
|
|
2. Open companion PR(s) in `bambuddy-wiki` and/or `bambuddy-website`
|
|
|
3. **Link the companion PR(s) in the code PR description** (the PR template has a dedicated section)
|
|
|
-4. Review the Cloudflare Pages **preview URLs** (posted as comments on the docs PRs) before merging
|
|
|
-5. Merge the PRs together — usually code first, then docs, unless the docs reference new things that don't exist yet
|
|
|
+4. Merge the PRs together — usually code first, then docs, unless the docs reference new things that don't exist yet
|
|
|
|
|
|
If your change truly doesn't need docs (internal refactor, silent bug fix), say so in the PR description and give a one-line reason.
|
|
|
|
|
|
### Previews before you merge
|
|
|
|
|
|
-Both docs repos are connected to [Cloudflare Pages](https://pages.cloudflare.com/). Every PR triggers an automatic build and deploys the result to a throwaway preview URL, so you can see your changes rendered on the real site before merging.
|
|
|
+Clone the docs repo and run it locally to see your changes rendered with the real theme before opening the PR:
|
|
|
|
|
|
-**What you'll see on a docs PR**:
|
|
|
+- **Wiki** (`bambuddy-wiki`) — `pip install -r requirements.txt && mkdocs serve` — live-reload on `http://localhost:8000`
|
|
|
+- **Website** (`bambuddy-website`) — static HTML/CSS, open the changed file directly or serve with `python -m http.server`
|
|
|
|
|
|
-1. Within ~30 seconds of pushing, a GitHub check appears:
|
|
|
- `Cloudflare Pages — Deploying...` (yellow dot).
|
|
|
-2. After the build completes (~1 minute for the wiki, ~10 seconds for the website), the check turns green and `cloudflare-pages[bot]` posts a comment with a preview URL like:
|
|
|
- > Deploying bambuddy-wiki with Cloudflare Pages
|
|
|
- > Preview: https://<branch-name>.bambuddy-wiki.pages.dev/
|
|
|
-3. Click the URL — you'll see the full rendered site with your changes, on the real theme, with working navigation, images, and links.
|
|
|
-4. Review the preview like you would the production site. Catch broken links, layout regressions, typos, missing images.
|
|
|
-5. If the preview looks right, merge the PR. If not, push more commits to the same branch — the preview auto-rebuilds on each push.
|
|
|
-
|
|
|
-**If the build fails**:
|
|
|
-
|
|
|
-- The check turns red and no preview URL is posted.
|
|
|
-- Click the check's "Details" link to see the build log.
|
|
|
-- Common causes: MkDocs YAML syntax error, broken image path, unclosed HTML tag. Fix in another commit, the build retries automatically.
|
|
|
-
|
|
|
-**Preview URL quirks to know**:
|
|
|
-
|
|
|
-- Previews are **publicly accessible** — fine for open-source docs, but don't paste drafts you wouldn't want strangers to see.
|
|
|
-- Preview URLs persist for a while after the PR is merged or closed, but Cloudflare eventually cleans them up.
|
|
|
-- Previews build from the **PR branch**, not from `main` — so you're always looking at exactly what will be merged.
|
|
|
+Review like you would the production site. Catch broken links, layout regressions, typos, missing images. If it looks right, open the PR.
|
|
|
|
|
|
### Editing docs without a local clone
|
|
|
|
|
|
@@ -99,7 +80,6 @@ Both docs repos can be edited directly in the browser, no `git clone` required:
|
|
|
|
|
|
- **GitHub web editor** — click the pencil icon on any file in the repo
|
|
|
- **github.dev** — press `.` (period) on any repo page to open VS Code in your browser, with multi-file editing and syntax highlighting
|
|
|
-- **Cloudflare Pages previews** — every PR gets a live preview URL auto-posted to the PR as a comment; click it to see your changes rendered on the real site
|
|
|
|
|
|
## Getting Started
|
|
|
|
maziggy