[3.x] Support versioned documentation pages

[emmadesilva]

Would be great if we on the framework level could support this now

[emmadesilva]

ChatGPT Deep Research

Native Versioned Documentation in HydePHP v3

Executive summary

This report treats “HydePHP v3” as a forward-looking design target built on Hyde’s currently public architecture, because Hyde’s public documentation currently labels 2.x as the current docs line and 1.x as old, and the latest public GitHub release visible on the core repository is v2.0.0. Hyde’s public positioning is also unusually clear: it is a content-first static site builder that aims to let authors write Markdown and Blade with as little ceremony as possible, while still being extensible for advanced use cases. Any native versioning design that feels “un-Hyde” will probably fail even if it is technically elegant. citeturn30search0turn1view0turn40search8turn29search1

The current Hyde architecture is well suited to native versioned documentation, but only if versioning is made a first-class build concern, not just a theme or plugin flourish. Hyde already models pages as classes with static source and output directories, derives route keys from page identity, auto-discovers content on kernel boot, generates documentation search as JSON, and exposes a rebuild command for a single source file. HydePHP.com’s present workaround proves the concept, but it does so by duplicating page classes, filtering menus by exact page class, and generating a separate in-memory search page for each docs version. That works, but it encodes version semantics in class names and folder strings, not in a coherent version model. citeturn7search0turn5view0turn30search7turn39search0turn14view1turn14view4turn14view7turn14view8turn37view0

The strongest fit for Hyde v3 is a hybrid design: a native VersionRegistry in core, a first-class VersionedDocumentationPage or equivalent version-aware projection, filesystem-first authoring by default, optional front-matter overrides for advanced cases, per-version menus, per-version search shards, and redirect/canonical/SEO policies centralised in core. This is more opinionated than a pure plugin API, but it aligns much better with Hyde’s current class-based page system and with established patterns from Docusaurus, Read the Docs, MkDocs plus mike, Hugo, and Jekyll. Docusaurus models versioned docs and sidebars explicitly; Read the Docs models default-version redirects and canonical URLs explicitly; MkDocs delegates deployment aliases and default-version redirects to mike; Hugo and Jekyll show the strengths of path-based routing plus front-matter overrides. Hyde should borrow from all of them, but keep the authoring experience simpler than any of them. citeturn26search0turn26search4turn26search10turn38search3turn38search1turn38search0turn27search0turn36search3turn36search0turn24search4turn26search6turn26search15

My recommendation is therefore: native core support, folder-first, metadata-aware, redirect-driven, and backward-compatible by default. Single-version _docs sites should continue to work unchanged. Versioned sites should opt into a docs.versions registry. HydePHP.com’s current workaround should migrate cleanly into the new system with compatibility shims for one major cycle. The result would be simpler for authors, safer for SEO, more reliable for menus and search, and cheaper to maintain than continuing to duplicate page classes and search pages per version. citeturn5view0turn14view1turn15view0turn14view7turn14view8turn28search0turn28search3

Assumptions and current baseline

The key assumption in this report is that Hyde v3 should preserve Hyde’s existing architectural style rather than replace it. Today, Hyde’s boot process auto-discovers pages and routes through the kernel; page models expose static source and output directories; and HydePage instances carry identifiers, route keys, metadata and navigation data. The route key is load-bearing: Hyde explicitly documents that it determines both the route identity and the output file path. DocumentationPage is not a generic “docs entry” record with arbitrary metadata; it is a concrete page model with _docs as source, docs as output, and a docs layout template. citeturn30search7turn7search0turn6search1turn5view0turn3view2

That baseline matters because Hyde’s current design is closer to “typed page models + automatic discovery” than to a content graph built purely from front matter. Hyde registers page classes and their source/output directories centrally, and documentation pages can also flatten nested source paths to basename-based routes depending on configuration. In other words, Hyde already treats “what kind of page is this?” and “where does it live?” as first-order questions. Native versioning should therefore extend those concepts instead of trying to route around them. citeturn3view2turn7search0turn5view0

