climateinteractive · chrispcampbell · Apr 9, 2024 · Apr 9, 2024
diff --git a/examples/sample-docs/projects/_shared/src/fragment-example.html b/examples/sample-docs/projects/_shared/src/fragment-example.html
@@ -0,0 +1,2 @@
+<!-- This HTML fragment will be inserted into the `<head>` element when the Markdown page -->
+<!-- includes `fragment: head: ['example']` in the frontmatter. -->
diff --git a/examples/sample-docs/projects/_shared/src/template-default.html b/examples/sample-docs/projects/_shared/src/template-default.html
@@ -24,6 +24,8 @@
   <script src="${ASSET-search.js}"></script>
   <script src="${ASSET-support.js}"></script>
 
+<!-- {HEAD FRAGMENTS} -->
+
   <script>
     function onSearch(searchTerm) {
       performSearch(searchTerm, '${BASE_PATH}');

diff --git a/examples/sample-docs/projects/sample-guide/content/page_1.md b/examples/sample-docs/projects/sample-guide/content/page_1.md
@@ -1,3 +1,8 @@
+---
+fragments:
+  head: ['example']
+---
+
 # <!-- section:page_1 --><!-- def:title -->Page 1
 
 <!-- def:intro -->

diff --git a/packages/docs-builder/package.json b/packages/docs-builder/package.json
@@ -39,6 +39,7 @@
     "find-up": "^6.3.0",
     "gettext-parser": "^5.0.0",
     "glob": "^8.0.3",
+    "gray-matter": "^4.0.3",
     "lunr": "^2.3.9",
     "lunr-languages": "^1.9.0",
     "mark.js": "^8.11.1",

diff --git a/packages/docs-builder/src/gen-html.ts b/packages/docs-builder/src/gen-html.ts
@@ -127,13 +127,17 @@ export function generateHtml(context: Context, mdRelPath: string, mdPage: Markdo
   // Convert the Markdown content to HTML
   const body = convertMarkdownToHtml(context, md)
 
+  // Save the names of the `<head>` fragments to include
+  const headFragments = mdPage.frontmatter?.fragments?.head || []
+
   // Clear the current page
   context.setCurrentPage(undefined)
 
   return {
     baseName,
     relPath: htmlRelPath,
-    body
+    body,
+    headFragments
   }
 }
 
@@ -308,7 +312,17 @@ export function writeHtmlFile(
   // Build the final HTML file by replacing fields in the template
   const templateFile = `template-${templateName}.html`
   const templatePath = resolvePath(context.config.sourceDir, templateFile)
-  const htmlTemplate = readTextFile(templatePath)
+  const htmlTemplateRaw = readTextFile(templatePath)
+  let headSlot = ''
+  if (htmlPage.headFragments) {
+    // Insert fragments into the `<head>` slot
+    for (const fragmentName of htmlPage.headFragments) {
+      const fragmentPath = resolvePath(context.config.sourceDir, `fragment-${fragmentName}.html`)
+      const fragmentHtml = readTextFile(fragmentPath)
+      headSlot += fragmentHtml + '\n'
+    }
+  }
+  const htmlTemplate = htmlTemplateRaw.replace('<!-- {HEAD FRAGMENTS} -->', headSlot)
   const html = htmlTemplate.replaceAll(/\${([a-zA-Z0-9._-]*)}/g, (_substring, id) => {
     if (id.startsWith('ASSET-')) {
       // Assets are specified like `${ASSET-my-image.png}`; remap to the full relative path to

diff --git a/packages/docs-builder/src/parse.ts b/packages/docs-builder/src/parse.ts
@@ -1,7 +1,9 @@
 // Copyright (c) 2022 Climate Interactive / New Venture Fund
 
 import { resolve } from 'path'
+import matter from 'gray-matter'
 import { marked } from 'marked'
+
 import type { BlockId } from './block'
 import type { Command } from './command'
 import type { Context } from './context'
@@ -46,7 +48,12 @@ export function parseMarkdownPage(context: Context, relPath: string): MarkdownPa
 
   // Read the Markdown file
   const filePath = resolve(context.config.baseProjDir, relPath)
-  const origMarkdown = readTextFile(filePath)
+  const origMarkdownWithFrontmatter = readTextFile(filePath)
+
+  // Separate frontmatter from the content
+  const origMarkdownSeparated = matter(origMarkdownWithFrontmatter)
+  const origMarkdown = origMarkdownSeparated.content
+  const frontmatter = origMarkdownSeparated.data
 
   // Append synthesized link info for glossary references so that source files can
   // use `[link text][glossary_term]` without manually defining a reference for
@@ -81,7 +88,8 @@ export function parseMarkdownPage(context: Context, relPath: string): MarkdownPa
   context.setCurrentPage(undefined)
 
   return {
-    raw: outMarkdown
+    raw: outMarkdown,
+    frontmatter
   }
 }
 

diff --git a/packages/docs-builder/src/types.ts b/packages/docs-builder/src/types.ts
@@ -2,12 +2,20 @@
 
 export type LangCode = string
 
+export type Frontmatter = {
+  fragments?: {
+    head?: string[]
+  }
+}
+
 export interface MarkdownPage {
   raw: string
+  frontmatter?: Frontmatter
 }
 
 export interface HtmlPage {
   baseName: string
   relPath: string
   body: string
+  headFragments?: string[]
 }
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		<!-- This HTML fragment will be inserted into the `<head>` element when the Markdown page -->
		<!-- includes `fragment: head: ['example']` in the frontmatter. -->