Docs shell and page

import 'material-next-web-components/docs-shell.js';
import 'material-next-web-components/docs-top-app-bar.js';
import 'material-next-web-components/docs-page.js';

Overview

These three elements frame this documentation site:

• <mnw-docs-shell> is a full-height column: the nav slot, the page in a <main> landmark, then the footer slot.
• <mnw-docs-top-app-bar> is a sticky bar with leading (brand), default (navigation) and trailing (actions) areas. Below 960px the navigation gets its own scrolling row; below 600px the bar scrolls away with the page.
• <mnw-docs-page> centres its content with documentation spacing.

They are internal candidates: exported, used by this site, but their API may change before 1.0. They hold no state and fire no events; the content, links and routing are yours.

Live demo

<mnw-docs-shell>
  <mnw-docs-top-app-bar slot="nav">
    <a slot="leading" class="brand" href="#">Acme Docs</a>
    <div class="site-nav">
      <a class="site-tab-link" href="#" aria-current="page">Guide</a>
      <a class="site-tab-link" href="#">API</a>
    </div>
    <a slot="trailing" class="btn" href="#">GitHub</a>
  </mnw-docs-top-app-bar>
  <mnw-docs-page style="--mnw-docs-page-max-width: 960px">
    <h1>Getting started</h1>
    <p>Content goes in the shell's default slot, inside <code>&lt;main&gt;</code>.</p>
    <mnw-docs-table-of-contents
      items-json='[{"label":"Install","href":"#install"},{"label":"Use","href":"#use"}]'
    ></mnw-docs-table-of-contents>
    <h2 id="install">Install</h2>
    <p>Sections of the page, linked from the table of contents.</p>
    <h2 id="use">Use</h2>
    <p>The page column keeps a readable width.</p>
  </mnw-docs-page>
  <footer slot="footer" class="site-footer"><div class="site-footer__inner">Footer slot</div></footer>
</mnw-docs-shell>

The classes in this demo (brand, site-nav, site-tab-link, btn) come from this site's stylesheet: the elements lay out the slots, and the page styles what goes in them.

API

<mnw-docs-shell>

Application shell for Material Next documentation pages: a navigation slot, the main landmark and a footer, in a full-height column.

<mnw-docs-shell> slots

Slot	Description
nav	Top app bar, usually an mnw-docs-top-app-bar.
Default	Page content, rendered inside <main>.
footer	Footer content.

<mnw-docs-top-app-bar>

Sticky Material documentation app bar with leading, navigation, and trailing slots. Below 960px the navigation moves to a scrolling row under the brand and actions; below 600px the bar scrolls away with the page.

<mnw-docs-top-app-bar> slots

Slot	Description
leading	Brand or logo link.
Default	Primary navigation, for example md-tabs with links.
trailing	Actions such as a repository link.

<mnw-docs-page>

Centers documentation content with Material documentation spacing.

<mnw-docs-page> slots

Slot	Description
Default	Page content.

<mnw-docs-page> CSS custom properties

Custom property	Description
--mnw-docs-page-max-width	Maximum content width. Default 1120px.
--mnw-docs-page-inline-gutter	Total inline space kept free. Default 32px.
--mnw-docs-page-padding-block	Top padding. Default 32px, 24px below 820px.

Accessibility

• The shell puts the page in a <main> landmark and the top app bar's default slot in a <nav aria-label="Primary">. Use links, not tabs, for site navigation inside it, and mark the current page with aria-current="page".
• Add a skip link before the shell to jump to the content.

Limitations

• Internal candidate: no compatibility promise before 1.0.
• The top app bar's background is a translucent surface with a blur; it does not change on scroll.