The menu and search baselines are equally important. Hyde has two built-in menu types—the main navigation menu and the documentation sidebar—which share a base navigation abstraction. The docs sidebar already has version-adjacent behaviour such as automatic grouping and configurable ordering. Search is likewise already a docs-specific build feature: Hyde documents a generated JSON search index, a full-page search route, a modal search interface, and a dedicated build:search command; in v2, the search page moved into an InMemoryPage, which means it is now part of the route graph rather than a purely post-build artefact. citeturn31search1turn23search9turn40search4turn23search2turn30search4turn39search0

HydePHP.com’s workaround is instructive because it is not merely cosmetic. Its MultiVersionDocsExtension returns page classes from configuration, defaulting to the core DocumentationPage for 2.x and a custom v1DocumentationPage for 1.x. The custom v1DocumentationPage subclasses the standard docs page, but hard-codes _docs/1.x as source and docs/1.x as output, including its own route logic and version-specific edit-link base. A custom navigation generator then filters routes by exact page class, and separate in-memory search pages write docs/1.x/search.json and docs/2.x/search.json. citeturn14view1turn15view0turn14view4turn14view7turn14view8

That workaround proves three things. First, Hyde’s extension and in-memory page systems are already flexible enough to model versioned docs. Secondly, separate menus and separate search indexes are both feasible and already running in production on HydePHP.com. Thirdly, the current implementation is brittle in exactly the places Hyde v3 should fix: version identity is encoded in duplicated classes, menu and search scoping rely on exact-class equality checks, and the search generator flattens entries to the basename of the identifier, which mirrors the current flattened docs routing but makes the design dependent on version-specific route prefixes to avoid collisions. Those are manageable workarounds for a site repo; they are not ideal primitives for a framework feature. citeturn14view4turn37view0turn5view0

flowchart LR
    A[Source files] --> B[Page discovery]
    B --> C[Typed page models]
    C --> D[Routes]
    C --> E[Navigation]
    C --> F[Search index]

    subgraph Current HydePHP.com hack
      G[_docs/1.x] --> H[v1DocumentationPage]
      I[_docs] --> J[DocumentationPage]
      H --> K[Class-filtered sidebar]
      J --> K
      H --> L[docs/1.x/search.json]
      J --> M[docs/2.x/search.json]
    end

Loading

Design requirements

A native Hyde v3 solution needs to satisfy more than “put the version in the URL”. It needs to preserve Hyde’s content-first authoring model, fit typed page discovery, support separate docs sidebars, generate search in a way that scales past one version, and remain understandable to users who never read framework internals. Hyde’s current docs and CLI already set the usability bar: authors can scaffold docs pages with make:page --docs, rebuild a single file with rebuild, list routes, and configure docs and navigation separately. Native versioning should feel like a natural extension of those workflows rather than a parallel subsystem. citeturn40search8turn39search0turn40search2

The functional requirements are straightforward but non-trivial in combination. Hyde v3 needs: separate menus per version; separate search indexes per version, plus an optional combined index with version facets; deterministic per-version routing; version-aware canonical URLs and redirect rules; optional version-scoped assets for frozen or divergent docs UX; a migration path from HydePHP.com’s duplicated-class workaround; route-collision detection compatible with Hyde’s existing flattened docs output mode; and build strategies that do not turn a rebuild of one file into a full rebuild of every version. Hyde’s current release notes already show that search pages, in-memory routes, grouped progress, Vite asset builds, asset caching and cache busting are active parts of the current design surface, so versioning should hook into those rather than bypass them. citeturn5view0turn39search0turn32search0turn30search4

