Skip to content

fix(v6): redeploy v6 documentation #4567

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
brandyscarney merged 3 commits into from
Jul 1, 2026
Merged

fix(v6): redeploy v6 documentation #4567

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ce9a820
fix(v6): redeploy v6 documentation
brandyscarney Jul 1, 2026
51bf8e4
fix(v6): archive v6
brandyscarney Jul 1, 2026
25ed085
docs(contributing): added note on archiving docs versions
brandyscarney Jul 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 28 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@ Thanks for your interest in contributing to Ionic's documentation! :tada: Check
- [Reporting Issues](#reporting-issues)
- [Pull Request Guidelines](#pull-request-guidelines)
- [Deploying](#deploying)
- [Archiving a Version](#archiving-a-version)
- [License](#license)

---
Expand Down Expand Up @@ -175,6 +176,33 @@ When submitting pull requests, please keep the scope of your change contained to

The Ionic documentation's `main` branch is deployed automatically and separately from the [Ionic site](https://github.com/ionic-team/ionic-site) itself. The Ionic site then uses a proxy for paths under `/docs` to request the deployed documentation.

### Archiving a Version

Archived versions are served from a frozen Vercel deployment instead of being rebuilt on every `main` deploy, which keeps build times and memory usage low. Two files control this:

- [`versions.json`](./versions.json): lists the versions Docusaurus rebuilds on every deploy.
- [`versionsArchived.json`](./versionsArchived.json): maps each archived version to the frozen deployment URL the version picker links to.

The archived URL has to point at a build that _included_ the version, so you build it first, then move it to `versionsArchived.json`:

1. **Build the version.** Make sure it is in `versions.json`. If you are refreshing an already-archived version, move it out of `versionsArchived.json` and back into `versions.json`. Commit, push and let Vercel deploy.
2. **Promote the deployment.** In the Vercel dashboard, open that deployment and **Promote to Production** so it does not get cleaned up. Wait for the build to finish before pushing again, or it may get canceled.
3. **Copy its URL.** Use the deployment's unique `ionic-docs-<hash>-ionic1.vercel.app` URL, not the branch or production alias.
4. **Archive it.** Remove the version from `versions.json`, then add it to `versionsArchived.json` with `/docs/<version>` appended and no trailing slash (a trailing slash causes a brief 404 flash):

```json
{
"v6": "https://ionic-docs-<hash>-ionic1.vercel.app/docs/v6"
}
```

5. **Open a PR.** Once merged, the version picker links to the archive and `main` stops building that version.

Removed versions keep their `versioned_docs/` and `versioned_sidebars/` content, so they can be rebuilt anytime by adding them back to `versions.json`.

> [!NOTE]
> Ionic v3 and v4 use other build tools and are not managed here.

---

## License
Expand Down
2 changes: 1 addition & 1 deletion versionsArchived.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
{
"v6": "https://ionic-docs-fo03f34h5-ionic1.vercel.app/docs/v6",
"v6": "https://ionic-docs-lq0if04rc-ionic1.vercel.app/docs/v6",
"v5": "https://ionic-docs-5utg8ms4c-ionic1.vercel.app/docs/v5"
}
Loading