Skip to content

docs(fumadocs): document Notra blog refresh, cache-off build, and deploy hook #115

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
tembo wants to merge 1 commit into from
Closed

docs(fumadocs): document Notra blog refresh, cache-off build, and deploy hook #115

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 30 additions & 3 deletions apps/fumadocs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,33 @@ API key on the server, and means there are no Notra calls from the browser.
Without the key the fetch is skipped and the last committed snapshot is kept,
so the build never fails.

New posts appear on the next deploy. The `Refresh blog posts from Notra` GitHub
workflow triggers a weekly Vercel rebuild; you can also point a Notra publish
webhook at the same Vercel deploy hook for instant updates.
### How new posts go live

Publishing a post in Notra does **not** update the site on its own — the snapshot
is regenerated only when the blog is rebuilt. A new post appears once a deploy
re-runs `fetch-notra-posts.ts` and ships a fresh `notra-posts.generated.ts`.

Build caching is intentionally disabled for this app in `apps/fumadocs/turbo.json`
(`"cache": false`). Without it, rebuilding the same commit can hit the turbo/Vercel
build cache and skip the Notra fetch, so a newly published post never appears
(only a forced no-cache build would pick it up). With caching off, every deploy
re-runs the fetch.

### Refresh workflow and deploy hook

The `Refresh blog posts from Notra` GitHub workflow
(`.github/workflows/blog-schedule.yml`) triggers a Vercel rebuild — which re-fetches
the latest published posts plus the sitemap, RSS, and JSON feed. It runs on three
triggers:

- **`repository_dispatch`** with event type `notra-published` — point a Notra
"post published" webhook at GitHub's `repository_dispatch` API for near-instant
updates.
- **`schedule`** — a daily rebuild (`30 13 * * *`) as a safety net in case a
webhook is missed.
- **`workflow_dispatch`** — manual rebuild from the Actions tab.

The workflow POSTs to a Vercel **Deploy Hook**. To enable it, create the hook
(Vercel project → **Settings → Git → Deploy Hooks**, branch `main`) and store its
URL as the `VERCEL_DEPLOY_HOOK_URL` repository secret. Until that secret is set the
workflow no-ops cleanly (it logs a notice and exits 0) rather than failing.