Comparator systems sharpen these requirements. Docusaurus stores version content and version sidebars explicitly and distinguishes between current, latest and historical versions in routing. MkDocs Material delegates multi-version deployment to mike, which makes version subdirectories, aliases such as latest, a default-version redirect, and same-page switching part of the model. Read the Docs treats root redirects, canonical URLs and page redirects as first-class hosting features. Hugo exposes file-path-driven URL management plus aliases, while Jekyll combines collections with front-matter defaults and custom permalinks. Sphinx itself is highly theme- and template-driven, with version UI often supplied by hosting or extension layers rather than the core page model. Hyde should take from each of these what matches its philosophy: strong build-time structure, but without turning authors into release engineers. citeturn26search0turn26search4turn27search0turn38search3turn38search1turn38search0turn36search3turn36search0turn24search4turn26search6turn25search1turn25search0

SEO requirements must also be explicit. Google recommends canonical URLs for duplicate or near-duplicate pages and treats redirects as signals of canonical targets; Read the Docs likewise centralises canonical URLs and default-version redirects for versioned documentation. At the same time, Google’s hreflang guidance is for localised variants, not for software-version variants. So Hyde v3 should not try to model version relations as hreflang; instead it should support self-canonical version pages, explicit default-version redirects, and optional noindex,follow on hidden or end-of-life versions where maintainers want traffic consolidated on supported branches. citeturn28search0turn28search3turn28search5turn28search2turn38search1turn38search3turn38search6

flowchart TD
    V[Version registry] --> R[Route resolver]
    V --> S[Sidebar resolver]
    V --> X[Search shard builder]
    V --> A[Asset namespace resolver]
    R --> U[Canonical + redirects]
    X --> G[Per-version JSON]
    X --> H[Optional global faceted JSON]

Loading

Evaluation of design options

First-class VersionedDocumentationPage type with built-in metadata. This is the cleanest direct extension of Hyde’s existing page-type model. Hyde already treats pages as typed classes with source/output directories, templates and route keys, and HydePHP.com already shows that one duplicated subclass per version is enough to make multi-version docs work. Making versioning first-class would replace duplicated subclasses with a structured version object and a single version-aware page class or page family. This approach also aligns with Docusaurus’s explicit modelling of versioned docs and versioned sidebars. Its biggest strengths are clarity, predictable routing, and the ability to centralise menu/search/SEO policy in one place. Its main cost is core complexity: Hyde would need version discovery, version validation, route policy, menu scoping, search sharding and migration tooling in the framework itself. On balance, that is a good trade for a feature HydePHP.com is already effectively maintaining in userland. citeturn7search0turn5view0turn14view1turn15view0turn26search0turn26search4

Plugin or extension API for versioning. Hyde already supports extensions and boot callbacks, so leaving versioning to a plugin is entirely feasible. Sphinx is the classic example of a documentation system where theming, templates and extension layers do much of the heavy lifting, and MkDocs Material plus mike likewise demonstrates that multi-version deployment can be externalised. The problem is not feasibility, but cohesion. In Hyde, version-aware menus, routes, search indexes, redirect pages and canonical URLs are not isolated add-ons; they are all generated during the build. A plugin can certainly do this—but every plugin author must then solve the same menu/search/SEO problems again, and migration between plugins becomes painful. A plugin-first design also leaves users exposed to inconsistent canonical and redirect policies, which matters far more for documentation than for a generic theme toggle. This is the lowest-risk short-term option for core maintainers, but the highest long-term ecosystem cost. citeturn29search8turn30search7turn25search1turn25search0turn24search2turn27search0

Virtual page collections generated at build time. In this model, Hyde would keep a simpler underlying docs page record, then generate per-version “projections” during discovery or build, with route/menu/search outputs derived from those projections. This fits Hyde’s growing use of InMemoryPage and build-time generation, and it is attractive if Hyde wants optional combined search with version facets or front-matter-driven multi-version pages later. It is also conceptually close to how Jekyll collections and Hugo front matter can reshape output independently from source location. The disadvantage is developer transparency: debugging becomes harder when the page a user edits is not the same object as the routed page being built. For a framework that pitches simplicity and discoverability, that additional indirection should be used sparingly. Virtual collections are excellent as an internal implementation detail; they are weaker as the primary mental model exposed to authors. citeturn30search4turn39search0turn36search3turn24search4turn26search6

