Sidebar regions
A whole page rather than a piece of one: the sidebar regions of the theme are filled for this page, so the content sits between a navigation column and a column of page metadata. Every other example is markup dropped in the content region, which says nothing about where the content region is; this one is about the columns beside it, and the only way to see those themed is to put blocks in them. The blocks are built for the example rather than placed, so the page is the same on every site and nothing has to be placed to see it, but they are ordinary block render arrays in ordinary regions, so the aside, the region and the block markup are the ones the theme really outputs. A theme that declares neither region gets neither, and the page reads as an ordinary one-column page. The content is deliberately long: a sidebar only shows whether it scrolls with the page or stays in view once the content beside it is taller than the window.
This page is the example. Its content region holds the text you are reading, and the columns beside it are the sidebar regions of the theme, filled for this page only. Nothing here is placed in the block layout of the site, so the page can be opened on any site the module is installed on and still be the same page.
The two columns
A page template decides where a region goes. The two filled here are the ones a theme is expected to render as an aside beside the content: the first sidebar, which usually carries navigation and comes before the content in the reading order, and the second, which usually carries what the page is about rather than where it sits.
- Sidebar first holds a menu block: the main menu of the site, with every page of this library nested under the entry for the library, the way a documentation site carries its table of contents beside the text. The page being read is in the active trail, one entry is marked as having children that are not shown, and the rest are neither, which is every state a menu item comes in.
- Sidebar second holds two short blocks: the headings of this page, and the pages of the handbook this shape is taken from.
A theme that declares neither region gets neither: the example only fills a region the theme has, so it is safe to open under a theme with a single column, where it reads as an ordinary page.
What the blocks are
Each one is a block render array, so it is wrapped in the block template of the theme, inside the region template, inside the aside the page template puts them in. That is the whole of what a page layout is themed against, and it is the reason the example fills the real regions instead of drawing a picture of them in the content: a mock-up in the content region would carry the classes but sit in the wrong place, and none of the rules that position a sidebar would reach it.
The navigation block goes further than a wrapper, because a menu is the one thing a page sidebar always holds: it carries the plugin ids of a placed menu block and its content is a menu render array in the shape the menu tree hands the template, so the nested lists, the item classes and the active trail are the ones the theme really has to style. The remaining blocks keep a plugin id of this module rather than pretending to be the views blocks a sidebar also holds: those plugins build variables their templates need and cannot be faked convincingly, and the wrapper they are printed in is the same either way.
What to check at each width
Sidebars are where a layout usually breaks, and it breaks differently at each end. Narrow the window through these and watch the three of them in turn.
| Width | What should happen |
|---|---|
| Wide | Three columns, the content the widest of them, and neither sidebar squeezed so far that its links wrap on every word. |
| Medium | One sidebar gives way before the other, and the content keeps a readable measure rather than growing to fill what was given up. |
| Narrow | One column, the sidebars stacked with the content and in an order that still reads: navigation before what it navigates, page metadata after the page. |
A page taller than the viewport
The rest of this page is here to make it long. A sidebar only shows what it does once the content beside it is taller than the window, and the two usual answers look identical on a short page: a column that scrolls away with the content, and a column that stays where it is while the content moves past it.
Both are defensible and a theme has to pick one. If the sidebar carries navigation, keeping it in view is worth the trouble, and the trouble is real: a column that stays needs a height to stay within, it needs its own scrollbar for when its own content is the taller of the two, and it needs to give all of that up at the width where the columns stack, because a navigation block that keeps its own scrollbar inside a single column page is a trap.
If it carries metadata about the page, letting it scroll away is the honest answer, and it costs nothing. What a theme should not do is decide by accident: a sidebar that stays only because its content happens to be shorter than the content region is a layout that changes shape with the length of an article.
Below this is the end of the content region. On a page with a column that stays, the bottom of the content and the bottom of the sidebar arrive together and the footer starts underneath both of them; on a page where the sidebar scrolls away, the space it leaves behind is the last thing before the footer, and how a theme fills it is worth a look.