Skip to content

docs: cut the docs site down to what soft navigations add - #18

Merged
ChristopherPHolder merged 5 commits into
mainfrom
docs/essentials
Nov 13, 2026
Merged

ChristopherPHolder merged 5 commits into
mainfrom
docs/essentials

Conversation

@ChristopherPHolder

@ChristopherPHolder ChristopherPHolder commented Nov 13, 2026 •

Copy link
Copy Markdown
Collaborator

Closes #17

The site now only covers what the package adds.

4 pages, down from 12:

  • Introduction: what a soft navigation is, what the package adds, requirements
  • Usage: install, a runnable flow with a soft navigation step, the user-flow flow file, how to tell a soft navigation step apart in the result
  • Throttling: why simulate doesn't work, per step vs. per flow
  • Limits and troubleshooting: the limits, plus a symptom → fix table

Removed: the API reference, How it works, the three Upstreaming pages and Links. From the landing page: the four-step strip, the sample report, the benefit cards and the second call to action. The landing page keeps the hero and one card per page.

Also changed:

  • The logo, favicon, touch icon and 404 scene are the user-flow ones.
  • The hero code shows the config, a page load and a soft navigation step. The terminal it replaces showed sample output the script doesn't print.
  • The hero animation runs the same two-step flow twice: on stock Lighthouse the soft navigation step fails with NO_FCP, and with the config it gets FCP, LCP and a score. It replaces the mock browser, which showed a soft navigation but not what the package does.
  • Pages without a table of contents keep the same text width as the others.
  • The footer drops the Releases link (there are none yet) and the design discussion link.

The upstreaming plan goes back to docs/upstreaming-to-lighthouse.md, and both READMEs link to it again.

Build, typecheck, lint and format pass. The production build prerenders 7 routes.

Screenshots

Hero animation

The flow fails with NO_FCP on stock Lighthouse, then is measured with the config

Landing page

Light Dark
Landing page, light Landing page, dark

Doc pages

Introduction Usage
Introduction page Usage page
Throttling Limits and troubleshooting
Throttling page, dark Limits and troubleshooting page

404 page

404 page

Mobile

Landing page Usage
Landing page on mobile Usage page on mobile, dark

Four pages: introduction, usage, throttling, and limits. The API, internals,
upstreaming and links pages go, along with most of the landing page. The
upstreaming plan moves back to docs/upstreaming-to-lighthouse.md.
- The usage example launches the browser and writes the report.
- Pages without a table of contents keep the same text width.
- A page that starts with a heading no longer shows two rules.
- The landing page lists the four pages and drops the second call to action.
- The troubleshooting table covers user-flow dry runs.
- The mark, favicon, touch icon and 404 scene are the user-flow ones.
- The hero shows the config and a soft navigation step, not a terminal with sample output.
A soft navigation starts from a loaded page, so the hero example failed as written. The usage page and the troubleshooting table say so too.
The hero animation runs the same two-step flow twice: on stock Lighthouse the soft navigation step fails with NO_FCP, with the config it gets FCP, LCP and a score. It replaces the mock browser, which showed a soft navigation but not what the package does.
@ChristopherPHolder
ChristopherPHolder merged commit a6919ad into main Nov 13, 2026
1 check passed
@ChristopherPHolder
ChristopherPHolder deleted the docs/essentials branch November 13, 2026 21:47
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.

docs: cut the docs site down to what soft navigations add

1 participant