1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129<div
class="wrapper"
data-layout="app"
data-shell-mode="viewport"
>
<div data-slot="page" id="toc-demo-page">
<header>
<div class="container-fluid">
<div class="d-flex align-items-center gap-3 py-3">
<strong class="small">Moo Starter</strong>
<span class="small text-body-secondary">Placement guide</span>
</div>
<div class="d-lg-none border-top py-3">
<nav id="demo-toc-compact" aria-label="On this page" data-toc="" data-toc-content="demo-article" data-toc-scroll-root="main-content" class="dropdown d-flex align-items-center gap-2 w-100">
<button class="btn btn-ghost btn-sm dropdown-toggle flex-shrink-0 bg-body-secondary" type="button" data-bs-toggle="dropdown" aria-expanded="false">On this page</button>
<span data-toc-current class="small text-body-secondary text-truncate">Overview</span>
<ul class="dropdown-menu w-100">
<li>
<a class="dropdown-item text-wrap text-break" href="#introduction"><span>Introduction</span></a>
</li>
<li>
<a class="dropdown-item text-wrap text-break" href="#content-and-configuration"><span>Content and configuration</span></a>
</li>
<li>
<a class="dropdown-item text-wrap text-break" href="#languages"><span>Languages</span></a>
</li>
<li>
<a class="dropdown-item text-wrap text-break" href="#navigation"><span>Navigation</span></a>
</li>
</ul>
</nav>
</div>
</div>
</header>
<main id="main-content" tabindex="-1" class="scroll-fade-y no-scrollbar">
<div class="container-xl" data-page-container>
<div class="row g-5 py-4">
<article class="col-12 col-lg-9" id="demo-article">
<h1 class="mb-3">Placement guide</h1>
<p class="text-body-secondary mb-4">Content placements and an independent aside.</p>
<section class="mb-5" aria-labelledby="introduction">
<h2 class="mb-3" id="introduction">Introduction</h2>
<p>A document can have an automatic table of contents beside its article. This guide brings together four parts of a small multilingual website: the article itself, the project configuration, the translated content and the navigation around it.</p>
<p>The article remains the main reading area. Its heading, description, paragraphs and lists come from the project's content file. Supporting information gives additional context without interrupting the reading order. Readers can begin with the article and find the supporting information afterwards on a narrow screen.</p>
<p>The table of contents serves a different purpose from the site menu. Its links point to headings on this page, while the site menu leads to other pages and archives. Following a heading leaves a URL fragment that can be copied and shared.</p>
<p>Read the guide from beginning to end or use the section links to move between topics. As each heading reaches the top of the reading area, the active indicator moves to the corresponding item.</p>
</section>
<section class="mb-5" aria-labelledby="content-and-configuration">
<h2 class="mb-3" id="content-and-configuration">Content and configuration</h2>
<p>The project owns this content. The package supplies the layout and reusable blocks. Authors can update the text without editing a template, and the site can change its layout without moving the article into a theme package.</p>
<p>Content and configuration answer different questions. The article describes the subject of the page. Configuration determines which navigation is available and where supporting blocks appear. Reusable information can be maintained separately and placed beside several articles.</p>
<p>A simple editing routine keeps the responsibilities clear:</p>
<ul>
<li>Write the article and its description in the content file.</li>
<li>Choose headings that describe each section clearly.</li>
<li>Assign relevant categories and tags.</li>
<li>Keep shared notices or contact information in reusable blocks.</li>
<li>Use project preferences for layout choices that apply across the site.</li>
</ul>
<p>The aside contains the table of contents and a separate page-information block. Each has its own section, and the configured gap provides consistent space between them. Adding another supporting block preserves that rhythm without empty paragraphs or manual spacing.</p>
</section>
<section class="mb-5" aria-labelledby="languages">
<h2 class="mb-3" id="languages">Languages</h2>
<p>Each published translation uses its own headings and reusable content. Versions of the guide discuss the same subjects, while the article and section labels are written for their readers. A language switcher connects the corresponding published routes.</p>
<p>Translated headings may have different fragment identifiers. Generate section links from the current document's headings so that the table of contents follows the version being read. The navigation label and the overview label can be translated independently.</p>
<p>A longer section label should wrap naturally without pushing the article out of its column. On narrow screens, the compact menu uses the available row width and keeps the current section visible beside its trigger.</p>
<p>The same structure also supports right-to-left content. Logical spacing utilities follow the document direction, and native links continue to point to the same authored section identifiers.</p>
</section>
<section class="mb-5" aria-labelledby="navigation">
<h2 class="mb-3" id="navigation">Navigation</h2>
<p>Site navigation and article navigation remain independent. The site menu takes readers to another document. The table of contents moves within the current article and keeps their place visible while they read.</p>
<p>On a wide screen, the section list stays beside the article. Below the large breakpoint, a compact menu appears below the page header. The header remains available while the article scrolls, so readers can choose another section at any point.</p>
<p>Supporting content follows the article when the columns stack. It remains accessible without competing with the compact table of contents. The reading area uses the space left between the header and footer.</p>
<p>Try returning to Introduction, then switch between the desktop, tablet and mobile previews. Each mode displays the same document and section data. The active section stays synchronized when the visible presentation changes.</p>
<h3 class="h5 mt-4 mb-3">Choosing section headings</h3>
<p>A heading should help a reader predict what comes next. Use the words that describe the task or subject, and keep the same wording in the section list. A concise label can still be specific: Content and configuration tells readers more than a general label such as Details. The heading remains part of the article even when the navigation is hidden.</p>
<p>Choose a stable identifier when a section is first published. If its wording changes later, keeping the identifier preserves links shared in messages, bookmarks and other pages. The visible title and the URL fragment have separate responsibilities: one explains the content, and the other provides a reliable destination. Section labels can change without breaking a reader's saved link.</p>
<h3 class="h5 mt-4 mb-3">Following the reading position</h3>
<p>The active indicator follows the section at the top of the reading area. It changes when a reader scrolls naturally and when they follow a section link. The list and compact control describe the same position, so resizing the preview does not require selecting the section again. Move between Languages and Introduction to watch the indicator travel along the outline.</p>
<p>A fixed header sits outside the article's scrolling region. This leaves the navigation available without covering the target heading. The scrolling region owns the remaining page height, and the supplementary column remains alongside it on larger screens. The footer has its own place below the reading area and stays visible while the article moves between sections.</p>
<h3 class="h5 mt-4 mb-3">Moving between screen sizes</h3>
<p>Desktop readers have enough space for a persistent outline beside the text. The tablet preview uses the compact control in the header, giving the article the full reading width. Mobile uses the same control and allows longer labels to wrap in the menu. These presentations share the document and the current section; they offer different ways to reach the same content.</p>
<p>Supporting information stays in the document when the layout changes. On narrow screens, it follows the article rather than occupying a second reading column. Scroll to the end of the mobile preview to find the page-information section. Returning to a heading through the compact menu brings the article back into view while the header and footer keep their positions.</p>
<h3 class="h5 mt-4 mb-3">Keyboard navigation and shared links</h3>
<p>Native links remain usable with a keyboard. Tab reaches the section controls, and Enter follows the selected link. The compact control also uses the normal Dropdown keyboard behavior: open the menu, move between its options, choose a section, or close it with Escape. Focus and the active reading position serve different purposes, so each retains its own visible state.</p>
<p>The URL fragment identifies the selected destination. In the standalone document, a saved fragment can reopen the corresponding section, and browser history can return to an earlier destination. Within this preview, the document has its own history and scroll area. Exploring its section links leaves the surrounding documentation route, reading position and navigation controls available.</p>
<h3 class="h5 mt-4 mb-3">Keeping the document readable</h3>
<p>The table of contents is an aid for longer articles. The main text should still be understandable when read from beginning to end. Give each section enough context, keep paragraphs focused on one idea, and use lists where readers benefit from a sequence. The outline then becomes a useful map of content that already has a clear reading order.</p>
<p>Readers who prefer reduced motion can move directly to a destination without animated scrolling. The same section links and current-section information remain available. Test both the reading flow and the section controls when publishing a guide, and check the narrow layout with realistic text so that long labels and supporting information receive the space they need.</p>
</section>
</article>
<aside class="col-12 col-lg-3" aria-label="Page information">
<div class="sticky-top d-flex flex-column gap-5">
<section class="d-none d-lg-block" aria-label="Article sections">
<nav aria-label="On this page" id="demo-toc-list" data-toc="" data-toc-content="demo-article" data-toc-scroll-root="main-content">
<span class="small fw-semibold ps-3">On this page</span>
<ul class="nav flex-column flex-nowrap gap-0 small p-0">
<li class="nav-item">
<a class="nav-link ps-3" href="#introduction"> <span> Introduction </span> </a>
</li>
<li class="nav-item">
<a class="nav-link ps-3" href="#content-and-configuration"> <span> Content and configuration </span> </a>
</li>
<li class="nav-item">
<a class="nav-link ps-3" href="#languages"> <span> Languages </span> </a>
</li>
<li class="nav-item">
<a class="nav-link ps-3" href="#navigation"> <span> Navigation </span> </a>
</li>
</ul>
</nav>
</section>
<section class="mb-5" aria-labelledby="demo-information">
<h4 class="h5" id="demo-information">Page information</h4>
<p>This guide uses a reusable supporting block. It appears beside the article on a wide screen and follows it when the columns stack.</p>
<p class="mb-0">Section links keep their native fragments and browser history.</p>
</section>
</div>
</aside>
</div>
</div>
</main>
<footer>
<div class="container-xl">
<div class="py-3 small text-body-secondary">Moo Starter · Placement guide</div>
</div>
</footer>
</div>
</div>
Usage
Supply ordered section IDs and plain-text labels. Moo UI renders native fragment links; the host owns headings, content and layout. Empty sections render nothing. A single section remains available.
Use the viewport controls to resize the same live document. Choose a section or scroll inside the preview to follow its active indicator. The preview owns its URL fragments and scroll area independently from this documentation page.
Responsive placement
The desktop list stays beside the article. Below lg, the compact presentation moves into the header above the scrolling content. Both use the same section data with unique navigation IDs and complementary Bootstrap visibility utilities.
The compact menu spans its navigation row, wraps long labels and uses Bootstrap's Dropdown keyboard and dismissal behavior. Supporting blocks render once and follow the article when the columns stack. Translate the labels for each document; logical spacing follows its text direction.
Runtime and placement
Import TableOfContents from @wpmoo/ui/toc.js and initialize each supplied [data-toc] root. Use refresh() after replacing targets and dispose() when removing a view. The previous @wpmoo/ui/table-of-contents.js entrypoint remains a compatibility re-export of the same constructor.
1
2
3
4
5
6
7
8import TableOfContents from "@wpmoo/ui/toc.js";
const reader = document.getElementById("main-content");
reader.classList.add("scroll-smooth");
document.querySelectorAll("[data-toc]").forEach(element => {
TableOfContents.getOrCreateInstance(element);
});
Importing the module alone does not initialize a document. For a JavaScript-disabled host, use the list.
content_id limits resolution to an explicit content region inside the same Moo owner. scroll_root_id identifies the scrolling ancestor of that content. Omitted values use the nearest Moo owner and document scrolling. A missing scope leaves the native links available and skips tracking.
The host owns fixed header geometry. With the App layout, place the compact navigation in the header above the scrolling main region, and supply that region's ID. For other layouts, a finite nonnegative activationOffset option sets the tracking line. The component does not change layout styles or override native scrolling.
For animated native fragment navigation, apply the Core scroll-smooth utility to the actual scroll container inside its Moo owner. The utility uses scroll-behavior and switches to immediate scrolling when the visitor prefers reduced motion. Links retain their native URL fragments and browser history.
Two presentations can share section data with unique IDs and complementary Bootstrap visibility utilities. Ordinary aside content renders once and can stack below the article on narrow screens.