Filesystem-based versioning with folders per version. This is the most Hyde-like authoring model. Hyde already maps source directories to page classes, Docusaurus stores versioned docs in version-specific folders, and Hugo’s default URL behaviour follows the content path unless overridden. Folder-first versioning gives separate menus almost for free, keeps per-version search sharding simple, matches user expectations on disk, and works very naturally with Hyde’s existing rebuild <path> command because the changed file path already encodes the version shard that must be invalidated. The main downside is duplication: unchanged pages often get copied between versions, which can increase repository noise. Even so, this is the simplest default and the least magical model for most Hyde users. citeturn3view2turn5view0turn39search0turn26search0turn36search3

Front-matter version tags in a shared docs tree. This is more flexible and can reduce duplication, especially when the same page applies to multiple supported versions. Jekyll’s front-matter defaults and Hugo’s front matter demonstrate the power of metadata-driven output control. But in Hyde, version tags alone would complicate almost every secondary system: menu generation would have to group by metadata rather than path; search would need projection logic; route collisions would be easier to create; and authoring would be noisier because every page would need explicit version declarations or inheritance rules. Front matter is an excellent override mechanism, but a poor default for Hyde’s core version identity. It fits advanced repositories better than the average Hyde documentation site. citeturn26search15turn36search6turn36search3turn24search4

Hybrid approaches. The strongest design is a hybrid: filesystem-first version roots for normal authoring, a native version registry for routing/search/menu/SEO policies, and optional front-matter directives for exceptional cases such as cross-version shared pages, custom aliases, or “current-only” navigation labels. This mirrors the best parts of Docusaurus, MkDocs plus mike, and Read the Docs: explicit version identity, stable versioned URLs, configurable default-version redirects, and optional aliasing without duplicate canonical pages. For Hyde specifically, a hybrid also lets core preserve the clean _docs experience for single-version sites while unlocking advanced multi-version sites without requiring duplicated subclasses or per-version search-page boilerplate. It has the highest one-time implementation cost, but the lowest long-run conceptual debt. citeturn26search0turn27search0turn38search3turn38search1turn14view1turn15view0

approach	routing	menus	search	build perf	migration difficulty	developer ergonomics	SEO
first-class page type	explicit version-aware route rules in core	native per-version sidebars	per-version shards, optional global index	good with shard caching	medium	very good	strong, consistent
plugin or extension API	plugin-defined, core unaware	plugin-defined	plugin-defined	variable	low to medium	mixed	inconsistent unless plugin is excellent
virtual page collections	projected routes from source pages	generated from projections	strongest support for faceting	medium	medium to high	good after setup, harder to debug	strong if centralised
filesystem-based versioning	path-driven, explicit	naturally separate	naturally separate	very good	low	best for most users	strong
front-matter version tags	metadata-driven, collision-prone if overused	metadata queries required	flexible, but more logic	medium	medium	powerful but noisy	easy to misconfigure
hybrid recommended	registry-driven, folder-first, override-capable	native per-version plus override hooks	per-version by default, global optional	very good	medium	very good	strongest overall

The table above is a synthesis of Hyde’s typed page/discovery model, HydePHP.com’s current workaround, and the explicit version-routing patterns visible in Docusaurus, MkDocs plus mike, Read the Docs, Hugo and Jekyll. citeturn7search0turn14view1turn15view0turn26search0turn27search0turn38search3turn36search3turn26search6

Recommended architecture and integration sketches

