- **Invalid YAML in `index.yml`:** Check indentation — nav entries use 2-space indent. A `- page:` must be inside a `contents:` block.
- **Missing file:** The `path:` in `index.yml` must match the actual file location. Paths are relative to `docs/` (e.g., `getting-started/quickstart.md`).
### `fern docs broken-links` reports errors
- **Broken internal link:** A markdown link reference points to a file that doesn't exist. Fix the path or remove the link.
- **Anchor not found:** A `#section-heading` link doesn't match any heading in the target page.
### CI fails after merge
- **MDX parse error:** Angle-bracket URLs like `<https://example.com>` break MDX parsing. Use `[text](https://example.com)` instead.
- **Broken links check:** The `detect_broken_links.py` job checks relative links across all docs. If your new page links to a file that doesn't exist yet, CI will fail.
- **Fern publish error:** Check the Actions tab for the `Fern Docs` workflow. Common causes: expired `FERN_TOKEN`, invalid `fern/docs.yml` syntax, or a file referenced in `index.yml` that wasn't synced to `docs-website`.
### Page doesn't appear on the live site
- **Missing nav entry:** The page exists but isn't in `docs/index.yml`. Add it.
- **Hidden section:** The page is inside a `hidden: true` section. It's accessible by direct URL but won't appear in the sidebar.
- **Sync delay:** After merge to `main`, the sync-dev workflow takes a few minutes to publish.
## Key References
| File | Purpose |
|------|---------|
| `docs/index.yml` | Navigation tree — add entries here |
| `docs/` | Content directory — create pages here |
description:Remove a page from the Dynamo Fern docs site. Use when deleting documentation pages.
---
# Remove a Dynamo Docs Page
Claude Code skill for removing a page from the Dynamo Fern documentation site.
## Related Skills
| Skill | Use When |
|-------|----------|
| [add-dynamo-docs](../add-dynamo-docs/SKILL.md) | Adding a new docs page |
| [update-dynamo-docs](../update-dynamo-docs/SKILL.md) | Editing an existing docs page |
---
## Branch Rule
**ALL edits happen on `main` (or a feature branch based on `main`).**
The `docs-website` branch is CI-managed and must **never** be edited by hand.
## Working Directory
Must be in the `dynamo` repo (not `dynamo-tpm`). Architecture details: `docs/README.md`.
## When Invoked
### 1. Identify the Page
Ask for the page to remove (accepts any of):
- File path (e.g., `docs/guides/old-page.md`)
- Page title (e.g., "Old Page")
- Topic keyword to search for
If given a title or keyword, search for the page:
```bash
# Search by title in navigation
grep-n"<title>" docs/index.yml
# Search by keyword in content
grep-rl"<keyword>" docs/
```
### 2. Find the Navigation Entry
Locate the page's entry in `docs/index.yml`:
```bash
grep-n"<filename>" docs/index.yml
```
Note the exact `- page:` block and its indentation level. If the page is the
sole entry in a `- section:` block, the entire section should be removed.
### 3. Check for Incoming Links
Search for references to this page from other docs:
```bash
# Search for the filename across all docs pages
grep-r"<filename>" docs/ --include="*.md"
# Also check the navigation file for any cross-references
grep-r"<filename>" docs/
```
Report any files that link to the page being removed — these links will break
and need updating.
### 4. Remove the Markdown File
```bash
git rm docs/<subdirectory>/<filename>.md
```
### 5. Remove the Navigation Entry
Edit `docs/index.yml` and delete the `- page:` block (and its `path:`
line). If this was the last page in a section, remove the entire `- section:`
block.
### 6. Fix Broken Incoming Links
For each file that linked to the removed page:
- Remove the link, or
- Redirect to a replacement page, or
- Leave a note about the removal
### 7. Validate
```bash
fern check
fern docs broken-links
```
### 8. Preview Locally (Optional)
```bash
fern docs dev
```
Opens a local preview at `http://localhost:3000` with hot reload. No token required.
### 9. Commit
```bash
git add -u docs/
git commit -s-m"docs: remove <page-title> page"
```
## Debugging
### `fern check` fails
-**Orphaned nav entry:** You deleted the file but left the `- page:` entry in `index.yml`. Remove it.
-**Empty section:** If the removed page was the only entry in a section, delete the entire `- section:` block from `index.yml`.
### `fern docs broken-links` reports errors
-**Incoming links to removed page:** Other pages still link to the deleted file. Search with `grep -r "<filename>" docs/` and update or remove those links.
### CI fails after merge
-**MDX parse error:** Angle-bracket URLs like `<https://example.com>` break MDX parsing. Use `[text](https://example.com)` instead.
-**Broken links check:** The `detect_broken_links.py` job found pages that still reference the removed file. Fix all incoming links before merging.
-**Fern publish error:** Check the Actions tab for the `Fern Docs` workflow. Common causes: expired `FERN_TOKEN`, invalid `fern/docs.yml` syntax.
### Page still appears on the live site
-**Sync delay:** After merge to `main`, the sync-dev workflow takes a few minutes to publish.
-**Cached version:** Fern CDN may cache the old page briefly. Hard-refresh or wait a few minutes.
## Key References
| File | Purpose |
|------|---------|
| `docs/index.yml` | Navigation tree — remove entries here |
| `docs/` | Content directory — delete pages here |
2. Remove the old `- page:` entry from `index.yml`
3. Add a new `- page:` entry under the target section in `index.yml`
4. Update the `path:` to reflect the new location
### 4. Check Incoming Links (If Path Changed)
If the file was moved, search for references that need updating:
```bash
# Search for the old path across all docs
grep-r"<old-filename>" docs/ --include="*.md"
grep-r"<old-filename>" docs/
```
Update all references to point to the new path.
### 5. Content Guidelines
Use standard **GitHub-flavored markdown**. For callouts, use GitHub's native syntax — CI auto-converts to Fern format:
```markdown
> [!NOTE]
> Helpful context for the reader.
> [!WARNING]
> Something the reader should be careful about.
```
**Callout mapping** (GitHub → Fern):
| GitHub Syntax | Fern Component |
|---|---|
| `> [!NOTE]` | `<Note>` |
| `> [!TIP]` | `<Tip>` |
| `> [!IMPORTANT]` | `<Info>` |
| `> [!WARNING]` | `<Warning>` |
| `> [!CAUTION]` | `<Error>` |
### 6. Validate
```bash
fern check
fern docs broken-links
```
### 7. Preview Locally (Optional)
```bash
fern docs dev
```
Opens a local preview at `http://localhost:3000` with hot reload. No token required.
### 8. Commit
```bash
git add docs/
git commit -s-m"docs: update <page-title>"
```
## Debugging
### `fern check` fails
-**Invalid YAML in `index.yml`:** Check indentation — nav entries use 2-space indent. A `- page:` must be inside a `contents:` block.
-**Missing file:** If you moved a page, the `path:` in `index.yml` must match the new location.
-**Duplicate entry:** The same page appears twice in `index.yml`. Remove the old entry after a section move.
### `fern docs broken-links` reports errors
-**Stale internal links:** After moving or renaming a page, other pages may still link to the old path. Search with `grep -r "<old-filename>" docs/` and update references.
-**Anchor not found:** A `#section-heading` link doesn't match any heading in the target page. Check if the heading text changed.
### CI fails after merge
-**MDX parse error:** Angle-bracket URLs like `<https://example.com>` break MDX parsing. Use `[text](https://example.com)` instead.
-**Broken links check:** The `detect_broken_links.py` job found stale references to the old path. Fix all incoming links before merging.
-**Fern publish error:** Check the Actions tab for the `Fern Docs` workflow. Common causes: expired `FERN_TOKEN`, invalid `fern/docs.yml` syntax, or a moved file that wasn't synced to `docs-website`.
### Changes don't appear on the live site
-**Title mismatch:** You updated the frontmatter `title:` but not the `- page:` name in `index.yml` (or vice versa). Keep them in sync.
-**Sync delay:** After merge to `main`, the sync-dev workflow takes a few minutes to publish.
## Key References
| File | Purpose |
|------|---------|
| `docs/index.yml` | Navigation tree — update entries here if title/path changes |
Ishan Dhanani <ishandhanani@gmail.com>