v0.4.0: Jekyll site scaffold for culture.dev/afi#7
Merged
Conversation
Modeled on agex-cli's setup: just-the-docs theme under docs/, baseurl /afi, jekyll-sitemap plugin so /afi/sitemap.xml is auto-generated at build time. Existing docs/*.md render untouched under the new baseurl. Deploy workflow (.github/workflows/docs.yml) mirrors the agex pipeline: PR previews + main deploy to Cloudflare Pages project `afi` via wrangler Direct Upload. Deploy step gated on CLOUDFLARE_API_TOKEN presence so CI stays green until the Pages project + secrets land via agentculture/cloudflare. Companion issues (to be opened) on agentculture/culture (site linkage) and agentculture/cloudflare (Pages project + secrets). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Review Summary by QodoAdd Jekyll site scaffold and Cloudflare Pages deploy pipeline
WalkthroughsDescription• Adds Jekyll site scaffold under docs/ with just-the-docs theme, baseurl /afi, and jekyll-sitemap plugin for auto-generated sitemap • Implements GitHub Actions workflow for PR previews and production deploy to Cloudflare Pages via wrangler Direct Upload • Deploy step gated on CLOUDFLARE_API_TOKEN presence to keep CI green until secrets provisioned • Bumps version to 0.4.0 with populated CHANGELOG.md entry per version-bump-every-PR policy Diagramflowchart LR
A["docs/ scaffold<br/>Jekyll + just-the-docs"] --> B["_config.yml<br/>baseurl /afi"]
A --> C["Gemfile<br/>jekyll-sitemap plugin"]
A --> D["index.md<br/>landing page"]
E["GitHub Actions<br/>docs.yml workflow"] --> F["Build Jekyll site"]
F --> G["Compute preview branch<br/>from PR head ref"]
G --> H{"Secrets<br/>present?"}
H -->|Yes| I["Deploy to CF Pages<br/>wrangler Direct Upload"]
H -->|No| J["Skip deploy<br/>post notice"]
I --> K["Post preview URL<br/>comment on PR"]
L["pyproject.toml"] --> M["Version 0.4.0"]
N["CHANGELOG.md"] --> M
File Changes1. .github/workflows/docs.yml
|
Code Review by Qodo
1. 0.4.0 changelog lacks JSON
|
![qodo-code-review[bot]](https://avatars.githubusercontent.com/in/484649?s=60&v=4){kind=small}
There was a problem hiding this comment.
Pull request overview
Adds a Jekyll-based documentation site scaffold under docs/ and a GitHub Actions workflow to build/deploy it to Cloudflare Pages, alongside a version bump to v0.4.0 with a corresponding changelog entry.
Changes:
- Add Jekyll/just-the-docs scaffold (config, Gemfile, index page, docs gitignore) under
docs/. - Add
.github/workflows/docs.ymlto build docs and (when secrets exist) deploy previews/production to Cloudflare Pages. - Bump project version to
0.4.0and add a0.4.0changelog entry.
Reviewed changes
Copilot reviewed 7 out of 8 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
uv.lock |
Updates locked editable package version to 0.4.0. |
pyproject.toml |
Bumps project version to 0.4.0. |
CHANGELOG.md |
Adds 0.4.0 release notes documenting docs scaffolding + deploy workflow. |
docs/index.md |
Adds landing page content for the new HTTP docs surface. |
docs/_config.yml |
Introduces Jekyll site configuration (theme/plugins/baseurl). |
docs/Gemfile |
Adds Ruby gem dependencies for Jekyll + plugins. |
docs/.gitignore |
Ignores Jekyll build artifacts and vendor caches. |
.github/workflows/docs.yml |
Adds CI workflow for building and deploying docs to Cloudflare Pages with PR previews. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Collaborator
Author
|
📘 docs preview for this PR:
|
5 tasks
- docs/_config.yml: drop custom color_scheme: dark-terminal (not present in this repo — that was an agex-local SCSS). Use built-in 'dark' scheme so Jekyll SCSS compile succeeds and CI docs build passes. Fixes the CI failure Qodo flagged. - .github/workflows/docs.yml: gate deploy on BOTH CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID (Qodo #4, Copilot). The notice now lists which specific secret is missing so nobody has to open the deploy log to find out. - .github/workflows/docs.yml: append /afi/ to the preview-URL comment (Qodo #2). Jekyll builds with baseurl: /afi, so the domain root returns a 404 — reviewers need the /afi/ entrypoint. - docs/agentculture.md, agent-first.md, rubric.md: add minimal front matter (title + nav_order) so just-the-docs renders them as themed pages with navigation + sitemap entries instead of raw markdown (Qodo #3, Copilot). Removed the now-redundant H1 lines since the theme renders `title:` as the page heading; keeps markdownlint MD025 single-h1 happy. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The secrets gate let wrangler through after CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID were added to the repo, but the Cloudflare Pages project `afi` does not exist yet — creation is tracked in agentculture/cloudflare#16. Wrangler then failed with HTTP 404 "Project not found", turning CI red for a real-but-tracked reason. Add a lightweight API precheck: GET /accounts/$ID/pages/projects/afi and require HTTP 200 before the deploy step runs. When the project lands on the CF side, CI flips green without another PR. No credentials leak — the account ID stays inside an env var (GitHub Actions already masks it). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
5 tasks
OriNachum
added a commit
to agentculture/culture
that referenced
this pull request
Apr 23, 2026
…288) Adds docs/reference/architecture/subsites.md documenting the reference pattern for hosting an AgentCulture project's docs as a sub-site under culture.dev. Blesses the afi-cli Jekyll scaffold (agentculture/afi-cli#7) and the earlier agex-cli scaffold as the canonical starting points; new sub-sites should begin from the afi-cli version. Spells out the five culture-side file edits every new sub-site needs — _data/sites.yml, _config.culture.yml aux_links, _config.culture.yml footer_content, _includes/head_custom.html rel=related, and sitemap.html — using the /agex and /afi entries as the concrete examples. Points at agentculture/cloudflare as the boundary for DNS / Pages project / Worker / Redirect Rule. Includes a new-sub-site checklist and when NOT to make a project a sub-site. Closes the fourth bullet of #288 ("bless the afi-cli scaffold pattern as reference for future AgentCulture sub-sites"), which Qodo flagged as a requirement gap on this PR. Also extends docs/reference/architecture/index.md from a one-liner into a navigable index so the new page has a landing point. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
OriNachum
added a commit
to agentculture/culture
that referenced
this pull request
Apr 23, 2026
* docs: add afi-cli site to culture.dev navigation + sitemap Wire culture.dev/afi alongside culture.dev/agex so the afi-cli docs site is discoverable from the main culture site — sites.yml entry, aux_links, footer, rel=related link, and sitemap index entry. Closes #288 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * docs(arch): bless afi-cli scaffold + codify sub-site pattern (closes #288) Adds docs/reference/architecture/subsites.md documenting the reference pattern for hosting an AgentCulture project's docs as a sub-site under culture.dev. Blesses the afi-cli Jekyll scaffold (agentculture/afi-cli#7) and the earlier agex-cli scaffold as the canonical starting points; new sub-sites should begin from the afi-cli version. Spells out the five culture-side file edits every new sub-site needs — _data/sites.yml, _config.culture.yml aux_links, _config.culture.yml footer_content, _includes/head_custom.html rel=related, and sitemap.html — using the /agex and /afi entries as the concrete examples. Points at agentculture/cloudflare as the boundary for DNS / Pages project / Worker / Redirect Rule. Includes a new-sub-site checklist and when NOT to make a project a sub-site. Closes the fourth bullet of #288 ("bless the afi-cli scaffold pattern as reference for future AgentCulture sub-sites"), which Qodo flagged as a requirement gap on this PR. Also extends docs/reference/architecture/index.md from a one-liner into a navigable index so the new page has a landing point. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
docs/modeled on agex-cli:just-the-docstheme,baseurl: /afi, and thejekyll-sitemapplugin so/afi/sitemap.xmlis auto-generated at build (required by the Agent First paradigm — agents navigate HTTP surfaces via sitemap, not heuristics)..github/workflows/docs.ymlthat mirrors agex's deploy pipeline: PR preview +maindeploy to Cloudflare Pages projectafiviawranglerDirect Upload, with a sticky preview-URL comment on PRs. Deploy step is gated onCLOUDFLARE_API_TOKENpresence, so this PR's CI stays green until the Pages project + secrets are provisioned.afi-clito v0.4.0 (minor — new surface, not a bug fix) with a populatedCHANGELOG.mdentry per the version-bump-every-PR policy.What this PR does NOT do
afior wireculture.dev/afirouting. That's the companion issue onagentculture/cloudflare(to be opened right after this PR).agentculture/culture.docs/agentculture.md,docs/agent-first.md, ordocs/rubric.md. They render under/afi/*unchanged.Test plan
uv run pytest -n auto -v— 136 passedscripts/lint-md.sh— clean (newdocs/index.mdlinted separately, MD025 resolved)python3 .claude/skills/version-bump/scripts/bump.py show→0.4.0::notice::line)agentculture/cloudflareprovisions the Pages project + secrets, re-run this workflow and verify the preview URL comment postsFollow-ups
agentculture/culture— add/afito the sites map, cross-link from the landing page.agentculture/cloudflare— create Pages projectafi, exposeCLOUDFLARE_API_TOKEN+CLOUDFLARE_ACCOUNT_IDtoagentculture/afi-cli, and wire theculture.dev/afi/*route.@spark-agexon culture IRC for a sanity check on the scaffold.@spark-cultureonce both issues exist so the work can proceed in parallel.— Claude
🤖 Generated with Claude Code