Merge pull request #167 from fcendesu/codex/analytics-integration

feat(config): add optional analytics integration

Author: fcendesu

assets/themes/atlas/templates/partials/head_assets.html

@@ -19,6 +19,9 @@
   {{ site_font_faces_css | safe }}
 </style>
 {% endif %}
+{% if site_analytics_head_html %}
+{{ site_analytics_head_html | safe }}
+{% endif %}
 <link rel="stylesheet" href="{{ asset_url(path='style.css') }}?v={{ site_asset_version }}" />
 <link rel="stylesheet" href="{{ asset_url(path='palette.css') }}?v={{ site_asset_version }}" />
 {% if site_has_custom_css %}

assets/themes/journal/templates/partials/head_assets.html

@@ -19,6 +19,9 @@
   {{ site_font_faces_css | safe }}
 </style>
 {% endif %}
+{% if site_analytics_head_html %}
+{{ site_analytics_head_html | safe }}
+{% endif %}
 <link rel="stylesheet" href="{{ asset_url(path='style.css') }}?v={{ site_asset_version }}" />
 <link rel="stylesheet" href="{{ asset_url(path='palette.css') }}?v={{ site_asset_version }}" />
 {% if site_has_custom_css %}

docs/cli.md

@@ -49,6 +49,18 @@ Project validation:
 rustipo check
 ```
 
+Analytics configuration is opt-in. For the first built-in integration, Rustipo supports Plausible
+with an optional self-hosted script override:
+
+```toml
+[site.analytics.plausible]
+domain = "docs.example.com"
+# Optional for self-hosted Plausible:
+# script_src = "https://stats.example.com/js/script.js"
+```
+
+Built-in themes render the analytics snippet automatically when configured.
+
 Theme discovery:
 
 ```bash
@@ -155,6 +167,7 @@ Current behavior:
   - `site.typography.heading_font`
   - `site.typography.mono_font`
 - Exposes `site_font_faces_css` to templates for optional font-face injection
+- Exposes `site_analytics_head_html` to templates for opt-in analytics snippet output
 - Auto-includes `static/custom.css` in template context when present (`site_has_custom_css`)
 - Writes rendered pages to `dist/` using pretty URL output paths
 - Writes generated palette variables to `dist/palette.css`

docs/implemented-features.md

@@ -232,6 +232,7 @@
 - `site_favicon_ico`
 - `site_apple_touch_icon`
 - `site_asset_version`
+- `site_analytics_head_html`
 - `site_style`
   - `content_width`
   - `top_gap`
@@ -269,6 +270,8 @@
 - resolution order:
   - `page_summary`
   - `site_description`
+- opt-in Plausible analytics snippet support in built-in themes
+- optional self-hosted Plausible `script_src` override
 - `route`
 - `section_name`
 - `section_title`

docs/theme-contract.md

@@ -198,6 +198,7 @@ Rustipo injects common site variables into template contexts, including:
   - `next_url`
 - favicon helpers: `site_favicon`, `site_favicon_svg`, `site_favicon_ico`, `site_apple_touch_icon`
 - asset helper: `site_asset_version` (stable cache-busting fingerprint for generated asset URLs)
+- analytics helper: `site_analytics_head_html` (optional provider-agnostic head snippet for configured analytics)
 - style helpers from config:
   - `site_style.content_width`
   - `site_style.top_gap`
@@ -216,6 +217,25 @@ Rustipo injects common site variables into template contexts, including:
 
 If both values are empty, Rustipo leaves `page_description` unset so themes can omit the tag cleanly.
 
+`site_analytics_head_html` is the stable hook for built-in analytics integrations. In `v0.15`,
+Rustipo supports opt-in Plausible analytics via:
+
+```toml
+[site.analytics.plausible]
+domain = "docs.example.com"
+# Optional for self-hosted Plausible:
+# script_src = "https://stats.example.com/js/script.js"
+```
+
+When present, Rustipo renders a ready-to-include head snippet. Themes can inherit the built-in
+head partial behavior or explicitly render:
+
+```html
+{% if site_analytics_head_html %}
+{{ site_analytics_head_html | safe }}
+{% endif %}
+```
+
 Rustipo also registers small Tera helpers for theme authors:
 
 - `slugify` filter

docs/theme-tera.md

@@ -78,6 +78,7 @@ Rustipo injects common values such as:
 - `site_title`
 - `site_description`
 - `site_asset_version`
+- `site_analytics_head_html`
 - `site_taxonomies`
 - `site_style.*`
 
@@ -88,6 +89,19 @@ Rustipo injects common values such as:
 
 If both are empty, `page_description` is omitted.
 
+`site_analytics_head_html` is the stable convenience value for built-in analytics output. In
+`v0.15`, Rustipo supports opt-in Plausible configuration from `config.toml`:
+
+```toml
+[site.analytics.plausible]
+domain = "docs.example.com"
+# Optional for self-hosted Plausible:
+# script_src = "https://stats.example.com/js/script.js"
+```
+
+When configured, `site_analytics_head_html` contains a ready-to-render `<script defer ...>`
+snippet. Built-in themes already include it in their shared head partials.
+
 Rustipo also injects stable navigation and page-state values:
 
 - `page_kind`

site/content/reference/cli.md

@@ -8,6 +8,21 @@ order: 1
 
 Rustipo currently centers on a small CLI surface that covers the full authoring loop.
 
+## Config-Driven Extras
+
+### Analytics
+
+Rustipo supports opt-in Plausible analytics from `config.toml`:
+
+```toml
+[site.analytics.plausible]
+domain = "docs.example.com"
+# Optional for self-hosted Plausible:
+# script_src = "https://stats.example.com/js/script.js"
+```
+
+Built-in themes render that snippet automatically through their shared head partials.
+
 ## Core Commands
 
 ### `rustipo new <site-name>`

src/commands/new/scaffold.rs

@@ -107,6 +107,9 @@ pub const HEAD_ASSETS_PARTIAL: &str = r#"{% if site_favicon_svg %}<link rel="ico
   {{ site_font_faces_css | safe }}
 </style>
 {% endif %}
+{% if site_analytics_head_html %}
+{{ site_analytics_head_html | safe }}
+{% endif %}
 <link rel="stylesheet" href="{{ asset_url(path='style.css') }}?v={{ site_asset_version }}" />
 <link rel="stylesheet" href="{{ asset_url(path='palette.css') }}?v={{ site_asset_version }}" />
 {% if site_has_custom_css %}