Blocks that read a document

Each block is a live component, so give it an id, as the sample pages do. Every block also takes global HTML attributes through rest, and carries a data-role on each element that a stylesheet can restyle it by. All four take the attributes below, except that doc-toc has no doc_base: it links to anchors in its own page and writes no address of another page.

A page that shows a document or a page of one reads the document, its versions and the page once, and hands those rows to its blocks. These four blocks are the ones that take them. doc-workspace-list and doc-section-cards declare no page_source and always read for themselves. See Page source: read a page's rows once for how a page reads and hands down the rows.

The tables below list only what each block adds. Every block that reads in the background also takes loading_text, error_text and retry_text, listed in its own table. While a later read runs, the block draws a skeleton. When a read fails it draws the error text and a Try again button.

Draws one page of a document: the trail above it, its title, when it last changed, its text, its notes, and links to the pages either side. With nothing asked, it draws the version's front page, or the document's landing. The landing is an overview: the document's tile, its version and number of pages, its name and summary, the first pages as numbered cards, and every page under the heading it is filed under. The block reads in step with the request, so the page's text is in the HTTP response.

The words doc-section says are attributes too:

The page's text and notes pass through the same HTML cleaning as the text is stored through, then draw the components placed in them. Each code block is drawn in a window with its language and a copy button. A placed doc-callout, doc-example or doc-section-cards is drawn there. See Callouts, examples and the version placeholder. A plugin adds facts and tabs through the document:page:extras event. See Plugin events.

Draws a document's whole contents as a tree, with the branch the reader is in open. Its hook doc-sidebar-scroll keeps the list where the reader left it as they move between pages, and brings the current entry into view when it lies outside.

Draws what is on the page being read, its headings and its notes, as links to anchors in the page. On a document's landing, which has no text, it draws nothing.

Draws a document's versions in a menu, each leading to the same page in that version. A version that does not have the page, or whose copy of it the reader may not open, leads to the document's front page. The closed menu names the version being read, and the list marks each version that is not stable with its status. When the version being read is not the latest, a line beside the menu says so and links to the latest. The block has no language switch: the site's header lists the languages the page is written in. On the sample pages, the bar under the header draws it. See Page frame: languages and the section bar.

• Document list and card blocks.
• How documents are organized.
• Page source: read a page's rows once: the rows a page hands to page_source.
• Page frame: languages and the section bar: the bar that draws doc-switcher.