Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
13 changes: 6 additions & 7 deletions .cursor/BUGBOT.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,13 +39,12 @@ pure noise:

The build catches broken links _inside the site_. It catches none of this:

- **A page was renamed, moved, or deleted without a `301` in `netlify.toml`.**
This is the single highest-cost miss in the repo: inbound links and bookmarks
die and nothing fails. Check the PR's renames/deletions under `docs/` against
new `[[redirects]]` entries. (`netlify.toml` is the live redirect list, ~200
entries; `vercel.json` holds only a handful of legacy ones.) Each new rule
also needs a matching line in `static/_redirects`, which Cloudflare previews
read.
- **A page was renamed, moved, or deleted without a `301` in
`static/_redirects`.** This is the single highest-cost miss in the repo:
inbound links and bookmarks die and nothing fails. Check the PR's
renames/deletions under `docs/` against new lines in `static/_redirects`, the
live redirect list (~200 entries). Exact paths belong above the wildcard (`*`)
rules at the end of the file.
- **URLs the build never checks.** Docusaurus only validates links it can see as
internal markdown links. Verify by hand that these resolve to a real page:
- absolute `https://docs.cypress.io/...` URLs (treated as external, unchecked)
Expand Down
8 changes: 4 additions & 4 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -316,9 +316,9 @@ jobs:
name: Cloudflare preview
needs: build
# Uploads this pull request's build as a Cloudflare Worker Preview and posts
# a `cloudflare/preview` commit status whose Details link opens it, the way
# Netlify's deploy-preview status does. Cloudflare's own Workers Builds
# check links to its dashboard instead, which needs a Cloudflare login.
# a `cloudflare/preview` commit status whose Details link opens it.
# Cloudflare's own Workers Builds check links to its dashboard instead,
# which needs a Cloudflare login.
#
# Same condition as `e2e`, minus pushes: it needs the Cloudflare secrets,
# which GitHub withholds from a pull request opened from a fork. This job
Expand All @@ -340,7 +340,7 @@ jobs:
# is the temporary merge commit, which the pull request never shows.
HEAD_SHA: ${{ github.event.pull_request.head.sha }}
# `pr-<number>` keeps one stable, short URL per pull request across
# pushes, like Netlify's `deploy-preview-<number>`.
# pushes.
PREVIEW_NAME: pr-${{ github.event.pull_request.number }}
steps:
# Until both secrets exist, skip with a notice rather than fail the run.
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/tag-docs-release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ on:
type: boolean
default: false

# Nothing ships through this workflow. Docs deploy via Netlify/Vercel and CI
# Nothing ships through this workflow. Docs deploy via Cloudflare and CI
# runs in ci.yml, and this runs on push to main after the merge, so it is not
# a pull request check. A failure here means a release is missing its tag and
# nothing else — it cannot block a merge or a deploy. It still opens an issue so
Expand Down
1 change: 0 additions & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,6 @@ cypress/videos
# Generated files
.docusaurus
.cache-loader
.vercel

.nuxt
themes
Expand Down
5 changes: 2 additions & 3 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -118,9 +118,8 @@ Each rule is a hard convention. See the linked section for the how and why.
- Order with `sidebar_position` and `_category_.json`, not `sidebars.js`. Without
a `sidebar_position`, pages sort alphabetically; if sibling files don't define
one, match them and skip it rather than introducing positions.
- Moving/renaming/deleting a page **requires** a `301` in both `netlify.toml`
and `static/_redirects` (Netlify serves production while Cloudflare builds
previews), plus updating in-repo links to it.
- Moving/renaming/deleting a page **requires** a `301` in `static/_redirects`,
plus updating in-repo links to it.

