# Page rendering docs Every page in a project has a rendering doc: one Markdown file that records, section by section, what the server HTML of each template holds and when each section's JavaScript loads. Search engines are certain to read only a page's server HTML, and Googlebot Smartphone crawls the mobile template, so a doc is written from Googlebot's point of view and checked against the real HTML. It is also where the team sees, before a change, which sections ship JavaScript. Default sections for common page types are in [page-type-maps.md](page-type-maps.md), the crawler rules a doc checks against are in [ui-rules.md](ui-rules.md#crawlers), and the way to choose where a section renders is in [rendering-patterns.md](rendering-patterns.md#choosing-where-a-part-loads). Read the sections a task needs. To design a page: Where docs live, Vocabulary, Doc format, Index file, and Writing a doc. To write a missing doc: Where docs live, Vocabulary, Doc format, Index file, Producing a doc from code, and Checking the crawler view. To audit a page: Vocabulary, Doc format, Producing a doc from code, and Checking the crawler view. To change or review a page that has a doc: Vocabulary, Doc format, and Keeping docs current, then Checking the crawler view once the code is built. Doc format, Index file, and Example: home page hold `##` lines inside code blocks, so read each of them to the next heading that the Contents line names. Contents: Where docs live · Vocabulary · Doc format · Index file · Writing a doc · Producing a doc from code · Checking the crawler view · Keeping docs current · Example: home page ## Where docs live ``` docs/pages/ ├── README.md # the index file: one line per page and per layout └── / ├── layout-shop.md # the (shop) group's layout: header and footer, documented once ├── not-found.md # the app's not-found and error pages ├── home.md # / ├── product-id.md # /product/[id] └── category-slug.md # /category/[...slug] ``` - `docs/pages/` sits at the monorepo root, beside `docs/decisions/`. Create it with the first doc. - Write one doc per route, that is, per `page.tsx`. Name it from the route: drop route groups, join the segments with `-`, write a dynamic segment as its parameter name, and call `/` `home`. Brackets stay out of file names, so Markdown links to them work. - A layout that renders UI, such as the header and footer, has its own doc: `layout.md` for the root layout, and `layout-.md` for a route group's layout. A page doc links its layout doc and never repeats its rows. What crawlers get from a URL is its layout docs plus its page doc. - A doc records decisions, never measurements: no sizes, timings, or dates, which change with every build. The PR plan records each key route's first-load JS and HTML size ([b2c-b2b.md](b2c-b2b.md#targets)). - A rule for many pages is a decision ([decisions.md](decisions.md)), not a line in every doc. ## Vocabulary - A section is a block of a page that a reader can name, such as the breadcrumb, the gallery, or the price. A part, in the rest of this skill, is a section with its own component; a part that loads on its own has its own `` and `PartBoundary`. - An indexable page is a page whose robots value is `index`, or `index; noindex when `. Nothing above it streams: no `loading.tsx`, and no `` around `children` in a layout or in a component that a layout renders around them. A `noindex` or blocked page keeps its `loading.tsx` ([b2c-b2b.md](b2c-b2b.md#rendering)). - An entity page is an indexable product, category, brand, seller, article, store branch, or campaign page: its URL names one record that can be missing or moved, so it answers a real 404 or 308 ([error-handling.md](error-handling.md#b2cb2b-server)). - The first flush is the first bytes of the response: the shell, sent when everything outside a `` is ready; with `htmlLimitedBots`, it also waits for `generateMetadata`. On an indexable page, the shell holds everything outside the page's own `` parts, in place. A `` boundary that is complete by then is in place too, while the HTML of the shell, of the boundaries already in place, and its own stays within 12,800 bytes (React's `progressiveChunkSize`, which Next.js doesn't change), or when its own HTML is 500 bytes or less. Otherwise, its fallback is in place, and its content follows the footer, as for `streamed`. - The First flush reads are the reads that the page's primary content needs. The page entry awaits them, `generateMetadata` reads the same caches when it needs data, and no Server Component outside a `` awaits any other read. A secondary section with a read of its own streams. Each section gets three values. Use only these words, with these meanings. Each value has a code signal (Producing a doc from code). **HTML**: what the response holds for the section, as a crawler reads it before any JavaScript runs. Crawlers get the same stream as browsers. | Value | The server HTML holds | |---|---| | `first flush` | The real content, in the first flush, in document order. Every crawler reads it, whether or not it renders the page. | | `streamed` | A skeleton in the first flush, and the real content later in the same response, in a hidden container at the end of ``, such as `