✨ Add Blowfish discovery and freshness path

exampleSite/config/_default/menus.en.toml

@@ -16,36 +16,19 @@
   weight = 10
 
 [[main]]
-  name = "Shortcodes"
-  pageRef = "docs/shortcodes"
-  weight = 15
-
-[[main]]
-  name = "Examples"
+  name = "Guides"
+  pageRef = "guides"
   weight = 20
 
-[[main]]
-  name = "Samples"
-  parent = "Examples"
-  pageRef = "samples"
-  weight = 16
-
 [[main]]
   name = "Showcase"
-  parent = "Examples"
   pageRef = "examples"
   weight = 30
 
-[[main]]
-  name = "Recipes"
-  parent = "Examples"
-  pageRef = "guides"
-  weight = 40
-
 [[main]]
   name = "Users"
   pageRef = "users"
-  weight = 90
+  weight = 40
 
 [[main]]
   identifier = "merch"

exampleSite/content/_index.md

@@ -1,6 +1,7 @@
 ---
 title: "Build a site that feels unmistakably yours."
 description: "A modern, flexible Hugo theme for blogs, documentation, portfolios, and more."
+lastmod: 2026-08-30
 heroLead: "Blowfish gives you expressive layouts, thoughtful defaults, and practical content building blocks, so you can focus on the thing you want to say."
 heroButtons:
   - label: "Get started"
@@ -35,3 +36,7 @@ Explore real sites, community contributions, and patterns that hold up in produc
 Blowfish ships an agent skill that teaches Claude Code and other coding agents how to install, configure, and build with the theme.
 {{< /feature >}}
 {{< /feature-grid >}}
+
+{{< alert >}}
+**Blowfish v3.5 is available.** Start a new site with `npx blowfish-tools new <site>` or [upgrade an existing site]({{< ref "guides/202608-upgrade-to-blowfish-v3" >}}).
+{{< /alert >}}

exampleSite/content/docs/welcome/index.md

@@ -3,16 +3,21 @@ title: "Welcome to Blowfish"
 featureimage: "images/v3/welcome.png"
 weight: 1
 draft: false
-description: "Discover what's new in Blowfish version 2.0."
+description: "Start building with the current version of Blowfish, a modern Hugo theme for blogs, documentation, portfolios, and more."
+lastmod: 2026-08-30
 tags: ["new", "docs"]
 series: ["Documentation"]
 series_order: 1
 ---
 
 {{< lead >}}
-Blowfish is packed with tons of features.
+Blowfish 3 is a modern Hugo theme for blogs, documentation, portfolios, and more.
 {{< /lead >}}
 
+{{< alert >}}
+Looking for the fastest path to a new site? Run `npx blowfish-tools new <site>`, then follow the [installation guide]({{< ref "docs/installation" >}}). The sections below document the major features introduced with Blowfish 2, which remain available in the current release.
+{{< /alert >}}
+
 The original aim of Blowfish was to develop a theme that was simple and lightweight. The theme is a fork of <a target="_blank" href="https://github.com/nunocoracao/congo">Congo</a> and expands its initial vision.
 
 ## Tailwind CSS 3.0

exampleSite/content/guides/202608-upgrade-to-blowfish-v3/index.md

@@ -0,0 +1,48 @@
+---
+title: "Upgrade an existing Hugo site to Blowfish 3"
+description: "Move an existing Blowfish site to version 3 with no breaking configuration changes."
+date: 2026-08-30
+lastmod: 2026-08-30
+tags: ["blowfish", "hugo", "migration", "v3"]
+showauthor: false
+authors: ["nunocoracao"]
+---
+
+{{< lead >}}
+Blowfish 3 is backwards compatible. Existing sites can upgrade without rewriting their configuration or content.
+{{< /lead >}}
+
+## Before you upgrade
+
+Commit your current site and make sure your Hugo version is within the range declared by Blowfish. If you have custom files inside the theme directory, move them into your site's `assets/` or `layouts/` directories first so upgrades do not overwrite them.
+
+## Upgrade your installation
+
+### Hugo module
+
+Update the module path in `config/_default/module.toml` to include `/v3`, then refresh dependencies:
+
+```toml
+[[imports]]
+path = "github.com/nunocoracao/blowfish/v3"
+```
+
+```shell
+hugo mod get -u
+```
+
+### Git submodule
+
+```shell
+git submodule update --remote --merge
+```
+
+### Manual install
+
+Download the latest release, replace `themes/blowfish/`, and keep your site-level configuration in `config/_default/`.
+
+## Verify the result
+
+Run `hugo server`, check your homepage and a representative article, then deploy as usual. New Blowfish 3 features are opt-in, so your existing site should render as before.
+
+For a new site instead, use `npx blowfish-tools new <site>` and follow the [installation guide]({{< ref "docs/installation" >}}).

exampleSite/content/guides/_index.md

@@ -1,6 +1,7 @@
 ---
-title: "Recipes"
-description: "Recipes, guides, and tutorials for Blowfish"
+title: "Guides"
+description: "Practical guides for building, migrating, and publishing Hugo sites with Blowfish"
+lastmod: 2026-08-30
 
 cascade:
   showDate: false
@@ -9,11 +10,11 @@ cascade:
 ---
 
 {{< lead >}}
-Recipes, guides, and tutorials for Blowfish
+Practical guides for building, migrating, and publishing Hugo sites with Blowfish.
 {{< /lead >}}
 
 **Blowfish user?** To add your guide to this list, [check the template](/guides/template/).
 
-This section contains guides for a variety of scenarios on how to configure your theme. If you're new, check out the [Installation]({{< ref "docs/installation" >}}) guide to begin or visit the [Samples]({{< ref "samples" >}}) section to see what Blowfish can do.
+Start with [installation]({{< ref "docs/installation" >}}), upgrade an existing site to [Blowfish 3]({{< ref "guides/202608-upgrade-to-blowfish-v3" >}}), or browse the [Showcase]({{< ref "examples" >}}) for inspiration.
 
 ---