The recommended design is a core-native hybrid with five principles. First, version identity should live in a registry, not in PHP class names. Secondly, authors should default to folders per version because that matches Hyde’s source-directory model. Thirdly, routing, menus, search, redirects and canonical URLs should all read from the same version registry. Fourthly, per-version assets should be opt-in, with shared assets remaining the default. Fifthly, single-version sites should remain effectively unchanged unless they opt in. This keeps Hyde’s content-first ergonomics intact while solving the real production problems already visible on HydePHP.com. citeturn40search8turn3view2turn14view1turn15view0turn29search0

A suitable registry model would look something like this in user configuration:

docs:
  default_version: "3.x"
  versions:
    "3.x":
      source: "_docs/3.x"
      output: "docs/3.x"
      status: "current"
      aliases: ["latest"]
      canonical: "self"
    "2.x":
      source: "_docs/2.x"
      output: "docs/2.x"
      status: "supported"
      canonical: "self"
    "1.x":
      source: "_docs/1.x"
      output: "docs/1.x"
      status: "legacy"
      canonical: "self"
      robots: "noindex,follow"

This configuration deliberately prefers explicit versioned paths as canonical URLs. That is the safest default for versioned documentation because it avoids building duplicate HTML under both /docs/foo and /docs/3.x/foo. The root docs path and any “latest” aliases should be generated as redirects, not as second canonical pages. That matches Read the Docs’ default-version redirect model and Google’s guidance that redirects and canonical tags should consolidate equivalent URLs rather than leave duplicates crawling around. citeturn38search3turn38search0turn38search1turn28search0turn28search3

For page modelling, Hyde does not strictly need to expose a brand-new public class if the underlying projection system is clean enough, but it should expose a version-aware interface. That gives templates, search builders and menu resolvers something stable to depend on, instead of today’s exact-class comparisons.

<?php

interface VersionAwarePage
{
    public function version(): DocsVersion;
    public function logicalIdentifier(): string;   // e.g. "installation/getting-started"
    public function versionedIdentifier(): string; // e.g. "2.x:installation/getting-started"
}

final readonly class DocsVersion
{
    public function __construct(
        public string $key,
        public string $label,
        public string $source,
        public string $output,
        public string $status = 'supported',
        public array $aliases = [],
        public string $canonicalPolicy = 'self',
        public ?string $robots = null,
    ) {}
}

class VersionedDocumentationPage extends DocumentationPage implements VersionAwarePage
{
    public function __construct(
        string $identifier,
        protected DocsVersion $version,
        FrontMatter|array $matter = [],
    ) {
        parent::__construct($identifier, $matter);
    }

    public function version(): DocsVersion
    {
        return $this->version;
    }

    public function logicalIdentifier(): string
    {
        return $this->identifier;
    }

    public function versionedIdentifier(): string
    {
        return "{$this->version->key}:{$this->identifier}";
    }

    public function getRouteKey(): string
    {
        $slug = Config::getBool('docs.flattened_output_paths', true)
            ? basename($this->identifier)
            : $this->identifier;

        return "{$this->version->output}/{$slug}";
    }
}

The core build hook should register all versioned doc collections during kernel boot so that route discovery, menu generation and route listing continue to work naturally. Hyde already exposes kernel boot hooks and extension registration, so this fits existing extension mechanics rather than inventing a second lifecycle. citeturn29search8turn30search7

<?php

Hyde::booting(function (HydeKernel $hyde) {
    $registry = app(DocsVersionRegistry::class)->discover();

    foreach ($registry->all() as $version) {
        $hyde->registerPageFactory(
            pageClass: VersionedDocumentationPage::class,
            sourceDirectory: $version->source,
            outputDirectory: $version->output,
            context: ['version' => $version],
        );
    }

    Hyde::share('docsVersions', $registry->publicIndex());
    Hyde::share('defaultDocsVersion', $registry->default());
});

