feature: Table of Contents

package.json

@@ -50,7 +50,10 @@
     "datocms-listen": "^0.1.15",
     "datocms-structured-text-utils": "^2.0.4",
     "get-video-id": "^3.6.5",
+    "github-slugger": "^2.0.0",
     "globby": "^13.2.2",
+    "hast-util-from-html": "^2.0.3",
+    "hast-util-to-string": "^3.0.1",
     "hls.js": "^1.5.2",
     "html-validate": "^8.7.4",
     "jiti": "^1.20.0",
@@ -59,7 +62,8 @@
     "promise-all-props": "^3.0.0",
     "regexparam": "^3.0.0",
     "rosetta": "^1.1.0",
-    "typescript": "^5.6.3"
+    "typescript": "^5.6.3",
+    "unist-util-visit": "^5.0.0"
   },
   "devDependencies": {
     "@astrojs/ts-plugin": "^1.10.2",

src/blocks/TextBlock/nodes/Heading.astro

@@ -1,5 +1,6 @@
 ---
 import type { Heading } from 'datocms-structured-text-utils';
+import HeadingComponent from '@components/Heading/Heading.astro';
 
 interface Props {
   node: Heading;
@@ -12,6 +13,5 @@ const minimumLevel = 2;
 const defaultLevel = 2;
 const level = Math.max(minimumLevel, (node.level || defaultLevel));
 
-const Tag = `h${level}`;
 ---
-<Tag><slot /></Tag>
+<HeadingComponent level={ level }><slot /></HeadingComponent>

src/blocks/index.ts

@@ -0,0 +1,7 @@
+import type { AnyBlock } from './Blocks';
+import { renderToString } from '@lib/renderer';
+import Blocks from './Blocks.astro';
+
+export const renderBlocks = async (blocks: AnyBlock[]) => {
+  return await renderToString(Blocks, { props: { blocks } });
+};

src/components/Heading/Heading.astro

@@ -0,0 +1,20 @@
+---
+import type { HTMLTag } from 'astro/types';
+import type { Heading } from 'datocms-structured-text-utils';
+import { htmlIdSlug } from '@components/HtmlIdSlugProvider/';
+
+interface Props {
+  id: string;
+  level: Heading['level'];
+}
+const { id, level = 2, ...props } = Astro.props;
+
+const slug = htmlIdSlug({
+  id,
+  html: await Astro.slots.render('default')
+});
+
+const Tag = `h${level}` as HTMLTag;
+---
+
+<Tag {...props} id={ slug } tabindex="-1"><slot /></Tag>

src/components/HtmlIdSlugProvider/HtmlIdSlugProvider.astro

@@ -0,0 +1,7 @@
+---
+import { resetHtmlIdSlugger } from './index';
+
+resetHtmlIdSlugger();
+---
+
+<slot />

src/components/HtmlIdSlugProvider/index.ts

@@ -0,0 +1,18 @@
+import GithubSlugger from 'github-slugger';
+import { fromHtml } from 'hast-util-from-html';
+import { toString } from 'hast-util-to-string';
+
+const slugger = new GithubSlugger();
+
+export const resetHtmlIdSlugger = () => {
+  slugger.reset();
+};
+
+export const htmlIdSlug = ({ id, html }: { id?: string; html: string }) => {
+  if (id) {
+    return slugger.slug(id);
+  }
+  const tree = fromHtml(html, { fragment: true });
+  const text = toString(tree);
+  return slugger.slug(text);
+};

src/components/TableOfContents/List.astro

@@ -0,0 +1,19 @@
+---
+import type { TreeItem } from './index';
+
+interface Props {
+  items: TreeItem[];
+}
+const { items } = Astro.props;
+---
+
+<ol>
+  { items.map((item) => (
+    <li class:list={[ `level-${item.level}` ]}>
+      <a href={ `#${ item.id }` }>{ item.text }</a>
+      { item.items && (
+        <Astro.self items={ item.items } />
+      ) }
+    </li>
+  )) }
+</ol>

src/components/TableOfContents/README.md

@@ -0,0 +1,3 @@
+# Table of Contents
+
+**Render a list of links to headings in a given HTML string.**

src/components/TableOfContents/TableOfContents.astro

@@ -0,0 +1,13 @@
+---
+import { t } from '@lib/i18n';
+import { extractTocItemsFromHtml } from './index';
+import List from './List.astro';
+
+const { html } = Astro.props;
+const items = extractTocItemsFromHtml(html);
+---
+
+<nav>
+  <h2>{ t('table_of_contents') }</h2>
+  <List items={ items } />
+</nav>

src/components/TableOfContents/index.ts

@@ -0,0 +1,37 @@
+import { fromHtml } from 'hast-util-from-html';
+import { toString } from 'hast-util-to-string';
+import { visit } from 'unist-util-visit';
+
+export type TreeItem = {
+  id: string;
+  level: number;
+  text: string;
+  items?: TreeItem[];
+};
+
+export const extractTocItemsFromHtml = (html: string) => {
+
+  const hast = fromHtml(html, { fragment: true });
+  const tagNames = new Set(['h1', 'h2', 'h3', 'h4', 'h5', 'h6']);
+  const items: TreeItem[] = [];
+
+  visit(hast, 'element', (node) => {
+    if (tagNames.has(node.tagName) && node.properties?.id) {
+      const text = toString(node);
+      const item: TreeItem = {
+        id: String(node.properties.id),
+        level: parseInt(node.tagName.slice(1), 10),
+        text,
+      };
+      const lastItem = items[items.length - 1];
+      if (lastItem && lastItem.level < item.level) {
+        lastItem.items = lastItem.items ?? [];
+        lastItem.items.push(item);
+      } else {
+        items.push(item);
+      }
+    }
+  });
+
+  return items;
+};

src/layouts/Default.astro

@@ -9,6 +9,7 @@ import type { PageUrl } from '@lib/seo';
 import query from './default.query.graphql';
 import Breadcrumbs from '@components/Breadcrumbs/Breadcrumbs.astro';
 import type { Breadcrumb } from '@components/Breadcrumbs';
+import HtmlIdSlugProvider from '@components/HtmlIdSlugProvider/HtmlIdSlugProvider.astro';
 import IconSprite from '@components/Icon/IconSprite.astro';
 import LocaleSelector from '@components/LocaleSelector/LocaleSelector.astro';
 import PreviewModeProvider from '@components/PreviewMode/PreviewModeProvider.astro';
@@ -42,25 +43,27 @@ const mainContentId = 'content';
   </head>
   <body>
     <PreviewModeProvider>
-      <SkipLink targetId={ mainContentId } />
-      <header { ...datocmsNoIndex }>
-        { /* accessible home link, inspired by https://www.gov.uk/; with Microformats rel */ }
-        <a rel="home" href={ getHomeHref() } aria-label={ t('go_to_home_page', { siteName }) }>[Logo]</a>
-        <div>
-          <LocaleSelector pageUrls={ pageUrls } />
-          <a rel="search" href={ getSearchPathname(locale) }>{ t('search') }</a>
-        </div>
-      </header>
-      { (breadcrumbs.length > 0) && (
-        <Breadcrumbs items={breadcrumbs} />
-      ) }
-      { /* main element requires tabindex to be focusable, see SkipLink/README.md */ }
-      <main id={ mainContentId } tabindex="-1">
-        <slot />
-      </main>
-      <footer { ...datocmsNoIndex }>
-        <p>Footer</p>
-      </footer>
+      <HtmlIdSlugProvider>
+        <SkipLink targetId={ mainContentId } />
+        <header { ...datocmsNoIndex }>
+          { /* accessible home link, inspired by https://www.gov.uk/; with Microformats rel */ }
+          <a rel="home" href={ getHomeHref() } aria-label={ t('go_to_home_page', { siteName }) }>[Logo]</a>
+          <div>
+            <LocaleSelector pageUrls={ pageUrls } />
+            <a rel="search" href={ getSearchPathname(locale) }>{ t('search') }</a>
+          </div>
+        </header>
+        { (breadcrumbs.length > 0) && (
+          <Breadcrumbs items={breadcrumbs} />
+        ) }
+        { /* main element requires tabindex to be focusable, see SkipLink/README.md */ }
+        <main id={ mainContentId } tabindex="-1">
+          <slot />
+        </main>
+        <footer { ...datocmsNoIndex }>
+          <p>Footer</p>
+        </footer>
+      </HtmlIdSlugProvider>
     </PreviewModeProvider>
     <IconSprite />
   </body>

src/lib/routing/html-id-slugger.ts

@@ -0,0 +1,18 @@
+import GithubSlugger from 'github-slugger';
+import { fromHtml } from 'hast-util-from-html';
+import { toString } from 'hast-util-to-string';
+
+const slugger = new GithubSlugger();
+
+export const resetHtmlIdSlugger = () => {
+  slugger.reset();
+};
+
+export const htmlIdSlug = ({ id, html }: { id?: string; html: string }) => {
+  if (id) {
+    return slugger.slug(id);
+  }
+  const tree = fromHtml(html, { fragment: true });
+  const text = toString(tree);
+  return slugger.slug(text);
+};

src/pages/[locale]/[...path]/index.astro

@@ -1,15 +1,16 @@
 ---
-import { datocmsCollection, datocmsRequest } from '@lib/datocms';
 import { type PageRouteForPath, getPagePath, getPageSlugFromPath, getParentPages } from '@lib/routing/page';
 import type { PageQuery, SiteLocale } from '@lib/types/datocms';
 import type { PageUrl } from '@lib/types/page-url';
+import { datocmsCollection, datocmsRequest } from '@lib/datocms';
 import Layout from '@layouts/Default.astro';
-import Blocks from '@blocks/Blocks.astro';
+import { renderBlocks } from '@blocks/index';
 import type { AnyBlock } from '@blocks/Blocks';
 
 import { formatBreadcrumb } from '@components/Breadcrumbs';
 import PreviewModeSubscription from '@components/PreviewMode/PreviewModeSubscription.astro';
 import ShareButton from '@components/ShareButton/ShareButton.astro';
+import TableOfContents from '@components/TableOfContents/TableOfContents.astro';
 import query from './_index.query.graphql';
 
 export async function getStaticPaths() {
@@ -63,6 +64,8 @@ const pageUrls = (page._allSlugLocales || []).map(({ locale }) => ({
     locale: locale as SiteLocale,
   })}/`,
 })) as PageUrl[];
+
+const blocksHtml = await renderBlocks(page.bodyBlocks as AnyBlock[]);
 ---
 
 <Layout
@@ -72,6 +75,7 @@ const pageUrls = (page._allSlugLocales || []).map(({ locale }) => ({
 >
   <PreviewModeSubscription query={query} variables={variables} />
   <h1>{page.title}</h1>
-  <Blocks blocks={page.bodyBlocks as AnyBlock[]} />
+  <TableOfContents html={ blocksHtml } />
+  <Fragment set:html={blocksHtml} />
   <ShareButton />
 </Layout>

src/pages/[locale]/index.astro

@@ -5,10 +5,11 @@ import type { PageUrl } from '@lib/types/page-url';
 import { locales } from '@lib/i18n';
 import { getHomeHref } from '@lib/routing';
 import Layout from '@layouts/Default.astro';
-import Blocks from '@blocks/Blocks.astro';
+import { renderBlocks } from '@blocks/index';
 import type { AnyBlock } from '@blocks/Blocks';
 import PreviewModeSubscription from '@components/PreviewMode/PreviewModeSubscription.astro';
 import ShareButton from '@components/ShareButton/ShareButton.astro';
+import TableOfContents from '@components/TableOfContents/TableOfContents.astro';
 import query from './_index.query.graphql';
 
 export async function getStaticPaths() {
@@ -25,11 +26,13 @@ const pageUrls = locales.map((locale) => ({
   locale,
   pathname: getHomeHref({ locale }),
 })) as PageUrl[];
+const blocksHtml = await renderBlocks(page.bodyBlocks as AnyBlock[]);
 ---
 
 <Layout pageUrls={pageUrls} seoMetaTags={page._seoMetaTags}>
   <PreviewModeSubscription query={query} variables={variables} />
   <h1>{page.title}</h1>
-  <Blocks blocks={page.bodyBlocks as AnyBlock[]} />
+  <TableOfContents html={ blocksHtml } />
+  <Fragment set:html={blocksHtml} />
   <ShareButton />
 </Layout>