**Authoring** — [components](./AGENTS_REFERENCE.md#mdx-components),
[partials](./AGENTS_REFERENCE.md#partials),
Expand Down
28 changes: 11 additions & 17 deletions AGENTS_REFERENCE.md
Original file line number Diff line number Diff line change
Expand Up @@ -84,23 +84,17 @@ Three files at the site root index all of that, and none is hand-maintained:
don't set a `sidebar_position`, leave it off your new page too and let it sort
alphabetically rather than introducing positions into a folder that doesn't use
them. Only add `sidebar_position` where the folder already relies on it.
- **Moving, renaming, or deleting a page requires a redirect.** Add a `301` entry
to `netlify.toml` (it already holds ~200) so existing bookmarks and inbound
links keep working:
```toml
[[redirects]]
from = "/old/path"
to = "/new/path"
status = 301
force = true
```
Add the same rule, at the same position, to `static/_redirects`, which
Cloudflare reads. Netlify serves production while hosting moves to
Cloudflare, so the two lists must match. Both hosts use the first rule that
matches a path:
- **Moving, renaming, or deleting a page requires a redirect.** Add a `301` line
to `static/_redirects` (it already holds ~200) so existing bookmarks and
inbound links keep working:
```text title="static/_redirects"
/old/path /new/path 301
```
Cloudflare applies an exact-path rule before any wildcard (`*`) rule, so add
exact paths above the wildcards at the end of the file. Avoid a new wildcard
that overlaps an existing one: Cloudflare doesn't reliably pick the first of
two overlapping wildcards (the comment above `/app/cloud/*` explains the one
case we have), so check any new wildcard on the pull request's preview.
Then update any in-repo links to the old path, since `onBrokenLinks: throw`
will otherwise fail the build.

Expand Down Expand Up @@ -219,9 +213,9 @@ Guidance, not arithmetic:
This applies to headings you are writing. Renaming an existing heading costs two
published URLs, and neither is redirectable:

- **Its anchor.** A URL fragment never reaches the server, so `netlify.toml`
cannot redirect it the way it redirects a moved page. Inbound deep links land
on the page and fail to scroll.
- **Its anchor.** A URL fragment never reaches the server, so
`static/_redirects` cannot redirect it the way it redirects a moved page.
Inbound deep links land on the page and fail to scroll.
- **Its section `.md` file.** The LLM export publishes every `##` section at
`<page-route>/<h2-slug>.md`, so renaming an H2 moves that file and the old URL
404s. Agents and tools that fetched it lose the link.
Expand Down
21 changes: 9 additions & 12 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -225,18 +225,15 @@ open a pull request (PR) from your repo to the
PR. This will make it easier for the maintainers to make minor adjustments, to
help with tests or any other changes we may need.
![Allow edits from maintainers checkbox](https://user-images.githubusercontent.com/1271181/31393427-b3105d44-ada9-11e7-80f2-0dac51e3919e.png)
- All PRs against `main` will automatically create a deploy preview URL with
Netlify. The deploy preview can be accessed via the PR's
`netlify-cypress-docs/deploy-preview` status check:

![Netlify deploy preview status check](https://user-images.githubusercontent.com/11802078/113176533-36b79680-9212-11eb-8aec-898d0f5047df.png)

- All branches will automatically create a branch deploy preview. The branch
deploy previews do not appear as a GitHub status check like deploy previews.
You can view your branch's deploy preview by visiting
`https://$BRANCH_NAME--cypress-docs.netlify.app` where `$BRANCH_NAME` is your
git branch name. For example, if my branch was named `my-branch`, my branch
preview will be available at `https://my-branch--cypress-docs.netlify.app`.
- A PR opened from a branch in this repository gets a preview of the built
site, hosted on Cloudflare and updated on every push. Open it from the
**Details** link on the PR's `cloudflare/preview` status check, or visit
`https://pr-<number>-cypress-documentation.cypress-io.workers.dev`, where
`<number>` is the PR number.
- A PR opened from a fork doesn't get a preview, because building one needs
credentials that GitHub doesn't share with forks. To check your changes, run
`npm run build` and then `npm run serve`, and open
[http://localhost:3000](http://localhost:3000).

### Contributor License Agreement

Expand Down
2 changes: 0 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,6 @@
[![CI](https://github.com/cypress-io/cypress-documentation/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/cypress-io/cypress-documentation/actions/workflows/ci.yml?query=branch%3Amain)
`main` branch

[![Netlify Status](https://api.netlify.com/api/v1/badges/dbf22ada-b50c-49b0-a933-bf02e87d25d1/deploy-status)](https://app.netlify.com/sites/cypress-docs/deploys)

Our docs are built using [Docusaurus](https://docusaurus.io/).

### Installation
Expand Down
Loading
Loading