Skip to content

fix(docs.json): restore redirects for legacy docs URLs - #119

Merged
stephenyeargin merged 1 commit into
mainfrom
fix/legacy-docs-redirects
Oct 9, 2026
Merged

stephenyeargin merged 1 commit into
mainfrom
fix/legacy-docs-redirects

Conversation

@stephenyeargin

@stephenyeargin stephenyeargin commented Oct 9, 2026 •

Copy link
Copy Markdown
Member

Problem

The MkDocs site (flox/floxdocs, archived) had a redirect_maps list in mkdocs.yml. It wasn't carried over in the Mintlify migration, so old docs URLs now 404 on flox.dev, for example:

  • /docs/reference/command-reference/flox-activate/ (all 23 command-reference pages)
  • /docs/cookbook/languages/rust/ (all 7 language guides)
  • /docs/cookbook/publish/catalog-store/, /docs/concepts/manifest/

The floxwebsite Netlify rules for these paths come after the /docs/* proxy, so they never fire. Mintlify is the only place that can catch them.

Changes

Adds a redirects array to docs.json:

  • The restored MkDocs map: reference/command-reference/* → man/* and cookbook/languages/* → languages/* (both wildcards), cookbook/publish/* → customer/*, and concepts/manifest → concepts/environments
  • Older pre-MkDocs paths that floxwebsite rules still point at: tutorials/projects, tutorials/custom-packages, tutorials/build-container-images, integrations/github-actions, cookbook/language-guides/*, */managed-environments, catalog, generations and environments
  • Removed commands: flox-update → man/flox-upgrade and flox-rollback → man/flox-generations-rollback
  • Specific rules come before the wildcards, because the first match wins

I left out pages with no current equivalent (stabilities, package-arguments, flox-plus-nix, validate-identical, flox-nix-config, direnv, flox-gh) instead of sending them to the docs home.

Sources are relative to the docs root, like navigation. Mintlify's built-in redirects keep the /docs prefix behind the flox.dev proxy (for example, /docs/tutorials/CUDA → /docs/tutorials/cuda).

Verification

  • mint validate passes
  • Every destination exists in the live sitemap
  • Locally under mint dev, the wildcards and specific-before-wildcard order resolve as expected (flox-activate → man/flox-activate, flox-rollback → man/flox-generations-rollback, cookbook/language-guides/python → languages/python)

After merge

  • curl -sI https://flox.dev/docs/reference/command-reference/flox-activate/ returns a 308 to /docs/man/flox-activate
  • A floxwebsite follow-up removes the unreachable /docs/* Netlify rules and points the root-level legacy rules straight at their final pages

🤖 Generated with Claude Code

The MkDocs site's redirect_maps (mkdocs.yml) weren't carried over in
the Mintlify migration, so old docs URLs now 404. floxwebsite's Netlify
rules for these paths sit behind the /docs/* proxy and never fire.

Restore the MkDocs map (command-reference -> man, cookbook/languages ->
languages, cookbook/publish -> customer, concepts/manifest) and add
mappings for pre-MkDocs paths that floxwebsite still links to.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@mintlify

mintlify Bot commented Oct 9, 2026 •

Copy link
Copy Markdown

Preview deployment for your docs. Learn more about Mintlify Previews.

Project Status Preview Updated
flox 🟢 Ready View Preview Oct 9, 2026, 3:27 PM

💡 Tip: Enable Automations to automatically generate PRs for you.

@stephenyeargin
stephenyeargin added this pull request to the merge queue Oct 9, 2026
Merged via the queue into main with commit 279fc3c Oct 9, 2026
6 checks passed
@stephenyeargin
stephenyeargin deleted the fix/legacy-docs-redirects branch October 9, 2026 16:14

This branch was successfully deployed

1 active deployment
staging — fa85675b Deployed Oct 9, 2026 by mintlify[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants