Skip to content
Tutorials Center
My learning

Topics

Lesson 129 of 139 ยท Projects

Project: Documentation Layout

Build a three-column documentation page in seven stages with a sticky sidebar, an On this page box, readable code blocks, callouts and menus that collapse on phones.

Documentation sites are read differently from any other kind of page. People rarely start at the top and read to the end. They jump in from a search, scan the headings, copy a command, glance at the sidebar to see where they are and jump somewhere else. A good docs layout supports exactly that: navigation that is always in reach, a clear column of text, an "On this page" list for the current page, and code blocks that are easy to read and copy.

In this project you will build that layout in seven stages. It is a three-column grid on large screens, two columns on tablets and a single column on phones, where both menus collapse into tidy disclosure buttons. Along the way you will use sticky positioning with its own scroll area, grid areas that change with the screen size, generated content for shell prompts, and a dark theme driven by custom properties. Each stage contains the complete code so far.

The product being documented is Pebble, a fictional static site generator. Its commands, package name and version numbers are invented for the project.

Stage 1: The markup

A docs page has more structure than it first seems, and getting the HTML right makes every later stage easier:

  • A <header> top bar with the logo, a version badge and a link.
  • A .layout wrapper with three children, in this source order: the documentation <nav>, an <aside> with the "On this page" list, and the <main> content. On a phone, this is also the reading order: menu, page outline, article.
  • Both menus sit inside a <details> element with a <summary>. That gives us a free, accessible show/hide button for small screens, with no JavaScript needed for the toggle itself. They start with the open attribute, so they are visible until Stage 6 decides otherwise.
  • The current page in the sidebar has aria-current="page", which screen readers announce and which CSS can target.
  • Every <h2> has an id and a small # anchor link, so people can copy a link to one section. The anchor has an aria-label, because "#" alone means nothing to a screen reader.
  • Shell commands are wrapped in <span class="cmd">, so CSS can add a $ prompt later. Output lines have no span, which keeps them visually distinct from what you type.
  • The options table sits inside a <div class="table-wrap"> with role="region", an aria-label and tabindex="0". When the table scrolls sideways on a phone, keyboard users can focus the region and scroll it with the arrow keys.
Stage 1: markup

The browser's default styles already make it readable. The <details> elements show their summaries with a small triangle, and you can click them to fold the menus away.

Stage 2: Tokens, base styles and the top bar

The design tokens describe a calm, technical look: dark blue-gray ink, a teal accent with a soft tint, a light gray for subtle backgrounds, and a separate pair of colors for code blocks. There is also a --topbar token for the height of the top bar. Several later rules need to know that height, and keeping it in one place means the sticky elements stay correct if you ever change it.

The --mono token is a font stack for code. ui-monospace asks for the system's own monospace font (SF Mono on Apple devices), followed by common fallbacks for Windows and Linux. Code fonts matter on a docs site: people read them as much as the prose.

The top bar is a sticky flex row (Flexbox Patterns). The changelog link gets margin-inline-start: auto, which absorbs the free space and pushes it to the far end. The bar has a solid background, which is important for anything sticky: without one, the content scrolling underneath would show through the text.

Stage 2: tokens and top bar

Stage 3: The responsive grid

Now the core layout. The .layout grid uses named areas (Grid Template Areas), and the whole responsive behavior is three versions of the same map:

Screen Columns Map
Phones one "nav" "toc" "main"
From 48em sidebar + content "nav toc" "nav main"
From 64em sidebar + content + outline "nav main toc"

On tablets, the sidebar fills the left column and spans both rows, while the outline sits above the article in the right column. On large screens, the outline moves into its own column on the right. The items never change; only the map does.

Three details deserve a closer look:

  • minmax(0, 1fr) for the content column. Docs pages are full of things that refuse to shrink: long code lines and wide tables. A plain 1fr column can't get narrower than its widest content, so one long command would push the whole layout off the screen. minmax(0, 1fr) allows the column to shrink, and the code blocks scroll inside it instead (Grid Tracks). For the same reason, .content has min-width: 0.
  • align-items: start. By default, grid items stretch to the height of their row. The outline box should be only as tall as its list, so the grid aligns items to the start.
  • align-self: stretch for the sidebar. The exception: the sidebar should stretch to the full height of the layout. That gives the sticky menu inside it room to stay in view as the page scrolls, which is the next stage.
Stage 3: grid areas

What you see depends on the width of your preview. A preview narrower than 48em (768 pixels) stacks everything; change 48em and 64em to smaller values, such as 30em and 40em, to see the other two layouts in a narrow preview. Remember to change them back.

Stage 4: Sticky navigation with its own scroll area

A docs sidebar can be long, often longer than the screen. If it simply scrolled away with the page, people would have to scroll back up to navigate. If it were sticky without any limit, its bottom links would be out of reach. The solution is a sticky box with a maximum height and its own scrollbar:

CSS
.sidebar .collapsible {
  position: sticky;
  top: calc(var(--topbar) + 1.5rem);
  max-height: calc(100dvh - var(--topbar) - 3rem);
  overflow-y: auto;
  overscroll-behavior: contain;
}

Read it line by line:

  • top is the distance from the top of the viewport where the box sticks. It must clear the sticky top bar, so it is the bar height plus some breathing room. This is where the --topbar token pays off.
  • max-height uses 100dvh, the dynamic viewport height, which follows the visible area on phones as their browser toolbars appear and disappear (Viewport Units). The box is never taller than the space under the top bar.
  • overflow-y: auto adds a scrollbar only when the menu is longer than that space (Overflow).
  • overscroll-behavior: contain stops "scroll chaining": when you reach the end of the sidebar, further scrolling doesn't start scrolling the page behind it.

Only the inner box is sticky. Its parent, the <nav> grid item, stretches the full height of the layout, and a sticky element can only move within its parent. That is why Stage 3 made the sidebar stretch.

The menu styling is quiet on purpose. The group labels are small uppercase text. The current page, found with the attribute selector [aria-current="page"], gets the accent tint (Attribute Selectors). The outline list has a thin line on its left edge, and each link has a transparent border of the same width, pulled over the line with a negative margin. On hover, the border turns teal, so a small marker slides along the line.

Stage 4: sticky menus

In a wide preview, scroll the page: the top bar, the sidebar and the outline stay in place while the article moves.

Stage 5: The article, code blocks, callouts and tables

This stage styles the content itself, and it is the biggest one, because content is what people come for.

Reading width. .doc gets max-width: 46rem. Long lines are tiring to read, and at this size, body text stays at roughly 70 to 80 characters per line (Text Styling).

Section headings get a thin top border, so the sections are easy to spot while scanning. The # anchor link has opacity: 0 and appears when you hover over the heading. .anchor:focus-visible also shows it, so keyboard users who tab to it can see where they are.

Inline code is selected with :not(pre) > code: code that is not directly inside a <pre>. It gets a light gray pill, and overflow-wrap: anywhere lets a long name like npm prefix --global break instead of overflowing a narrow phone. <kbd> keys get a thicker bottom border, so they look like physical keys.

Code blocks (pre.code) get a dark background, padding, rounded corners and overflow-x: auto. Never wrap code in a docs page; a scrollbar is better than a command that looks like two commands. tab-size: 2 keeps tab-indented code compact.

Shell prompts come from generated content:

CSS
.cmd::before {
  content: "$ ";
  color: #7fd1c7;
}

Each command line shows a $ prompt, but the prompt is not part of the HTML, so in most browsers it isn't copied when someone selects the command (Pseudo-elements). Output lines have no prompt, so it's instantly clear what to type.

A file name label sits on top of the configuration block. The <figcaption> is an inline block with rounded top corners in a slightly lighter shade, and border-start-start-radius: 0 squares off the block's top-left corner so the two pieces join seamlessly. That's a logical property: it means "top left" in left-to-right languages and follows the writing direction otherwise.

Callouts use one rule for every type. The color comes from a --callout custom property set by each modifier class, and the background mixes 10% of it into the page color with color-mix() (Modern Colors). A new callout type, such as a red "danger" box, needs only one line of CSS.

Tables sit in their scrolling wrapper. The table has min-width: 32rem, so on a phone it keeps readable columns and scrolls, instead of squeezing each column into a tall stack of words (Styling Tables).

The pager at the end uses the auto-fit grid pattern: two links side by side when there is room, stacked when there isn't (Grid Patterns).

Stage 5: content styles

Stage 6: Collapsing the menus on small screens

On a phone, a full sidebar above the article pushes the content you came for far down the page. Both menus are already inside <details> elements, so they can collapse; this stage decides when.

The CSS part is simple. The <summary> gets a button-like look on small screens. From 48em, the sidebar's summary gets display: none: on a wide screen the menu is always visible, so it doesn't need a toggle. From 64em, the outline's summary loses its button styling and becomes a plain label, with list-style: none removing the triangle marker (Lists) and pointer-events: none ignoring clicks.

There is one thing CSS can't do: open or close a <details> element. A closed <details> hides its content no matter what your CSS says. So a few lines of JavaScript sync the open state with the same media query the CSS uses:

JavaScript
const wide = matchMedia('(min-width: 48em)');

function syncMenus() {
  for (const menu of document.querySelectorAll('.collapsible')) {
    menu.open = wide.matches;
  }
}

syncMenus();
wide.addEventListener('change', syncMenus);

The HTML still starts with both menus open. If the script fails to load, everyone sees the full navigation, which is the safe default. The script only closes the menus on narrow screens, and the change listener reopens them if the window grows past 48em.

Stage 6: collapsing menus

In a narrow preview, you now see two compact buttons, "Docs menu" and "On this page", followed directly by the article. Tap one to open it.

Newer browsers let you style the content box of a <details> element with the ::details-content pseudo-element, and the HTML name attribute can link several <details> elements into an accordion. Neither replaces the small script here, because the script must change the open state itself.

Stage 7: Dark theme and finishing touches

Because every color comes from a token, the dark theme is one block that redefines the tokens inside @media (prefers-color-scheme: dark). color-scheme: light dark tells the browser that the page supports both, so scrollbars, form controls and the default focus colors switch too (Dark Mode). The code blocks were already dark, so they only get a slightly deeper background. The callouts adapt automatically, because their tint is mixed from var(--page).

The other touches:

  • scroll-padding-top on html makes outline links land below the sticky top bar rather than under it. It reuses the --topbar token.
  • The target heading is highlighted. When you follow an outline link, the URL fragment points to that heading, so h2:target matches. It turns teal, and a short flash animation fades a tinted background out. A @keyframes rule with only a from frame animates from those values back to the element's normal style (Animations). The animation and smooth scrolling only run under prefers-reduced-motion: no-preference.
  • A skip link hides above the page until it receives focus, and :focus-visible draws a clear outline for keyboard users (Accessible CSS).
Stage 7: the finished docs page

Click the links in the outline to watch the headings flash, and switch your system to dark mode to see the dark theme. You now have a documentation layout that works on every screen size, keeps navigation in reach, and makes code easy to read.

Ideas to take it further

  • Highlight the outline link of the section currently on screen as you scroll. That needs a little JavaScript with an IntersectionObserver, which toggles a class on the matching link.
  • Add a "Copy" button to each code block. Use position: absolute inside a position: relative block, and show the button on hover and focus.
  • Organize the stylesheet with @layer base, layout, components; so components can never be overridden by accident (Cascade Layers).
  • Write a print stylesheet that hides both menus and the pager and prints the URL after each link (Print Styles).

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Why does the content column use minmax(0, 1fr) instead of 1fr?

    With minmax(0, 1fr), the column's minimum is 0, so wide content like code blocks and tables scroll inside it instead of widening the page.
  2. 2. The sidebar menu is sticky but its bottom links are unreachable on short screens. Which fix matches this project?

    A maximum height keeps the menu within the visible area, and its own scrollbar lets people reach every link.
  3. 3. Why does the <nav> grid item get align-self: stretch?

    Sticky positioning keeps an element in view only while its containing block is on screen. A short parent would carry the menu away after a few lines.
  4. 4. What does :not(pre) > code select?

    The selector matches code elements whose parent is anything except pre, so inline code gets a pill while code blocks keep their dark style.
  5. 5. Why does the project need a few lines of JavaScript to collapse the menus?

    The open state lives in the HTML. The script opens the menus on wide screens and closes them on narrow ones; everything else is CSS.

Summary

  • One set of grid areas, redrawn at 48em and 64em, turns a single column into a two- and three-column docs layout without touching the items.
  • minmax(0, 1fr) and min-width: 0 let the content column shrink, so code blocks and tables scroll instead of breaking the layout.
  • A sticky menu needs a stretched parent, a top that clears the top bar, a max-height based on 100dvh, overflow-y: auto and overscroll-behavior: contain.
  • Style inline code with :not(pre) > code, keep code blocks unwrapped with overflow-x: auto, and add shell prompts with ::before.
  • One callout rule plus a --callout property and color-mix() covers every callout type.
  • <details> gives collapsible menus on phones; a short matchMedia script keeps them open on wide screens.
  • Tokens make dark mode one block; scroll-padding-top and :target make in-page links land well.

Next: Project: Dashboard Layout, the final project, where you build an app layout with grid areas, container queries and dark mode.