docs: add support for meta header

Author: blaugold

docs/README.md

@@ -34,6 +34,22 @@ There are IDE plugins for Prettier that you can use to format code on save:
 - [IntelliJ](https://plugins.jetbrains.com/plugin/10456-prettier)
 - [VSCode](https://github.com/prettier/prettier-vscode)
 
+### Page Header
+
+Each page usually starts with a description of the content of the page and links
+to related content.
+
+This information has to be specified in the front-matter of the page:
+
+```
+---
+description: This is a description of the page.
+related_content:
+  - name: Related Content
+    url: /related/content
+---
+```
+
 ### Callouts
 
 For notes, warnings and other callouts, use
@@ -45,12 +61,7 @@ For notes, warnings and other callouts, use
 
 Code examples are titled code blocks with a unique ID.
 
-To use the `CodeExample` component, make sure it is imported at the top of the
-document:
-
-```
-import CodeExample from '@site/src/components/CodeExample'
-```
+The `CodeExample` component is available without importing it.
 
 Assign each code example a unique ID and give it a title:
 

docs/docs/install.md

@@ -1,7 +1,8 @@
-# Install
+---
+description: Installing Couchbase Lite for Dart
+---
 
-This guide will help you install Couchbase Lite and verify that everything is
-working correctly.
+# Install
 
 :::info
 

docs/docusaurus.config.js

@@ -5,6 +5,7 @@ require('ts-node').register()
 const lightCodeTheme = require('prism-react-renderer/themes/github')
 const darkCodeTheme = require('prism-react-renderer/themes/dracula')
 const { exampleLinks } = require('./src/remark/example-links')
+const { metaHeader } = require('./src/remark/meta-header')
 
 /** @type {import('@docusaurus/types').Config} */
 const config = {
@@ -31,7 +32,7 @@ const config = {
           sidebarPath: require.resolve('./sidebars.js'),
           routeBasePath: '/',
           editUrl: 'https://github.com/cbl-dart/cbl-dart/tree/main/docs/',
-          remarkPlugins: [exampleLinks],
+          remarkPlugins: [exampleLinks, metaHeader],
         },
         blog: false,
         theme: {

docs/package-lock.json

@@ -26,6 +26,7 @@
     "react": "^17.0.2",
     "react-dom": "^17.0.2",
     "ts-node": "^10.9.1",
+    "unist-util-flatmap": "^1.0.0",
     "unist-util-is": "^5.1.1",
     "unist-util-visit": "^4.1.1"
   },

docs/package.json

@@ -0,0 +1,37 @@
+import React from 'react'
+import { useMDXContent } from '../context'
+import styles from './styles.module.css'
+
+export default function MetaHeader() {
+  const content = useMDXContent()
+  const frontMatter = content.frontMatter
+  const description = frontMatter.description
+  const relatedContent = frontMatter.related_content
+
+  if (!description && !relatedContent) {
+    return <></>
+  }
+
+  return (
+    <div className={styles.metaHeader}>
+      {description && (
+        <div>
+          Description — <em>{description}</em>
+        </div>
+      )}
+      {relatedContent && (
+        <div>
+          Related Content —{' '}
+          {relatedContent.map(({ name, url }, index) => {
+            return (
+              <>
+                <a href={url}>{name}</a>
+                {index < relatedContent.length - 1 && ' | '}
+              </>
+            )
+          })}
+        </div>
+      )}
+    </div>
+  )
+}

docs/src/components/MetaHeader/index.tsx

@@ -0,0 +1,6 @@
+.metaHeader {
+  margin-bottom: 3rem;
+  padding-left: 1rem;
+  font-weight: 300;
+  border-left: 2px solid var(--ifm-color-emphasis-500);
+}

docs/src/components/MetaHeader/styles.module.css

@@ -0,0 +1,10 @@
+const React = require('react')
+
+export const MDXContent = React.createContext()
+
+/**
+ * Returns the MDX content of the current page, including frontmatter.
+ */
+export function useMDXContent() {
+  return React.useContext(MDXContent)
+}

docs/src/components/context.js

@@ -0,0 +1,26 @@
+const exampleRegex = /Example ([0-9]+)/
+
+/**
+ * Remark plugin that inserts the meta header under each level 1 heading.
+ */
+export function metaHeader() {
+  return async (ast: any) => {
+    // Workaround for import ES6 modules.
+    const is = (await import('unist-util-is')).is
+    const flatMap = (await import('unist-util-flatmap')).default
+
+    flatMap(ast, (node) => {
+      if (is(node, 'heading') && (node as any).depth == 1) {
+        return [
+          node,
+          {
+            type: 'html',
+            value: '<MetaHeader />',
+          },
+        ]
+      } else {
+        return [node]
+      }
+    })
+  }
+}

docs/src/remark/meta-header.ts

@@ -0,0 +1,12 @@
+import DocItem from '@theme-original/DocItem'
+import React from 'react'
+
+import { MDXContent } from '@site/src/components/context'
+
+export default function DocItemWrapper(props) {
+  return (
+    <MDXContent.Provider value={props.content}>
+      <DocItem {...props} />
+    </MDXContent.Provider>
+  )
+}

docs/src/theme/DocItem/index.js

@@ -0,0 +1,9 @@
+import CodeExample from '@site/src/components/CodeExample'
+import MetaHeader from '@site/src/components/MetaHeader'
+import MDXComponents from '@theme-original/MDXComponents'
+
+export default {
+  ...MDXComponents,
+  codeexample: CodeExample,
+  metaheader: MetaHeader,
+}