Search should remain plain-text JSON, as HydePHP.com already does through ConvertsMarkdownToPlainText, because that keeps the index lightweight and reduces XSS exposure in search UIs. The default search mode should be per-version shards, matching today’s HydePHP.com deployment, with an optional combined index for global “search across versions” UX. The combined index should add version, status and logical_identifier fields so that the UI can facet cleanly without guessing from path strings. Hyde already has a docs search feature, an in-memory search page model, and a build:search command, so this is an extension of existing behaviour rather than an alien subsystem. citeturn37view0turn14view7turn14view8turn23search2turn30search4turn39search0

<?php

final class VersionedDocsSearchIndexer
{
    public function buildShard(DocsVersion $version): array
    {
        return VersionedDocumentationPageCollection::for($version)
            ->reject(fn ($page) => $page->matter('search') === false)
            ->map(fn ($page) => [
                'version'            => $version->key,
                'status'             => $version->status,
                'slug'               => basename($page->getIdentifier()),
                'logical_identifier' => $page->logicalIdentifier(),
                'title'              => $page->title,
                'content'            => $this->plainText($page),
                'destination'        => Hyde::formatLink($page->getOutputPath()),
            ])
            ->values()
            ->all();
    }

    public function buildManifest(DocsVersionRegistry $registry): array
    {
        return $registry->all()->map(fn ($v) => [
            'version' => $v->key,
            'status'  => $v->status,
            'index'   => Hyde::url("{$v->output}/search.json"),
        ])->all();
    }
}

Menus should be resolved by version metadata, not by page class equality. HydePHP.com’s current VersionAwareNavigationMenuGenerator works by filtering routes where route->getPage()::class === $this->pageClass; native support should instead ask for the active docs version and build that version’s sidebar from version-aware pages. Docusaurus’s versioned sidebars are the closest conceptual analogue here, even though Hyde’s implementation style is different. citeturn14view4turn26search4

<?php

final class VersionedDocumentationSidebarBuilder
{
    public function build(DocsVersion $version): DocumentationSidebar
    {
        $items = VersionedDocumentationPage::allFor($version)
            ->filter(fn (VersionAwarePage $page) => $page->showInNavigation())
            ->sortBy(fn (VersionAwarePage $page) => [
                $page->navigationMenuGroup() ?? '',
                $page->navigationMenuPriority(),
                $page->navigationMenuLabel(),
            ])
            ->pipe(fn ($pages) => $this->groupByDirectoryOrFrontMatter($pages, $version));

        return new DocumentationSidebar($items);
    }
}

On build performance, Hyde should treat each version as a cache shard. The cache key for rendered docs should include source path, version key, flattened-route policy, search config hash and relevant template hashes. A rebuild of _docs/2.x/installation.md should invalidate that page, the 2.x sidebar, the 2.x search shard, and any default-version redirect pointing at it—but not every docs version. This dovetails with Hyde’s existing rebuild <path> command and with v2’s broader performance work on in-memory pages, grouped progress bars, asset caching and CRC32-based cache busting. citeturn39search0turn32search0

On assets, the right default is shared assets, versioned only when necessary. Hyde’s current asset model is site-wide and already emphasises Vite integration, “only compile when needed” behaviour, and cache-busted media assets. Most versioned documentation sites do not need a full duplicate CSS/JS bundle per version. The better approach is to keep app.css and common docs JS shared by default, while allowing optional version-scoped docs assets such as _media/docs/1.x/search.js if a legacy version needs frozen behaviour. This keeps builds fast and avoids needless cache fragmentation. citeturn29search0turn32search0

Developer ergonomics should be equally opinionated. Hyde should add version-aware helpers and commands rather than expect users to assemble them from lower-level APIs. Examples that fit Hyde’s current CLI idiom would include make:page --docs --version=3.x, build:search --version=2.x, docs:versions, docs:freeze 3.x, and docs:redirects. In Blade, maintainers should get helpers such as docs_version(), docs_versions(), docs_sidebar(), version_switch_url('2.x'), and <x-hyde::docs.version-switcher />. Hyde already has a strong command-line and component story; versioning should join that rather than live in custom site code. citeturn39search0turn29search0

Migration, compatibility and operational implications

The migration path from HydePHP.com’s current workaround can be made surprisingly gentle. The framework should first introduce the new core version registry and native docs version builder without removing the existing DocumentationPage. If a project has only _docs and no docs.versions config, Hyde should behave exactly as it does today. If a project opts into docs.versions, core should discover version roots and generate version-aware routes, menus and search shards automatically. Existing custom subclasses such as v1DocumentationPage can then become thin compatibility shims that map to the native version registry for one major cycle before removal. citeturn5view0turn15view0turn14view1

A practical migration from the HydePHP.com hack would look like this:

1. Add docs.versions config entries for current and legacy versions, using the current _docs/1.x and docs/1.x conventions as the initial source/output mapping.
2. Replace the custom MultiVersionDocsExtension with core config, keeping the old extension class as a no-op shim during transition.
3. Replace v1DocumentationPage with native version-aware docs pages, preserving existing output paths so that inbound links do not break.
4. Replace bespoke v1DocumentationSearchIndex and v2DocumentationSearchIndex pages with core-generated per-version search shards and an optional global manifest.
5. Replace VersionAwareNavigationMenuGenerator with the native per-version sidebar resolver.
6. Run route:list, build, build:search, build:sitemap and representative rebuild operations to diff old and new output before cutting over. Hyde’s current CLI already exposes the key commands needed for this validation loop. citeturn14view1turn15view0turn14view7turn14view8turn14view4turn39search0

Backward compatibility should focus on output stability, not API nostalgia. The safest rule is: keep current versioned URLs intact, keep the old search file paths as redirects or compatibility aliases where possible, and preserve front-matter semantics unless they conflict with the new version registry. That means existing docs/1.x/* and docs/2.x/* routes should survive unchanged, while any new root or latest aliases should be emitted as redirects instead of duplicate pages. Hyde’s existing docs search path model and current HydePHP.com search shard paths make this especially straightforward. citeturn23search2turn14view7turn14view8turn38search3turn28search3

SEO and security need central validation rules. Hyde should validate version keys against a conservative pattern, refuse duplicate route keys across version projections, and warn loudly when flattened docs output would create collisions inside one version. That last point matters because Hyde’s current DocumentationPage may flatten nested identifiers to basenames when docs.flattened_output_paths is enabled. Version prefixes solve collisions between versions, but not collisions within a version. A native validator should therefore surface these problems before build output is written. citeturn5view0turn39search0turn40search7

Canonical and robots policies should likewise be owned by core. Version pages that are materially different should normally be self-canonical. Default-version landers should redirect, not duplicate. Hidden or end-of-life versions should be able to opt into noindex,follow. And hreflang should not be auto-generated for version relations, because Google treats hreflang as a signal for localised alternatives, not software-version alternatives. These rules are simple, widely understood, and much safer than leaving each theme or plugin to improvise. citeturn28search0turn28search2turn28search5turn38search1turn38search3

The maintenance-cost conclusion is therefore quite firm. A plugin-only answer is cheapest for the framework in the next release but most expensive for the ecosystem over time. A front-matter-first answer is flexible but too subtle for Hyde’s default posture. A filesystem-first first-class core design, implemented as a hybrid with optional front-matter overrides and optional global search faceting, is the best long-term fit. It matches Hyde’s current page-type architecture, absorbs HydePHP.com’s proven workaround, borrows the right lessons from Docusaurus, Read the Docs, MkDocs, Hugo and Jekyll, and gives Hyde v3 a native versioned documentation story that feels consistent with its design philosophy rather than bolted on after the fact. citeturn7search0turn14view1turn15view0turn26search0turn27search0turn38search3turn36search3turn26search6turn40search8

[emmadesilva]

Implemented in #2516