feat(site): GitHub Pages — cosmic-green landing + MkDocs Material docs

.github/workflows/pages.yml

@@ -0,0 +1,67 @@
+name: Deploy GitHub Pages
+
+# Builds the landing page (web/) + docs (MkDocs Material) into _site/ and
+# deploys to GitHub Pages. Requires repo Settings → Pages → Source: GitHub Actions.
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "web/**"
+      - "docs/**"
+      - "assets/**"
+      - "overrides/**"
+      - "mkdocs.yml"
+      - "scripts/build_site.py"
+      - "requirements-docs.txt"
+      - ".github/workflows/pages.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow one concurrent deployment; don't cancel an in-progress production deploy.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: requirements-docs.txt
+
+      - name: Install docs toolchain
+        run: pip install -r requirements-docs.txt
+
+      - name: Build site (landing + docs)
+        run: python scripts/build_site.py
+
+      - name: Configure Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: _site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -27,6 +27,10 @@ docs/plans/
 # Superpowers brainstorming visual companion scratch (local only)
 .superpowers/
 
+# GitHub Pages site build output (assembled by scripts/build_site.py)
+/_site/
+/site/
+
 # The book's build sources are real source, not the Python build/ artifact dir
 !book/build/
 !book/build/**

docs/stylesheets/pyfly.css

@@ -0,0 +1,94 @@
+/* ============================================================
+   PyFly docs theme — MkDocs Material, cosmic-green identity.
+   Mirrors the brand palette in assets/ (banner.svg, diagrams).
+   ============================================================ */
+
+/* ---- custom primary (deep green header in both schemes) ---- */
+[data-md-color-primary="custom"] {
+  --md-primary-fg-color: #1f5e16;
+  --md-primary-fg-color--light: #2c8a1c;
+  --md-primary-fg-color--dark: #143f0f;
+  --md-primary-bg-color: #f4f9ee;
+  --md-primary-bg-color--light: #f4f9eeb3;
+}
+
+[data-md-color-accent="custom"] {
+  --md-accent-fg-color: #4cbb2f;
+  --md-accent-fg-color--transparent: #4cbb2f1f;
+  --md-accent-bg-color: #ffffff;
+  --md-accent-bg-color--light: #ffffffb3;
+}
+
+/* ---- light scheme ---- */
+[data-md-color-scheme="default"] {
+  --md-typeset-a-color: #2c8a1c;
+  --md-footer-bg-color: #0a1410;
+  --md-footer-bg-color--dark: #07110b;
+}
+
+/* ---- dark scheme: cosmic green-tinted ---- */
+[data-md-color-scheme="slate"] {
+  --md-hue: 145;
+  --md-default-bg-color: #0b150e;
+  --md-default-bg-color--light: #0e1812;
+  --md-default-fg-color: #e9f2e2;
+  --md-default-fg-color--light: #bacbb0;
+  --md-default-fg-color--lighter: #85957e;
+  --md-default-fg-color--lightest: #3a4a33;
+  --md-code-bg-color: #07110b;
+  --md-code-fg-color: #cdddc2;
+  --md-typeset-a-color: #7ed321;
+  --md-accent-fg-color: #c2e85f;
+  --md-footer-bg-color: #07110b;
+  --md-footer-bg-color--dark: #060d08;
+}
+
+/* ---- Maven Pro for headings & chrome (matches the wordmark) ---- */
+.md-typeset h1,
+.md-typeset h2,
+.md-typeset h3,
+.md-typeset h4,
+.md-header__title,
+.md-nav__title,
+.md-tabs__link,
+.md-ellipsis {
+  font-family: "Maven Pro", system-ui, sans-serif;
+}
+.md-typeset h1,
+.md-typeset h2 { letter-spacing: -0.01em; font-weight: 700; }
+
+/* green title rule under H2 — a brand motif from the README/book */
+.md-typeset h2 {
+  border-bottom: 1px solid var(--md-default-fg-color--lightest);
+  padding-bottom: 0.35em;
+}
+.md-typeset h2::before {
+  content: "";
+  display: inline-block;
+  width: 0.7em;
+  height: 0.7em;
+  margin-right: 0.45em;
+  vertical-align: -1px;
+  border-radius: 50%;
+  background: radial-gradient(circle, #dff58a 0%, #7ed321 45%, rgba(76, 187, 47, 0) 72%);
+}
+
+/* logo: give the firefly mark a soft glow on the header */
+.md-header__button.md-logo img {
+  filter: drop-shadow(0 0 6px rgba(194, 232, 95, 0.5));
+}
+
+/* hero/landing back-link affordance in the header title */
+.md-header__title { font-weight: 700; }
+
+/* code copy + admonition accents stay green via accent var; nudge inline code */
+[data-md-color-scheme="slate"] .md-typeset code {
+  background-color: rgba(126, 211, 33, 0.1);
+}
+
+/* search highlight + active nav in brand green */
+.md-nav__link--active,
+.md-nav__item .md-nav__link--active { color: var(--md-typeset-a-color); }
+
+/* tables: subtle brand border */
+.md-typeset table:not([class]) th { background: rgba(126, 211, 33, 0.08); }

mkdocs.yml

@@ -0,0 +1,196 @@
+# MkDocs Material configuration for the PyFly documentation site.
+# Renders the existing docs/*.md into https://fireflyframework.github.io/fireflyframework-pyfly/docs/
+# The landing page (web/) and brand assets are assembled around this build by scripts/build_site.py.
+
+site_name: PyFly
+site_description: >-
+  The official Python implementation of the Firefly Framework — Spring Boot's
+  cohesion, native to async Python. Dependency injection, CQRS, sagas, event
+  sourcing and more, with production-ready defaults from day one.
+site_author: Firefly Software Foundation
+site_url: https://fireflyframework.github.io/fireflyframework-pyfly/docs/
+
+repo_url: https://github.com/fireflyframework/fireflyframework-pyfly
+repo_name: fireflyframework-pyfly
+edit_uri: edit/main/docs/
+
+docs_dir: docs
+# Keep internal brainstorming specs and the duplicate root index out of the public docs.
+exclude_docs: |
+  /README.md
+  superpowers/
+
+copyright: >-
+  Apache License 2.0 · © Firefly Software Foundation —
+  <a href="https://fireflyframework.github.io/fireflyframework-pyfly/">PyFly home</a>
+
+theme:
+  name: material
+  logo: assets/pyfly-mark.svg
+  favicon: assets/pyfly-mark.svg
+  custom_dir: overrides
+  font:
+    text: Roboto
+    code: Roboto Mono
+  icon:
+    repo: fontawesome/brands/github
+  palette:
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: custom
+      accent: custom
+      toggle:
+        icon: material/weather-night
+        name: Switch to light mode
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: custom
+      accent: custom
+      toggle:
+        icon: material/weather-sunny
+        name: Switch to dark mode
+  features:
+    - navigation.tabs
+    - navigation.sections
+    - navigation.top
+    - navigation.tracking
+    - navigation.indexes
+    - navigation.footer
+    - toc.follow
+    - search.suggest
+    - search.highlight
+    - search.share
+    - content.code.copy
+    - content.code.annotate
+    - content.tabs.link
+
+extra_css:
+  - stylesheets/pyfly.css
+
+extra:
+  # Make the header logo/title link back to the landing page instead of the docs index.
+  homepage: https://fireflyframework.github.io/fireflyframework-pyfly/
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/fireflyframework/fireflyframework-pyfly
+      name: PyFly on GitHub
+    - icon: fontawesome/brands/python
+      link: https://github.com/fireflyframework
+      name: The Firefly Framework
+
+markdown_extensions:
+  - abbr
+  - admonition
+  - attr_list
+  - def_list
+  - footnotes
+  - md_in_html
+  - tables
+  - toc:
+      permalink: true
+      title: On this page
+  - pymdownx.betterem
+  - pymdownx.caret
+  - pymdownx.details
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.keys
+  - pymdownx.mark
+  - pymdownx.smartsymbols
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.tasklist:
+      custom_checkbox: true
+  - pymdownx.tilde
+
+plugins:
+  - search
+
+nav:
+  - Home: index.md
+  - Getting Started: getting-started.md
+  - Installation: installation.md
+  - Architecture: architecture.md
+  - CLI Reference: cli.md
+  - Spring Comparison: spring-comparison.md
+  - Versioning: versioning.md
+  - Modules:
+      - Overview: modules/README.md
+      - Foundation:
+          - Core: modules/core.md
+          - Dependency Injection: modules/dependency-injection.md
+          - Configuration: modules/configuration.md
+          - Logging: modules/logging.md
+          - Error Handling: modules/error-handling.md
+      - Web & API:
+          - Web Layer: modules/web.md
+          - Web Filters: modules/web-filters.md
+          - Server Layer: modules/server.md
+          - Validation: modules/validation.md
+          - Sessions: modules/session.md
+          - WebSockets: modules/websocket.md
+          - Internationalization: modules/i18n.md
+      - Data:
+          - Data Commons: modules/data.md
+          - Data Relational (SQL): modules/data-relational.md
+          - Data Document (MongoDB): modules/data-document.md
+      - CQRS & Domain:
+          - CQRS: modules/cqrs.md
+          - Domain (DDD): modules/domain.md
+      - Messaging & Eventing:
+          - Messaging: modules/messaging.md
+          - Events (EDA): modules/events.md
+          - Event Sourcing: modules/eventsourcing.md
+      - Distributed Transactions:
+          - Transactional Engine: modules/transactional.md
+      - Business Logic:
+          - Rule Engine: modules/rule-engine.md
+          - Plugins: modules/plugins.md
+      - Security & Identity:
+          - Security: modules/security.md
+          - Identity Provider (IDP): modules/idp.md
+      - Integrations:
+          - Content Management (ECM): modules/ecm.md
+          - Notifications: modules/notifications.md
+          - Callbacks (outbound): modules/callbacks.md
+          - Webhooks (inbound): modules/webhooks.md
+      - Resilience & Clients:
+          - HTTP Client: modules/client.md
+          - Resilience: modules/resilience.md
+          - Caching: modules/caching.md
+          - Scheduling: modules/scheduling.md
+          - Shell: modules/shell.md
+          - Config Server: modules/config-server.md
+      - Observability & Admin:
+          - Observability: modules/observability.md
+          - Actuator: modules/actuator.md
+          - Custom Actuator Endpoints: modules/custom-actuator-endpoints.md
+          - Admin Dashboard: modules/admin.md
+          - AOP: modules/aop.md
+      - Testing:
+          - Testing: modules/testing.md
+          - Integration Testing: modules/integration-testing.md
+      - Starters: modules/starters.md
+  - Adapters:
+      - Overview: adapters/README.md
+      - SQLAlchemy: adapters/sqlalchemy.md
+      - MongoDB: adapters/mongodb.md
+      - Starlette: adapters/starlette.md
+      - FastAPI: adapters/fastapi.md
+      - Granian: adapters/granian.md
+      - Kafka: adapters/kafka.md
+      - RabbitMQ: adapters/rabbitmq.md
+      - Redis: adapters/redis.md
+      - HTTPX: adapters/httpx.md
+      - Click: adapters/click.md

overrides/main.html

@@ -0,0 +1,9 @@
+{% extends "base.html" %}
+
+<!-- Inject the Maven Pro wordmark typeface used across the PyFly brand. -->
+{% block extrahead %}
+  {{ super() }}
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=Maven+Pro:wght@500;600;700;800&display=swap" rel="stylesheet">
+{% endblock %}