Comprehensive documentation update

.github/workflows/pybuilder.github.io.yml

@@ -10,10 +10,10 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - uses: ruby/setup-ruby@v1
         with:
-          ruby-version: "3.1"
+          ruby-version: "3.4"
           bundler-cache: false
       - name: Install Dependencies
         run: bundle install

CLAUDE.md

@@ -0,0 +1,200 @@
+# PyBuilder Documentation Site — Project Instructions
+
+## Overview
+
+This is the official documentation website for [PyBuilder](https://pybuilder.io),
+hosted on GitHub Pages. It is a Jekyll static site. The source lives on the `source`
+branch; the `master` branch contains only the built output deployed by CI.
+
+Repository: `pybuilder/pybuilder.github.io` (origin, not a fork).
+
+## Branch Model
+
+- **`source`** — all development happens here. This is the default working branch.
+- **`master`** — auto-deployed built site. Never edit or push to `master` directly.
+- **`plugin_doc_gen`** — WIP branch for plugin documentation rework.
+- **`bootstrap_4`** — stale Bootstrap 4 migration branch.
+
+PRs target `source`. The CI deploys to `master` on push to `source`.
+
+## Site Structure
+
+```
+_config.yml              — primary Jekyll configuration
+_config-prod.yml         — production URL overlay (https://pybuilder.io)
+Gemfile                  — Ruby dependencies (Jekyll 4.x, plugins, html-proofer)
+build.sh                 — CI build script (build, validate, rebuild with prod config)
+CNAME                    — custom domain (pybuilder.io)
+
+_layouts/
+  default.html           — base layout (header, container, footer)
+  documentation.html     — two-column layout with auto-generated ToC sidebar
+  post.html              — blog post layout with author metadata
+
+_includes/layout/
+  metaAndStyles.html     — Google Analytics, meta tags, CSS imports
+  header.html            — navbar with navigation dropdowns
+  footer.html            — links, scripts, JS imports
+
+_plugins/
+  pybuilder.rb           — custom Liquid filters (abs/rel canonical URL helpers)
+
+_data/
+  authors.yml            — author profiles referenced by blog posts
+
+documentation/           — all documentation pages (layout: documentation)
+  index.md               — documentation hub
+  installation.md        — installation guide
+  tutorial.md            — comprehensive tutorial (~590 lines, largest doc)
+  manual.md              — usage manual
+  plugins.md             — built-in plugin reference (~1100 lines)
+  writing-plugins.md     — plugin development guide
+  publishing-plugins.md  — how to publish plugins
+  external-plugin-list.md — third-party plugins
+  examples.md            — example projects
+  ide.md                 — IDE integration
+  developing-pybuilder.md — contributing to PyBuilder core
+
+articles/                — Jekyll collections directory
+  _posts/                — blog posts (layout: post, author: <key from authors.yml>)
+  _release-notes/        — release notes collection (v0.10.x through v0.13.x)
+  _migration-guides/     — migration guides collection
+
+css/                     — custom stylesheets (styles.css, highlightjs.css, tabcontent.css)
+js/                      — custom JS (highlight.pack.js, tabcontent.js, toc.js)
+img/                     — logos, mascot, screenshots
+```
+
+## Building Locally
+
+```bash
+# Install Ruby dependencies
+bundle install
+
+# Start development server with live reload
+bundle exec jekyll serve --watch
+# Browse to http://localhost:4000
+
+# Full CI-equivalent build (build + htmlproofer + prod rebuild)
+./build.sh
+```
+
+## CI / Deployment
+
+GitHub Actions workflow at `.github/workflows/pybuilder.github.io.yml`:
+1. Triggers on PRs to `source` and pushes to `source`
+2. Sets up Ruby 3.1, installs bundle dependencies
+3. Runs `build.sh`:
+   - `jekyll build` (dev config)
+   - `htmlproofer` validates links, scripts, images, OpenGraph, favicon
+   - `jekyll build -c _config.yml,_config-prod.yml` (prod config with real URL)
+4. On push (not PR): deploys `_site/` to `master` branch
+
+## Content Conventions
+
+### Documentation Pages
+
+- Layout: `documentation` (provides auto-ToC sidebar)
+- Front matter: `layout: documentation`, `title: <Page Title>`
+- Use `{% link documentation/filename.md %}` for cross-references
+- Markdown with kramdown extensions (fenced code blocks, etc.)
+
+### Blog Posts
+
+- Location: `articles/_posts/YYYY-MM-DD-slug.md`
+- Layout: `post`
+- Front matter: `layout: post`, `title`, `author` (key from `_data/authors.yml`)
+- Optional: `update_date` for showing last-updated
+
+### Release Notes
+
+- Location: `articles/_release-notes/vX.Y.x.md`
+- One file per minor version series
+
+### Migration Guides
+
+- Location: `articles/_migration-guides/vX.Y.x-vA.B.C.md`
+
+## Technology Stack
+
+- Jekyll 4.x with kramdown (Markdown) and rouge (syntax highlighting)
+- Bootstrap 3.4.1 (CSS framework)
+- jQuery 3.4.1
+- bootstrap-toc 0.4.1 (auto table of contents)
+- highlight.js (code highlighting)
+- lite-youtube 1.5.0 (lazy YouTube embeds)
+- Plugins: jekyll-sitemap, jekyll-paginate, jekyll-last-modified-at,
+  jekyll-redirect-from, jekyll-seo-tag, jekyll-feed, jemoji, and others
+
+## Git Workflow
+
+This is an origin repo (not a fork). All changes go through PRs to `source`.
+Never push directly to `source` or `master`.
+
+## Content Editing
+
+- Keep documentation accurate with respect to the current PyBuilder release.
+  Cross-reference the main PyBuilder repo at `../pybuilder/` for feature details.
+- Preserve existing front matter fields exactly. Do not add or remove fields
+  unless intentionally changing page behavior.
+- Use the `{% link %}` Liquid tag for internal cross-references, never raw paths.
+- Do not reformat or rewrap existing paragraphs that you are not changing.
+  Minimize diff noise.
+
+## Layouts and Includes
+
+- Bootstrap 3, not 4 or 5. The `bootstrap_4` migration was never completed.
+  Do not upgrade Bootstrap unless explicitly asked.
+- Google Analytics tag is in `_includes/layout/metaAndStyles.html`. Do not
+  modify or remove it.
+- Navigation structure is in `_includes/layout/header.html`. When adding new
+  documentation pages, add a corresponding nav entry there and in
+  `documentation/index.md`.
+
+## Adding New Documentation Pages
+
+1. Create the `.md` file in `documentation/` with front matter:
+   ```yaml
+   ---
+   layout: documentation
+   title: Your Page Title
+   ---
+   ```
+2. Add a link in `documentation/index.md` under the appropriate section
+3. Add a navigation entry in `_includes/layout/header.html`
+
+## Adding Blog Posts
+
+1. Create `articles/_posts/YYYY-MM-DD-slug.md` with front matter:
+   ```yaml
+   ---
+   layout: post
+   title: "Post Title"
+   author: arcivanov
+   ---
+   ```
+2. Author key must exist in `_data/authors.yml`
+
+## Adding Release Notes
+
+1. If a file for the minor version series exists, append to it
+2. Otherwise create `articles/_release-notes/vX.Y.x.md`
+3. The release notes index auto-generates from the collection
+
+## Testing Changes
+
+- Always run `bundle exec jekyll build` to verify the site builds without errors
+- For thorough validation, run `./build.sh` which also checks links and images
+  via htmlproofer
+- htmlproofer may fail on transient external link issues (429, timeouts). These
+  are usually not your fault. Check if the link is actually broken before fixing.
+
+## Things to Avoid
+
+- Do not edit files on the `master` branch. It is auto-generated.
+- Do not add `Gemfile.lock` to version control (it is gitignored).
+- Do not modify vendored JS libraries (`highlight.pack.js`, jQuery, Bootstrap)
+  unless upgrading them intentionally.
+- Do not remove or alter the `CNAME` file.
+- Do not change `_config.yml` pagination or permalink settings without
+  understanding the URL impact on existing links and SEO.

Gemfile

@@ -1,36 +1,39 @@
 source "https://rubygems.org"
 
 gem "html-proofer"
-gem "jekyll", "~> 4.0"
-gem "jekyll-sass-converter" #, "~>2.0
+gem "jekyll", "~> 4.4"
+gem "jekyll-sass-converter"
+
+# Ruby 3.4+ stdlib extractions
+gem "csv"
+gem "base64"
 
 # Converters
-gem "kramdown" #, "1.17.0"
-gem "jekyll-commonmark-ghpages" # "0.1.6"
+gem "kramdown"
+gem "jekyll-commonmark-ghpages"
 
 # Misc
-gem "liquid" #=> "4.0.3",
-gem "rouge" #=> "3.13.0",
-gem "github-pages-health-check" #=> "1.16.1",
+gem "liquid"
+gem "rouge"
+gem "github-pages-health-check"
 
 # Plugins
-gem "jekyll-redirect-from" #=> "0.15.0",
-gem "jekyll-sitemap" #=> "1.4.0",
+gem "jekyll-redirect-from"
+gem "jekyll-sitemap"
 gem "jekyll-last-modified-at"
-gem "jekyll-feed" #=> "0.13.0",
-gem "jekyll-gist" #=> "1.5.0",
-gem "jekyll-paginate" #=> "1.1.0",
-gem "jekyll-coffeescript" #=> "1.1.1",
-gem "jekyll-seo-tag" #=> "2.6.1",
-gem "jekyll-github-metadata" #=> "2.13.0",
-gem "jekyll-avatar" #=> "0.7.0",
-gem "jekyll-remote-theme" #=> "0.4.1",
+gem "jekyll-feed"
+gem "jekyll-gist"
+gem "jekyll-paginate"
+gem "jekyll-coffeescript"
+gem "jekyll-seo-tag"
+gem "jekyll-github-metadata"
+gem "jekyll-avatar"
+gem "jekyll-remote-theme"
 
 # Plugins to match GitHub.com Markdown
-gem "jemoji" #=> "0.11.1",
-gem "jekyll-mentions" #=> "1.5.1",
-gem "jekyll-relative-links" #=> "0.6.1",
-gem "jekyll-optional-front-matter" #=> "0.3.2",
-gem "jekyll-readme-index" #=> "0.3.0",
-# gem "jekyll-default-layout" #=> "0.1.4",
-gem "jekyll-titles-from-headings" #=> "0.5.3",
+gem "jemoji"
+gem "jekyll-mentions"
+gem "jekyll-relative-links"
+gem "jekyll-optional-front-matter"
+gem "jekyll-readme-index"
+gem "jekyll-titles-from-headings"

_data/authors.yml

@@ -10,4 +10,3 @@ mriehl:
   name: Maximilien Riehl
   email: max@riehl.io
   github: mriehl
-  website: https://max.riehl.io/

_includes/layout/header.html

@@ -51,6 +51,9 @@
                                 <li>
                                     <a href="/documentation/ide">IDE integration</a>
                                 </li>
+                                <li>
+                                    <a href="/documentation/coding-agents">Coding Agents</a>
+                                </li>
                             </ul>
                         </li>
                         <li class="dropdown-submenu">

_layouts/post.html

@@ -30,21 +30,21 @@ <h1>{{ page.title }}</h1>
                     {% endif %}
                     {% if author.github %}
                     <a rel="author" href="https://github.com/{{ author.github }}" title="{{ author.name }}'s GitHub">
-                        <img src="https://external-content.duckduckgo.com/ip/github.com.ico" alt="GitHub Logo"></a>
+                        <img src="https://icons.duckduckgo.com/ip3/github.com.ico" alt="GitHub Logo"></a>
                     {% endif %}
                     {% if author.openhub %}
                     <a rel="author" href="https://www.openhub.net/accounts/{{ author.openhub }}"
                        title="{{ author.name }}'s OpenHub">
-                        <img src="https://external-content.duckduckgo.com/ip/openhub.net.ico" alt="OpenHub Logo"></a>
+                        <img src="https://icons.duckduckgo.com/ip3/openhub.net.ico" alt="OpenHub Logo"></a>
                     {% endif %}
                     {% if author.twitter %}
-                    <a rel="author" href="https://twitter.com/{{ author.twitter }}" title="{{ author.name }}'s Twitter">
-                        <img src="https://external-content.duckduckgo.com/ip/twitter.com.ico" alt="Twitter Logo"></a>
+                    <a rel="author" href="https://x.com/{{ author.twitter }}" title="{{ author.name }}'s X">
+                        <img src="https://icons.duckduckgo.com/ip3/x.com.ico" alt="X Logo"></a>
                     {% endif %}
                     {% if author.linkedin %}
                     <a rel="author" href="https://www.linkedin.com/in/{{ author.linkedin }}/"
                        title="{{ author.name }}'s LinkedIn">
-                        <img src="https://external-content.duckduckgo.com/ip/linkedin.com.ico" alt="LinkedIn Logo">
+                        <img src="https://icons.duckduckgo.com/ip3/linkedin.com.ico" alt="LinkedIn Logo">
                     </a>
                     {% endif %}
                     {% endif %}

about.html

@@ -13,7 +13,7 @@ <h2>Who Built The PyBuilder?</h2>
             Past maintainers include Maximilien Riehl and Michael Gruber.
         </p>
         <p>
-            As of 2020 <a href="https://www.ivanov.biz/">Arcadiy Ivanov</a> is actively developing PyBuilder.
+            <a href="https://www.ivanov.biz/">Arcadiy Ivanov</a> is the current maintainer and active developer of PyBuilder.
         </p>
     </div>
 </div>

articles/_posts/2022-06-15-version-0.13.6-python-3.11.md

@@ -0,0 +1,15 @@
+---
+layout: post
+title: "Python 3.11 Support in PyBuilder 0.13.6"
+author: arcivanov
+categories: news
+---
+
+PyBuilder 0.13.6 adds support for Python 3.11, which introduced breaking changes
+to both the `multiprocessing` module's spawn mechanism and the `unittest.TestCase`
+internal results API. Both are core to PyBuilder's test isolation infrastructure
+and required targeted fixes.
+
+This release also drops support for Python 3.6.
+
+See the [release notes](/release-notes/v0.13.x) for details.

articles/_posts/2022-11-03-version-0.13.8-debug-venvs.md

@@ -0,0 +1,18 @@
+---
+layout: post
+title: "PyBuilder 0.13.8: Debug Python Support and Log Formatting"
+author: arcivanov
+categories: news
+---
+
+PyBuilder 0.13.8 brings two notable improvements:
+
+**Debug/release venv distinction.** Managed virtual environments now distinguish
+between debug and release builds of Python. Debug builds (compiled with `--with-pydebug`)
+get their own isolated venv directories, preventing ABI-incompatible packages from
+being mixed between debug and release environments.
+
+**Configurable log format.** A new `--log-format` command line parameter allows
+customizing PyBuilder's log output format.
+
+See the [release notes](/release-notes/v0.13.x) for details.

articles/_posts/2024-02-14-version-0.13.11-python-3.12.md

@@ -0,0 +1,12 @@
+---
+layout: post
+title: "PyBuilder 0.13.11: Python 3.12 Support"
+author: arcivanov
+categories: news
+---
+
+PyBuilder 0.13.11 officially supports Python 3.12. Preliminary fixes for 3.12
+compatibility landed in v0.13.10, and this release completes the work with full
+CI coverage across CPython 3.8 through 3.12 on Linux, macOS, and Windows.
+
+See the [release notes](/release-notes/v0.13.x) for details.

articles/_posts/2024-06-04-version-0.13.13-drop-python-3.8.md

@@ -0,0 +1,15 @@
+---
+layout: post
+title: "PyBuilder 0.13.13: Python 3.8 End of Life"
+author: arcivanov
+categories: news
+---
+
+PyBuilder 0.13.13 drops support for Python 3.8, which reached end of life in
+October 2024. The minimum supported version is now Python 3.9.
+
+This release also improves handling of dependency extras in the `Dependency` class,
+fixing cases where extras specifications were not properly considered during
+dependency resolution.
+
+See the [release notes](/release-notes/v0.13.x) for details.