feat: migrate documentation to zensical by paul58914080 · Pull Request #5 · ff4j/docs

paul58914080 · 2026-02-06T16:04:33Z

No description provided.

…n guidelines

github-actions · 2026-02-06T16:04:54Z

📘 Site preview available:

https://ff4j.github.io/docs/pr-5/

Copilot

Pull request overview

Migrates the documentation site from the previous MkDocs configuration to a Zensical + uv-managed setup, updating the build/deploy pipeline and site theming/templates accordingly.

Changes:

Replace mkdocs.yml configuration with zensical.toml and add a Python/uv project (pyproject.toml, uv.lock, .python-version)
Add a new GitHub Actions workflow for PR previews + Pages publishing, plus repo governance files (CODEOWNERS, PR template, Dependabot)
Refresh homepage template/styles and add Bootstrap grid CSS for layout

Reviewed changes

Copilot reviewed 41 out of 121 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
zensical.toml	Introduces Zensical site configuration (project metadata, theme, nav, CSS).
uv.lock	Adds locked Python dependencies for Zensical-based docs build.
serve.sh	Adds local serve command wrapper (`uv run zensical serve -o`).
pyproject.toml	Defines the Python project and Zensical dependency.
mkdocs.yml	Removes legacy MkDocs configuration.
docs/stylesheets/theme.css	Adds/updates site theming CSS variables and homepage styling.
docs/stylesheets/bootstrap-grid.min.css	Adds Bootstrap grid stylesheet for responsive layout.
docs/pages/web/thymeleaf.md	Removes legacy MkDocs content page.
docs/pages/web/taglib.md	Removes legacy MkDocs content page.
docs/pages/web/index.md	Removes legacy MkDocs content page.
docs/pages/web/console.md	Removes legacy MkDocs content page.
docs/pages/web/apis.md	Removes legacy MkDocs content page.
docs/pages/v2/index.md	Removes legacy MkDocs content page.
docs/pages/strategy/index.md	Removes legacy MkDocs content page.
docs/pages/stores/index.md	Removes legacy MkDocs content page.
docs/pages/spring/index.md	Removes legacy MkDocs content page.
docs/pages/samples/index.md	Removes legacy MkDocs content page.
docs/pages/configuration.md	Removes legacy MkDocs content page.
docs/pages/basics/security.md	Removes legacy MkDocs content page.
docs/pages/basics/property-store.md	Removes legacy MkDocs content page.
docs/pages/basics/index.md	Removes legacy MkDocs content page.
docs/pages/basics/flipping-strategy.md	Removes legacy MkDocs content page.
docs/pages/basics/feature.md	Removes legacy MkDocs content page.
docs/pages/basics/feature-store.md	Removes legacy MkDocs content page.
docs/pages/basics/architecture.md	Removes legacy MkDocs content page.
docs/pages/advanced/spring-boot.md	Removes legacy MkDocs content page.
docs/pages/advanced/jmx.md	Removes legacy MkDocs content page.
docs/pages/advanced/feature-groups.md	Removes legacy MkDocs content page.
docs/pages/advanced/cli.md	Removes legacy MkDocs content page.
docs/pages/advanced/caching.md	Removes legacy MkDocs content page.
docs/pages/advanced/aop.md	Removes legacy MkDocs content page.
docs/overrides/main.html	Simplifies override to only extend `base.html`.
docs/overrides/home.html	Reworks homepage layout/content using grid + new visuals.
docs/index.md	Switches index page to use the new `home.html` template only.
docs/img/ff4j-logo.svg	Adds SVG logo asset used by the new theme config.
docs/home/img/upcoming.svg	Adds new homepage illustration asset.
docs/home/img/strategy.svg	Adds new homepage illustration asset.
docs/home/img/featuretoggle.svg	Adds new homepage illustration asset.
docs/home/img/canaryrelease.svg	Adds new homepage illustration asset.
docs/cheat.md	Removes legacy MkDocs “cheat sheet” page.
README.md	Updates local run instructions to the new toolchain entrypoint.
.python-version	Pins local Python version for the new `uv` workflow.
.gitignore	Updates ignores for `uv` venv/cache and site output.
.github/workflows/pages.yml	Adds PR preview publishing + Pages deploy workflow for Zensical build output.
.github/workflows/main.yml	Removes old MkDocs deployment workflow.
.github/dependabot.yml	Adds Dependabot config for `uv` + GitHub Actions updates.
.github/PULL_REQUEST_TEMPLATE.md	Adds a PR template focused on docs review/preview checks.
.github/CODEOWNERS	Adds code ownership for review routing.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-02-06T16:09:19Z

.github/workflows/pages.yml

+    if: github.event_name == 'pull_request' &&
+      github.event.action == 'closed' &&
+      github.event.pull_request.merged == false
+    runs-on: ubuntu-latest


The preview cleanup job only runs when a PR is closed and not merged, which leaves the pr-<number>/ preview folder behind for merged PRs. If previews should be ephemeral, adjust the condition to also clean up after merges (or document why merged previews should be retained).

Copilot · 2026-02-06T16:09:19Z

README.md

+## Prerequisites

