Test: Add Documentation testing checklist page #5481
Conversation
|
Requested by: Unknown |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
|
|
||
| ## Navigation and links | ||
|
|
||
| Navigation issues are the most common source of post-merge bugs. A new MDX file that isn't referenced in `docs.yml` is silently excluded from the build, and broken links can ship without warning. |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[FernStyles.Adverbs] Remove 'silently' if it's not important to the meaning of the statement.
|
|
||
| ## API references | ||
|
|
||
| API reference pages are generated from OpenAPI, AsyncAPI, gRPC, or Fern Definition specs. Changes that affect APIs require additional validation: |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[FernStyles.Reject] Use 'API Reference' instead of 'API reference'.
| The [API Explorer](/learn/docs/api-references/api-explorer) renders an interactive playground for each endpoint. Confirm parameters, auth, and example responses look right. | ||
| </Step> | ||
| <Step title="Review the changelog"> | ||
| If the API change is user-facing, add a changelog entry under `fern/products/docs/pages/changelog/` with a filename of `YYYY-MM-DD.mdx`. Use `##` headings, include `tags` in frontmatter, and lead with the user capability. |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[FernStyles.Acronyms] 'YYYY' has no definition.
| </Step> | ||
| </Steps> | ||
|
|
||
| ## Accessibility and SEO |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[FernStyles.Headings] 'Accessibility and SEO' should use sentence-style capitalization.
|
|
||
| - **Headings.** Pages should have exactly one `<h1>` (the title from frontmatter). Subheadings should be ordered — don't jump from `##` to `####`. | ||
| - **Alt text.** Every image should have alt text describing what it shows. Decorative images can use `alt=""`. | ||
| - **Color contrast.** If you added custom CSS or color overrides, check WCAG AA contrast for body text. |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[FernStyles.Acronyms] 'WCAG' has no definition.
|
🌿 Preview your docs: https://fern-preview-fern-test-page-addition.docs.buildwithfern.com/learn Here are the markdown pages you've updated: |
fern-api
Bot
force-pushed
the
fern/test-page-addition
branch
from
e2287b4 to
b64968a
Compare
| This page is a sample used to exercise the Fern Docs build and publishing pipeline. It walks through the most common authoring patterns — frontmatter, headings, callouts, code blocks, tabs, accordions, and cross-page links — so that pull requests touching the docs infrastructure can be verified against a single, self-contained reference. | ||
|
|
||
| <Callout intent="info"> | ||
| This page is intentionally hidden from search engines (`noindex: true`) and lives in the hidden **Resources** section. It is safe to land, revert, or move without affecting customer-visible navigation. |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Microsoft.Contractions] Use 'it's' instead of 'It is'.
| Callouts highlight tips, warnings, and notes. Use the intent that matches the content — `info`, `success`, `warning`, or `danger`. | ||
|
|
||
| <Callout intent="success"> | ||
| Use `success` callouts to confirm a positive outcome, like "Your docs site is now live at `your-domain.docs.buildwithfern.com`." |
There was a problem hiding this comment.
[FernStyles.Current] Avoid time-relative terms like 'now' that become outdated
|
|
||
| <AccordionGroup> | ||
| <Accordion title="Why is my page missing from the sidebar?"> | ||
| Fern only includes pages that are referenced in `docs.yml` navigation or auto-discovered by a `folder:` entry. If a page is not appearing, confirm that its `path:` matches the file on disk and that no parent section is marked `hidden: true` unintentionally. |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Microsoft.Contractions] Use 'isn't' instead of 'is not'.
| Add a top-level `- section:` entry to the relevant product's YAML file with a `contents:` list of pages. See [Sections, pages, and folders](/learn/docs/navigation) for the full schema. | ||
| </Accordion> | ||
| <Accordion title="How do I redirect an old URL?"> | ||
| Add a `redirects:` entry to `fern/docs.yml` mapping the old path to the new path. Redirects take effect on the next publish. |
There was a problem hiding this comment.
[FernStyles.Current] Avoid time-relative terms like 'old' that become outdated
|
|
||
| 1. **Prefer updates over duplicates.** Search the repo before creating a new page; an existing page may already cover the topic. | ||
| 2. **Lead with the user benefit.** Open each page with what the reader will be able to do, not how the feature is implemented. | ||
| 3. **Cross-link generously.** When you mention a concept covered elsewhere, link to it using a `/learn/...` URL path. |
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[FernStyles.Adverbs] Remove 'generously' if it's not important to the meaning of the statement.
|
Requested by: Unknown |
1 participant
Summary
Test PR — adds a substantial new page to the (hidden) Resources section in the
docsproduct.fern/products/docs/pages/resources/docs-testing-checklist.mdx(~205 lines)Resourcessection infern/products/docs/docs.ymlThe Resources section is
hidden: true, so the new page is not surfaced in production navigation. The page itself is intentionally substantial — a practical pre-merge checklist for verifying Fern docs changes (builds, navigation, links, components, API references, accessibility, review, and post-merge validation).What this validates
<Steps>,<AccordionGroup>,<CardGroup>, callouts, and internal/learn/...links render in CI/previewRequested by: Fern Support