-## Run the website locally
+- [zensical](https://zensical.org/docs/get-started/)

-### 1. Installation
+## Run locally

-```bash
-python3 -m pip install --upgrade pip     # install pip
-python3 -m pip install mkdocs            # install mkdocs 
-python3 -m pip install mkdocs-material   # install material theme
-#python3 -m pip install https://github.com/bmcorser/fontawesome-markdown/archive/master.zip   # install font-awesome
-python3 -m pip install mkdocs-git-revision-date-plugin # install git revision date
-python3 -m pip install mkdocs-video # install git revision date
+```shell
+sh ./serve.sh
 ```


The "Prerequisites" section only mentions Zensical, but serve.sh relies on uv being installed (and a compatible Python version). Consider updating the README to include installing uv (and running uv sync once) so the local run instructions are complete.

Copilot · 2026-02-06T16:09:19Z

zensical.toml

+nav = [
+   { "Home" = "index.md" }
+ ]


The new Zensical nav only includes index.md, and the previous documentation pages appear to have been removed from docs/ (no other .md files remain). If the intent is a full migration from the prior MkDocs site, you likely need to add the missing pages back (or relocate them) and expand nav so the documentation remains accessible.

Copilot · 2026-02-06T16:09:20Z

docs/overrides/home.html

+        <a href="#" class="md-button md-button--primary">
+          Get started
+        </a>
+        <a href="#" class="md-button link-color">
+          Learn more
+        </a>


The primary CTA links use href="#", which results in non-functional links in the generated homepage. Point these buttons to real pages (e.g., the first docs section / getting-started page) so users can navigate from the landing page.

Copilot · 2026-02-06T16:09:20Z

.github/workflows/pages.yml

+      - name: Comment PR with preview URL
+        if: github.event_name == 'pull_request'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const pr = context.payload.pull_request.number;
+            const { owner, repo } = context.repo;
+
+            const url = `https://ff4j.github.io/docs/pr-${pr}/`;
+
+            await github.rest.issues.createComment({
+              owner,
+              repo,
+              issue_number: pr,
+              body: `📘 **Site preview available**:\n\n${url}`
+            });
+


This workflow posts a new PR comment on every synchronize event, which will spam the PR thread on iterative pushes. Consider making the comment idempotent (search for an existing comment containing a unique marker and update it) or use a dedicated "sticky comment" approach.

Copilot · 2026-02-06T16:09:20Z

.github/workflows/pages.yml

+      - name: "Set up Python"
+        uses: actions/setup-python@v6
+        with:
+          python-version-file: "pyproject.toml"
+


actions/setup-python is configured with python-version-file: "pyproject.toml", but this repo also adds a .python-version file. If setup-python can't parse pyproject.toml for the version, CI will fail; it’s safer to point python-version-file at .python-version (or set python-version explicitly).

Copilot · 2026-02-06T16:09:20Z

.github/workflows/pages.yml

+    environment:
+      name: github-pages
+      url: https://paulwilliams.dev
+    steps:


The GitHub Pages environment URL is set to https://paulwilliams.dev, which doesn’t match the project’s configured docs URL (https://ff4j.github.io/docs/). This will show an incorrect deployment link in GitHub’s UI; update it to the actual GitHub Pages (or custom) domain for this site.

paul58914080 added 15 commits January 18, 2026 09:24

refactor: remove all files

ddf7c74

feat: initial files for ff4j

6204a8d

ci: documentation ci

56d75c0

ci: add CODEOWNERS

6faad74

ci: add dependabot for uv and action

41a7b87

ci: add pr template

79f8899

ci: clean up condition updated

bfcfa62

docs: add logo

3d59cb0

feat: home page and theme

4b45cc1

style: update feature section heading margin

060f567

docs(home): add feature toggle image

6752de2

docs(home): add all images

bb42746

docs(home): update links to stay on home

c12676a

docs(README): expand documentation with prerequisites and contributio…

a3c22a2

…n guidelines

ci: rename docs.yml to pages.yml and update deployment settings

06092e8

Copilot AI review requested due to automatic review settings February 6, 2026 16:04

Copilot started reviewing on behalf of paul58914080 February 6, 2026 16:04 View session

paul58914080 merged commit afe2622 into main Feb 6, 2026
7 checks passed

paul58914080 deleted the feature/zensical branch February 6, 2026 16:08

Copilot AI reviewed Feb 6, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: migrate documentation to zensical#5

feat: migrate documentation to zensical#5
paul58914080 merged 15 commits intomainfrom
feature/zensical

paul58914080 commented Feb 6, 2026

Uh oh!

github-actions bot commented Feb 6, 2026

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Feb 6, 2026

Uh oh!

Copilot AI Feb 6, 2026

Uh oh!

Copilot AI Feb 6, 2026

Uh oh!

Copilot AI Feb 6, 2026

Uh oh!

Copilot AI Feb 6, 2026

Uh oh!

Copilot AI Feb 6, 2026

Uh oh!

Copilot AI Feb 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

paul58914080 commented Feb 6, 2026

Uh oh!

github-actions bot commented Feb 6, 2026

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Feb 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 6, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant