0.2.1

.gitea/workflows/build-and-pubilsh.yaml

@@ -0,0 +1,36 @@
+
+name: Build and publish
+
+on:
+- workflow_dispatch
+  # push:
+  #   branches:
+  #   - master
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    env:
+      NPM_PUBLISH_TOKEN: ${{ secrets.NPM_TOKEN }}
+    steps:
+      - name: Check out the repo
+        uses: actions/checkout@v3
+
+      - name: Use Node.js 20
+        uses: actions/setup-node@v3
+        with:
+          node-version: 20
+
+      - name: Login to package registry
+        run: |
+          npm config set @doc-utils:registry https://gitea.jbrumond.me/api/packages/doc-utils/npm/
+          npm config set -- '//gitea.jbrumond.me/api/packages/doc-utils/npm/:_authToken' "$NPM_PUBLISH_TOKEN"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Compile TypeScript
+        run: npm run tsc
+
+      - name: Publish package
+        run: npm publish

.gitea/workflows/build-and-test.yaml

@@ -0,0 +1,40 @@
+
+name: Build and test
+
+on:
+  push:
+    branches:
+    - master
+  pull_request:
+    branches:
+    - master
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [18.x, 20.x]
+    steps:
+      - name: Check out the repo
+        uses: actions/checkout@v3
+
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v3
+        with:
+          node-version: ${{ matrix.node-version }}
+
+      - name: Login to package registry
+        run: |
+          npm config set @doc-utils:registry https://gitea.jbrumond.me/api/packages/doc-utils/npm/
+          npm config set -- '//gitea.jbrumond.me/api/packages/doc-utils/npm/:_authToken' "$NPM_PUBLISH_TOKEN"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Compile TypeScript
+        run: npm run tsc
+
+      # todo: tests
+      - name: Run tests
+        run: exit 0

extras/components/outline-button.js

@@ -116,9 +116,16 @@
 		const outline = [ ];
 
 		for (const heading of headings) {
+			const content = heading.cloneNode(true);
+			const anchor = content.querySelector('a.heading-anchor');
+
+			if (anchor) {
+				anchor.parentNode.removeChild(anchor);
+			}
+
 			outline.push(`
 			<li data-depth="${heading.tagName.toLowerCase()}">
-				<a href="#${heading.id}">${heading.innerText}</a>
+				<a href="#${heading.id}">${content.innerHTML}</a>
 			</li>
 			`);
 		}

extras/components/outline-inline.js

@@ -92,9 +92,16 @@
 		const outline = [ ];
 
 		for (const heading of headings) {
+			const content = heading.cloneNode(true);
+			const anchor = content.querySelector('a.heading-anchor');
+
+			if (anchor) {
+				anchor.parentNode.removeChild(anchor);
+			}
+
 			outline.push(`
 			<li data-depth="${heading.tagName.toLowerCase()}">
-				<a href="#${heading.id}">${heading.innerText}</a>
+				<a href="#${heading.id}">${content.innerHTML}</a>
 			</li>
 			`);
 		}

extras/figures.css

@@ -0,0 +1,163 @@
+
+figure[data-lang] {
+	margin-block: 2rem;
+}
+
+figure a.view-svg {
+	font-size: 0.85rem;
+	font-family: var(--font-body);
+}
+
+figure[data-lang] svg {
+	display: block;
+	margin-inline: auto;
+	margin-block: 2rem;
+
+	/* The auto-scaling font-size from typography/*.css does bad things to a lot of SVGs.
+	 * The SVGs themselves are inherently scalable, so there is no need for it here anyway. */
+	font-size: 16px !important;
+}
+
+figure[data-size='medium']:has(svg) {
+	margin-block: 4rem;
+}
+
+figure[data-size='large'] {
+	margin-block: 6rem;
+}
+
+figure[data-size='small'] svg {
+	max-width: 40rem;
+	max-height: min(20rem, 50vw);
+}
+
+figure[data-size='medium'] svg {
+	max-width: 60rem;
+	max-height: min(40rem, 50vw);
+}
+
+figure[data-size='large'] svg {
+	max-height: min(60rem, 80vw);
+}
+
+/* figure[data-lang].big {
+	background: var(--theme-bg-main);
+	position: fixed;
+	top: 0;
+	bottom: 0;
+	left: 0;
+	right: 0;
+	z-index: 1000;
+	display: flex;
+	border: 0.25rem var(--theme-line) solid;
+	margin: 3rem;
+}
+
+figure[data-lang].big svg {
+	max-width: none !important;
+	max-height: none !important;
+} */
+
+/* figure:is([data-lang='pikchr'], [data-lang='nomnoml'], [data-lang='bytefield']) svg text:not([fill^='var']) { */
+figure:is([data-lang='pikchr'], [data-lang='nomnoml'], [data-lang='bytefield']) svg text {
+	fill: var(--theme-text-body);
+}
+
+figure:is([data-lang='pikchr'], [data-lang='nomnoml'], [data-lang='bytefield']) svg text:not([font-family~='Courier']) {
+	font-family: var(--font-body);
+}
+
+[data-lang='bash:samp'] samp {
+	display: block;
+	margin-block-start: 0.5rem;
+	padding-block-start: 0.5rem;
+	border-block-start: 0.1rem solid var(--theme-line);
+}
+
+/* === KaTeX === */
+
+.katex-display {
+	color: var(--theme-text-body);
+}
+
+.katex-display .katex {
+	font-size: 1.4rem;
+}
+
+/* using "body" here to add specificity, to override styles from katex.min.css */
+body .katex-display {
+	margin: 2rem;
+}
+
+body figure.align-left .katex-display > .katex {
+	text-align: left;
+}
+
+body figure.align-right .katex-display > .katex {
+	text-align: right;
+}
+
+:not(.katex-display) > .katex {
+	font-size: inherit;
+	margin-inline: 0.5rem;
+}
+
+.katex span[style~='color:transparent;'] {
+	user-select: none;
+}
+
+/* === Pikchr */
+
+/* boxes */
+figure[data-lang='pikchr'] svg path[style*='fill:none;'] {
+	fill: var(--theme-bg-light) !important;
+	transition: fill linear .5s;
+}
+
+/* lines and boxes */
+figure[data-lang='pikchr'] svg path[style*='stroke:rgb(0,0,0);'] {
+	stroke: var(--theme-text-body) !important;
+}
+
+/* circles */
+figure[data-lang='pikchr'] svg circle[style*='stroke:rgb(0,0,0);'] {
+	stroke: var(--theme-text-body) !important;
+}
+
+/* arrow heads */
+figure[data-lang='pikchr'] svg polygon[style='fill:rgb(0,0,0)'] {
+	fill: var(--theme-text-body) !important;
+	transition: fill linear .5s;
+}
+
+/* === Bytefield === */
+
+figure[data-lang='clojure:bytefield'] svg line[stroke-width='1'] {
+	stroke-width: 2;
+}
+
+figure[data-lang='clojure:bytefield'] svg :is(text, tspan)[font-size='11'] {
+	font-size: 14px;
+}
+
+figure[data-lang='clojure:bytefield'] svg :is(text, tspan)[font-size='18'] {
+	font-size: 16px;
+}
+
+figure[data-lang='clojure:bytefield'] svg :is(text, tspan)[font-family~='Courier'] {
+	font-family: var(--font-monospace);
+}
+
+figure[data-lang='clojure:bytefield'] svg :is(text, tspan)[font-family~='Times'] {
+	font-family: var(--font-body);
+}
+
+figure[data-lang='clojure:bytefield'] svg line[stroke-dasharray='1,1'] {
+	stroke-dasharray: 4px, 3px;
+}
+
+figure[data-lang='clojure:bytefield'] svg line[stroke-dasharray='1,3'] {
+	stroke-dasharray: 2px, 3px;
+}
+
+

extras/svg-links.js

@@ -0,0 +1,58 @@
+(() => {
+	
+	if (document.readyState === 'complete') {
+		add_svg_links();
+	}
+
+	else {
+		window.addEventListener('DOMContentLoaded', add_svg_links);
+	}
+
+	function add_svg_links() {
+		const svg_elems = document.querySelectorAll('figure > svg');
+
+		for (const svg_elem of svg_elems) {
+			const figure_elem = svg_elem.parentElement;
+			const anchor_elem = document.createElement('a');
+			const lang = figure_elem.getAttribute('data-lang') || '';
+
+			let svg_html;
+
+			if ('svg_link_css' in window) {
+				const svg_clone = svg_elem.cloneNode(true);
+				const style_elem = document.createElement('style');
+				svg_clone.insertBefore(style_elem, svg_clone.firstChild);
+
+				const css
+					= (window.svg_link_css['*'] || '')
+					+ (lang ? window.svg_link_css[lang] || '' : '');
+	
+				style_elem.setAttribute('type', 'text/css');
+				style_elem.appendChild(document.createTextNode(css));
+
+				svg_html = svg_clone.outerHTML;
+			}
+
+			else {
+				svg_html = svg_elem.outerHTML;
+			}
+			
+			const box = document.createElement('div');
+			const svg_xml = '<?xml version="1.0" standalone="no" ?>\r\n'
+				+ svg_html.replace(/(&(?!(amp|gt|lt|quot|apos))[^;]+;)/g, ($0, $1) => {
+					box.innerHTML = $0;
+					return box.textContent;
+				});
+
+			const svg_blob = new Blob([ svg_xml ], { type: 'image/svg+xml; charset=utf-8' });
+			const svg_object_url = URL.createObjectURL(svg_blob);
+
+			anchor_elem.href = svg_object_url;
+			anchor_elem.className = 'view-svg';
+			anchor_elem.textContent = 'View / Download Graphic';
+
+			figure_elem.insertBefore(anchor_elem, svg_elem);
+		}
+	}
+
+})();

extras/typography/compact.css

@@ -52,3 +52,50 @@ li {
 	line-height: 1.5;
 	margin-block: 0.25rem;
 }
+
+dl {
+	padding: 1rem;
+}
+
+dd + dt {
+	margin-block-start: 1rem;
+}
+
+:is(dt, dd) > p {
+	line-height: 1.5;
+	margin-block-start: 0;
+	margin-block-end: 0.15rem;
+}
+
+
+
+
+
+/* ===== Figure Captions ===== */
+
+figcaption {
+	margin-block-start: 1.5rem;
+}
+
+
+
+/* ===== Pre-formatted Blocks ===== */
+
+pre {
+	padding: 0.5rem;
+	margin-block: 1.5rem;
+}
+
+
+
+
+
+/* ===== Note Blocks ===== */
+
+:is(aside, section):is([role='note'], .info, .highlight, .warning, .problem) > :first-child {
+	margin-block-start: 0.25rem;
+}
+
+:is(aside, section):is([role='note'], .info, .highlight, .warning, .problem) > :last-child {
+	margin-block-end: 0.25rem;
+}

extras/typography/general.css

@@ -80,12 +80,23 @@ p {
 
 
 
+/* ===== Inline Styles ===== */
+
+del {
+	text-decoration: line-through;
+}
+
+
+
 
 /* ===== Links ===== */
 
 a {
 	font-family: inherit;
 	color: var(--theme-text-link);
+	display: inline;
+	align-items: center;
+	column-gap: 0.2rem;
 }
 
 a:active,
@@ -98,7 +109,8 @@ a:visited {
 	color: var(--theme-text-link-visited);
 }
 
-a.icon-link {
+a.icon-link,
+a.inline-flex {
 	display: inline-flex;
 	column-gap: 0.3rem;
 	align-items: center;
@@ -108,6 +120,10 @@ a.icon-link svg.icon {
 	--icon-size: 1rem;
 }
 
+del a {
+	text-decoration: line-through underline;
+}
+
 
 
 
@@ -137,38 +153,10 @@ ul[role='doc-endnotes'] {
 	background: var(--theme-bg-heavy);
 }
 
-dl {
-	padding: 1rem;
-}
-
-dt, dd {
-	/*  */
-}
-
 dt {
 	font-weight: 700;
 }
 
-dt p {
-	margin-block-end: 1rem;
-}
-
-dt:not(:first-of-type) {
-	margin-block-start: 2rem;
-}
-
-/* dd {
-	margin-inline-start: 1rem;
-	padding-inline-start: 1rem;
-	padding-block: 0.125rem;
-	border-inline-start: 0.5rem var(--theme-line) solid;
-	background: var(--theme-bg-heavy)
-} */
-
-dd p {
-	margin-block: 1rem;
-}
-
 .cite-label {
 	font-weight: 600;
 }
@@ -205,64 +193,64 @@ mark {
 
 /* ===== Tables ===== */
 
-table, .table, td, .td {
+table, .faux-table, td, .faux-td {
 	color: var(--theme-text-body);
 	font-family: var(--font-body);
 }
 
-table, .table {
+table, .faux-table {
 	display: table;
 	margin-block: 2rem;
 	border-collapse: collapse;
 }
 
 table, th, td,
-.table, .th, .td {
+.faux-table, .faux-th, .faux-td {
 	font-size: 1rem;
 	line-height: 1.75;
 }
 
-thead, .thead {
+thead, .faux-thead {
 	display: table-header-group;
 }
 
-tbody, .tbody {
+tbody, .faux-tbody {
 	display: table-row-group;
 }
 
 tbody tr,
-.tbody .tr {
+.faux-tbody .faux-tr {
 	border-top: 1px var(--theme-line) solid;
 }
 
-tr, .tr {
+tr, .faux-tr {
 	display: table-row;
 }
 
-th, .th {
+th, .faux-th {
 	text-align: center;
 	font-weight: 700;
 	color: var(--theme-text-heading);
 }
 
-th, .th,
-td, .td {
+th, .faux-th,
+td, .faux-td {
 	padding-block: 0.5rem;
 	padding-inline: 1rem;
 	display: table-cell;
 }
 
-td, .td {
+td, .faux-td {
 	display: table-cell;
 	font-weight: 300;
 	vertical-align: top;
 }
 
-:is(td, .td):not(:last-of-type) {
+:is(td, .faux-td):not(:last-of-type) {
 	border-inline-end: 0.1rem solid var(--theme-line);
 }
 
-:is(table, .table) :is(input, select) {
+:is(table, .faux-table) :is(input, select) {
 	margin-block: 0;
 }
 
@@ -280,24 +268,28 @@ table dl {
 pre {
 	color: var(--theme-code-normal);
 	font-family: var(--font-monospace);
-	margin-block: 3rem;
-	margin-inline: 2rem;
-	padding-block: 0.5rem;
-	padding-inline: 1rem;
+	margin-inline-start: 1rem;
+	margin-inline-end: 5rem;
 	border: 0.1rem solid var(--theme-line);
-	border-radius: 1rem;
+	border-radius: 0.5rem;
 	font-size: 1rem;
 	overflow: auto;
 	background: var(--theme-bg-light);
 }
 
+@media screen and (max-width: 60rem) {
+	pre {
+		margin-inline: 0;
+	}
+}
+
 
 
 
 /* ===== Code / Sample Output ===== */
 
 code, samp {
-	font-size: 1rem;
+	font-size: inherit;
 	color: var(--theme-code-normal);
 	font-family: var(--font-monospace);
 }
@@ -305,8 +297,11 @@ code, samp {
 :not(pre) > :is(code, samp) {
 	color: inherit;
 	background: var(--theme-bg-light);
+	margin-inline: 0.15rem;
+	padding-block: 0.1rem;
 	padding-inline: 0.25rem;
 	border: 0.1rem solid var(--theme-line);
+	border-radius: 0.2rem;
 }
 
 
@@ -351,7 +346,6 @@ figcaption {
 	font-family: var(--font-body);
 	text-align: center;
 	font-size: 0.85rem;
-	margin-block-start: 1rem;
 	color: var(--theme-text-light);
 	max-width: 60vw;
 	margin-inline: auto;

extras/typography/spacious.css

@@ -45,6 +45,20 @@ p {
 
 
 
+/* ===== Note Blocks ===== */
+
+:is(aside, section):is([role='note'], .info, .highlight, .warning, .problem) > :first-child {
+	margin-block-start: 0.5rem;
+}
+
+:is(aside, section):is([role='note'], .info, .highlight, .warning, .problem) > :last-child {
+	margin-block-end: 0.5rem;
+}
+
+
+
+
+
 
 /* ===== Lists ===== */
 
@@ -52,3 +66,36 @@ li {
 	line-height: 1.75;
 	margin-block: 0.5rem;
 }
+
+dl {
+	padding: 1rem;
+}
+
+dd + dt {
+	margin-block-start: 1.25rem;
+}
+
+:is(dt, dd) > p {
+	margin-block-start: 0;
+	margin-block-end: 0.25rem;
+}
+
+
+
+
+
+/* ===== Figure Captions ===== */
+
+figcaption {
+	margin-block-start: 2rem;
+}
+
+
+
+/* ===== Pre-formatted Blocks ===== */
+
+pre {
+	margin-block: 2rem;
+	padding-block: 0.5rem;
+	padding-inline: 1rem;
+}

package-lock.json

@@ -1,17 +1,19 @@
 {
   "name": "@doc-utils/docs2website",
-  "version": "0.1.3",
+  "version": "0.2.1",
   "lockfileVersion": 2,
   "requires": true,
   "packages": {
     "": {
       "name": "@doc-utils/docs2website",
-      "version": "0.1.3",
+      "version": "0.2.1",
       "dependencies": {
-        "@doc-utils/color-themes": "^0.1.14",
+        "@doc-utils/color-themes": "^0.2.0",
         "@doc-utils/jsonschema2markdown": "^0.1.1",
-        "@doc-utils/markdown2html": "^0.2.1",
+        "@doc-utils/markdown2html": "^0.3.6",
         "glob": "^10.2.3",
+        "ical": "^0.8.0",
+        "ical-generator": "^4.1.0",
         "luxon": "^3.3.0",
         "mustache": "^4.2.0",
         "xmlbuilder2": "^3.1.1",
@@ -21,6 +23,7 @@
         "docs2website": "bin/docs2website"
       },
       "devDependencies": {
+        "@types/ical": "^0.8.0",
         "@types/jsdom": "^20.0.1",
         "@types/luxon": "^3.3.0",
         "@types/mustache": "^4.2.2",
@@ -30,9 +33,9 @@
       }
     },
     "node_modules/@doc-utils/color-themes": {
-      "version": "0.1.14",
-      "resolved": "https://gitea.jbrumond.me/api/packages/doc-utils/npm/%40doc-utils%2Fcolor-themes/-/0.1.14/color-themes-0.1.14.tgz",
-      "integrity": "sha512-j0U8v8Y+9zAm9D7pbCheTQYGEKt9FSpKSZQNGsogxWl95S9Z7QMjtmJns6QPgdOsSDss7sjMLFS5Gm50GCMzNA=="
+      "version": "0.2.0",
+      "resolved": "https://gitea.jbrumond.me/api/packages/doc-utils/npm/%40doc-utils%2Fcolor-themes/-/0.2.0/color-themes-0.2.0.tgz",
+      "integrity": "sha512-UtjY25B8m4qdMvrmTPK3I1JXckbc1cvCOmIygHFBexpSWBQmb+sdoXfdCsoSpgPncurz1kwlEXffgPELCGtP8g=="
     },
     "node_modules/@doc-utils/jsonschema2markdown": {
       "version": "0.1.1",
@@ -48,9 +51,9 @@
       }
     },
     "node_modules/@doc-utils/markdown2html": {
-      "version": "0.2.6",
-      "resolved": "https://gitea.jbrumond.me/api/packages/doc-utils/npm/%40doc-utils%2Fmarkdown2html/-/0.2.6/markdown2html-0.2.6.tgz",
-      "integrity": "sha512-6cQNzthYOOlkT6rr6E1lpSJ4Zq991+chblSRxv69SVT8y5cIs6c9tFu75MXoIKX4+H68Q4i10gtMrrsXD+bkaA==",
+      "version": "0.3.6",
+      "resolved": "https://gitea.jbrumond.me/api/packages/doc-utils/npm/%40doc-utils%2Fmarkdown2html/-/0.3.6/markdown2html-0.3.6.tgz",
+      "integrity": "sha512-LCt5HAAcHz6lE+IqV2igQP7bbTq1juNbyn4KWqn3xe9eSslIyl7EvSaEH68WQtqEzX/iVFOvZz7qSoqsQeggXA==",
       "dependencies": {
         "bytefield-svg": "^1.6.1",
         "dompurify": "^2.3.6",
@@ -63,6 +66,9 @@
         "qrcode": "^1.5.1",
         "vega": "^5.22.1",
         "yaml": "^2.2.2"
+      },
+      "bin": {
+        "markdown2html": "bin/markdown2html"
       }
     },
     "node_modules/@isaacs/cliui": {
@@ -152,6 +158,43 @@
       "resolved": "https://registry.npmjs.org/@types/geojson/-/geojson-7946.0.4.tgz",
       "integrity": "sha512-MHmwBtCb7OCv1DSivz2UNJXPGU/1btAWRKlqJ2saEhVJkpkvqHMMaOpKg0v4sAbDWSQekHGvPVMM8nQ+Jen03Q=="
     },
+    "node_modules/@types/ical": {
+      "version": "0.8.0",
+      "resolved": "https://registry.npmjs.org/@types/ical/-/ical-0.8.0.tgz",
+      "integrity": "sha512-46KAYxAwRuCh+jRgl9k5cTaXJJkB16gWpvMVPuog9UBBb2zXTf9M0MsfWYBQ21JohFSuMZfPTvk6tohqGr1tCg==",
+      "dev": true,
+      "dependencies": {
+        "rrule": "2.6.4"
+      }
+    },
+    "node_modules/@types/ical/node_modules/luxon": {
+      "version": "1.28.1",
+      "resolved": "https://registry.npmjs.org/luxon/-/luxon-1.28.1.tgz",
+      "integrity": "sha512-gYHAa180mKrNIUJCbwpmD0aTu9kV0dREDrwNnuyFAsO1Wt0EVYSZelPnJlbj9HplzXX/YWXHFTL45kvZ53M0pw==",
+      "dev": true,
+      "optional": true,
+      "engines": {
+        "node": "*"
+      }
+    },
+    "node_modules/@types/ical/node_modules/rrule": {
+      "version": "2.6.4",
+      "resolved": "https://registry.npmjs.org/rrule/-/rrule-2.6.4.tgz",
+      "integrity": "sha512-sLdnh4lmjUqq8liFiOUXD5kWp/FcnbDLPwq5YAc/RrN6120XOPb86Ae5zxF7ttBVq8O3LxjjORMEit1baluahA==",
+      "dev": true,
+      "dependencies": {
+        "tslib": "^1.10.0"
+      },
+      "optionalDependencies": {
+        "luxon": "^1.21.3"
+      }
+    },
+    "node_modules/@types/ical/node_modules/tslib": {
+      "version": "1.14.1",
+      "resolved": "https://registry.npmjs.org/tslib/-/tslib-1.14.1.tgz",
+      "integrity": "sha512-Xni35NKzjgMrwevysHTCArtLDpPvye8zV/0E4EyYn43P7/7qvQwPh9BGkHewbMulVntbigmcT7rdX3BNo9wRJg==",
+      "dev": true
+    },
     "node_modules/@types/jsdom": {
       "version": "20.0.1",
       "resolved": "https://registry.npmjs.org/@types/jsdom/-/jsdom-20.0.1.tgz",
@@ -167,7 +210,7 @@
       "version": "3.3.0",
       "resolved": "https://registry.npmjs.org/@types/luxon/-/luxon-3.3.0.tgz",
       "integrity": "sha512-uKRI5QORDnrGFYgcdAVnHvEIvEZ8noTpP/Bg+HeUzZghwinDlIS87DEenV5r1YoOF9G4x600YsUXLWZ19rmTmg==",
-      "dev": true
+      "devOptional": true
     },
     "node_modules/@types/mustache": {
       "version": "4.2.2",
@@ -179,7 +222,7 @@
       "version": "18.16.13",
       "resolved": "https://registry.npmjs.org/@types/node/-/node-18.16.13.tgz",
       "integrity": "sha512-uZRomboV1vBL61EBXneL4j9/hEn+1Yqa4LQdpGrKmXFyJmVfWc9JV9+yb2AlnOnuaDnb2PDO3hC6/LKmzJxP1A==",
-      "dev": true
+      "devOptional": true
     },
     "node_modules/@types/prismjs": {
       "version": "1.26.0",
@@ -1061,6 +1104,82 @@
         "node": ">= 6"
       }
     },
+    "node_modules/ical": {
+      "version": "0.8.0",
+      "resolved": "https://registry.npmjs.org/ical/-/ical-0.8.0.tgz",
+      "integrity": "sha512-/viUSb/RGLLnlgm0lWRlPBtVeQguQRErSPYl3ugnUaKUnzQswKqOG3M8/P1v1AB5NJwlHTuvTq1cs4mpeG2rCg==",
+      "dependencies": {
+        "rrule": "2.4.1"
+      }
+    },
+    "node_modules/ical-generator": {
+      "version": "4.1.0",
+      "resolved": "https://registry.npmjs.org/ical-generator/-/ical-generator-4.1.0.tgz",
+      "integrity": "sha512-5GrFDJ8SAOj8cB9P1uEZIfKrNxSZ1R2eOQfZePL+CtdWh4RwNXWe8b0goajz+Hu37vcipG3RVldoa2j57Y20IA==",
+      "dependencies": {
+        "uuid-random": "^1.3.2"
+      },
+      "engines": {
+        "node": "^14.8.0 || >=16.0.0"
+      },
+      "peerDependencies": {
+        "@touch4it/ical-timezones": ">=1.6.0",
+        "@types/luxon": ">= 1.26.0",
+        "@types/mocha": ">= 8.2.1",
+        "@types/node": ">= 15.0.0",
+        "dayjs": ">= 1.10.0",
+        "luxon": ">= 1.26.0",
+        "moment": ">= 2.29.0",
+        "moment-timezone": ">= 0.5.33",
+        "rrule": ">= 2.6.8"
+      },
+      "peerDependenciesMeta": {
+        "@touch4it/ical-timezones": {
+          "optional": true
+        },
+        "@types/luxon": {
+          "optional": true
+        },
+        "@types/mocha": {
+          "optional": true
+        },
+        "@types/node": {
+          "optional": true
+        },
+        "dayjs": {
+          "optional": true
+        },
+        "luxon": {
+          "optional": true
+        },
+        "moment": {
+          "optional": true
+        },
+        "moment-timezone": {
+          "optional": true
+        },
+        "rrule": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/ical/node_modules/luxon": {
+      "version": "1.28.1",
+      "resolved": "https://registry.npmjs.org/luxon/-/luxon-1.28.1.tgz",
+      "integrity": "sha512-gYHAa180mKrNIUJCbwpmD0aTu9kV0dREDrwNnuyFAsO1Wt0EVYSZelPnJlbj9HplzXX/YWXHFTL45kvZ53M0pw==",
+      "optional": true,
+      "engines": {
+        "node": "*"
+      }
+    },
+    "node_modules/ical/node_modules/rrule": {
+      "version": "2.4.1",
+      "resolved": "https://registry.npmjs.org/rrule/-/rrule-2.4.1.tgz",
+      "integrity": "sha512-+NcvhETefswZq13T8nkuEnnQ6YgUeZaqMqVbp+ZiFDPCbp3AVgQIwUvNVDdMNrP05bKZG9ddDULFp0qZZYDrxg==",
+      "optionalDependencies": {
+        "luxon": "^1.3.3"
+      }
+    },
     "node_modules/iconv-lite": {
       "version": "0.6.3",
       "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.6.3.tgz",
@@ -1545,6 +1664,16 @@
       "resolved": "https://registry.npmjs.org/robust-predicates/-/robust-predicates-3.0.1.tgz",
       "integrity": "sha512-ndEIpszUHiG4HtDsQLeIuMvRsDnn8c8rYStabochtUeCvfuvNptb5TUbVD68LRAILPX7p9nqQGh4xJgn3EHS/g=="
     },
+    "node_modules/rrule": {
+      "version": "2.7.2",
+      "resolved": "https://registry.npmjs.org/rrule/-/rrule-2.7.2.tgz",
+      "integrity": "sha512-NkBsEEB6FIZOZ3T8frvEBOB243dm46SPufpDckY/Ap/YH24V1zLeMmDY8OA10lk452NdrF621+ynDThE7FQU2A==",
+      "optional": true,
+      "peer": true,
+      "dependencies": {
+        "tslib": "^2.4.0"
+      }
+    },
     "node_modules/rw": {
       "version": "1.3.3",
       "resolved": "https://registry.npmjs.org/rw/-/rw-1.3.3.tgz",
@@ -1792,6 +1921,13 @@
         "node": ">=12"
       }
     },
+    "node_modules/tslib": {
+      "version": "2.5.2",
+      "resolved": "https://registry.npmjs.org/tslib/-/tslib-2.5.2.tgz",
+      "integrity": "sha512-5svOrSA2w3iGFDs1HibEVBGbDrAY82bFQ3HZ3ixB+88nsbsWQoKqDRb5UBYAUPEzbBn6dAp5gRNXglySbx1MlA==",
+      "optional": true,
+      "peer": true
+    },
     "node_modules/type-check": {
       "version": "0.3.2",
       "resolved": "https://registry.npmjs.org/type-check/-/type-check-0.3.2.tgz",
@@ -1841,6 +1977,11 @@
         "requires-port": "^1.0.0"
       }
     },
+    "node_modules/uuid-random": {
+      "version": "1.3.2",
+      "resolved": "https://registry.npmjs.org/uuid-random/-/uuid-random-1.3.2.tgz",
+      "integrity": "sha512-UOzej0Le/UgkbWEO8flm+0y+G+ljUon1QWTEZOq1rnMAsxo2+SckbiZdKzAHHlVh6gJqI1TjC/xwgR50MuCrBQ=="
+    },
     "node_modules/vega": {
       "version": "5.25.0",
       "resolved": "https://registry.npmjs.org/vega/-/vega-5.25.0.tgz",
@@ -2536,9 +2677,9 @@
   },
   "dependencies": {
     "@doc-utils/color-themes": {
-      "version": "0.1.14",
-      "resolved": "https://gitea.jbrumond.me/api/packages/doc-utils/npm/%40doc-utils%2Fcolor-themes/-/0.1.14/color-themes-0.1.14.tgz",
-      "integrity": "sha512-j0U8v8Y+9zAm9D7pbCheTQYGEKt9FSpKSZQNGsogxWl95S9Z7QMjtmJns6QPgdOsSDss7sjMLFS5Gm50GCMzNA=="
+      "version": "0.2.0",
+      "resolved": "https://gitea.jbrumond.me/api/packages/doc-utils/npm/%40doc-utils%2Fcolor-themes/-/0.2.0/color-themes-0.2.0.tgz",
+      "integrity": "sha512-UtjY25B8m4qdMvrmTPK3I1JXckbc1cvCOmIygHFBexpSWBQmb+sdoXfdCsoSpgPncurz1kwlEXffgPELCGtP8g=="
     },
     "@doc-utils/jsonschema2markdown": {
       "version": "0.1.1",
@@ -2554,9 +2695,9 @@
       }
     },
     "@doc-utils/markdown2html": {
-      "version": "0.2.6",
-      "resolved": "https://gitea.jbrumond.me/api/packages/doc-utils/npm/%40doc-utils%2Fmarkdown2html/-/0.2.6/markdown2html-0.2.6.tgz",
-      "integrity": "sha512-6cQNzthYOOlkT6rr6E1lpSJ4Zq991+chblSRxv69SVT8y5cIs6c9tFu75MXoIKX4+H68Q4i10gtMrrsXD+bkaA==",
+      "version": "0.3.6",
+      "resolved": "https://gitea.jbrumond.me/api/packages/doc-utils/npm/%40doc-utils%2Fmarkdown2html/-/0.3.6/markdown2html-0.3.6.tgz",
+      "integrity": "sha512-LCt5HAAcHz6lE+IqV2igQP7bbTq1juNbyn4KWqn3xe9eSslIyl7EvSaEH68WQtqEzX/iVFOvZz7qSoqsQeggXA==",
       "requires": {
         "bytefield-svg": "^1.6.1",
         "dompurify": "^2.3.6",
@@ -2637,6 +2778,40 @@
       "resolved": "https://registry.npmjs.org/@types/geojson/-/geojson-7946.0.4.tgz",
       "integrity": "sha512-MHmwBtCb7OCv1DSivz2UNJXPGU/1btAWRKlqJ2saEhVJkpkvqHMMaOpKg0v4sAbDWSQekHGvPVMM8nQ+Jen03Q=="
     },
+    "@types/ical": {
+      "version": "0.8.0",
+      "resolved": "https://registry.npmjs.org/@types/ical/-/ical-0.8.0.tgz",
+      "integrity": "sha512-46KAYxAwRuCh+jRgl9k5cTaXJJkB16gWpvMVPuog9UBBb2zXTf9M0MsfWYBQ21JohFSuMZfPTvk6tohqGr1tCg==",
+      "dev": true,
+      "requires": {
+        "rrule": "2.6.4"
+      },
+      "dependencies": {
+        "luxon": {
+          "version": "1.28.1",
+          "resolved": "https://registry.npmjs.org/luxon/-/luxon-1.28.1.tgz",
+          "integrity": "sha512-gYHAa180mKrNIUJCbwpmD0aTu9kV0dREDrwNnuyFAsO1Wt0EVYSZelPnJlbj9HplzXX/YWXHFTL45kvZ53M0pw==",
+          "dev": true,
+          "optional": true
+        },
+        "rrule": {
+          "version": "2.6.4",
+          "resolved": "https://registry.npmjs.org/rrule/-/rrule-2.6.4.tgz",
+          "integrity": "sha512-sLdnh4lmjUqq8liFiOUXD5kWp/FcnbDLPwq5YAc/RrN6120XOPb86Ae5zxF7ttBVq8O3LxjjORMEit1baluahA==",
+          "dev": true,
+          "requires": {
+            "luxon": "^1.21.3",
+            "tslib": "^1.10.0"
+          }
+        },
+        "tslib": {
+          "version": "1.14.1",
+          "resolved": "https://registry.npmjs.org/tslib/-/tslib-1.14.1.tgz",
+          "integrity": "sha512-Xni35NKzjgMrwevysHTCArtLDpPvye8zV/0E4EyYn43P7/7qvQwPh9BGkHewbMulVntbigmcT7rdX3BNo9wRJg==",
+          "dev": true
+        }
+      }
+    },
     "@types/jsdom": {
       "version": "20.0.1",
       "resolved": "https://registry.npmjs.org/@types/jsdom/-/jsdom-20.0.1.tgz",
@@ -2652,7 +2827,7 @@
       "version": "3.3.0",
       "resolved": "https://registry.npmjs.org/@types/luxon/-/luxon-3.3.0.tgz",
       "integrity": "sha512-uKRI5QORDnrGFYgcdAVnHvEIvEZ8noTpP/Bg+HeUzZghwinDlIS87DEenV5r1YoOF9G4x600YsUXLWZ19rmTmg==",
-      "dev": true
+      "devOptional": true
     },
     "@types/mustache": {
       "version": "4.2.2",
@@ -2664,7 +2839,7 @@
       "version": "18.16.13",
       "resolved": "https://registry.npmjs.org/@types/node/-/node-18.16.13.tgz",
       "integrity": "sha512-uZRomboV1vBL61EBXneL4j9/hEn+1Yqa4LQdpGrKmXFyJmVfWc9JV9+yb2AlnOnuaDnb2PDO3hC6/LKmzJxP1A==",
-      "dev": true
+      "devOptional": true
     },
     "@types/prismjs": {
       "version": "1.26.0",
@@ -3307,6 +3482,38 @@
         "debug": "4"
       }
     },
+    "ical": {
+      "version": "0.8.0",
+      "resolved": "https://registry.npmjs.org/ical/-/ical-0.8.0.tgz",
+      "integrity": "sha512-/viUSb/RGLLnlgm0lWRlPBtVeQguQRErSPYl3ugnUaKUnzQswKqOG3M8/P1v1AB5NJwlHTuvTq1cs4mpeG2rCg==",
+      "requires": {
+        "rrule": "2.4.1"
+      },
+      "dependencies": {
+        "luxon": {
+          "version": "1.28.1",
+          "resolved": "https://registry.npmjs.org/luxon/-/luxon-1.28.1.tgz",
+          "integrity": "sha512-gYHAa180mKrNIUJCbwpmD0aTu9kV0dREDrwNnuyFAsO1Wt0EVYSZelPnJlbj9HplzXX/YWXHFTL45kvZ53M0pw==",
+          "optional": true
+        },
+        "rrule": {
+          "version": "2.4.1",
+          "resolved": "https://registry.npmjs.org/rrule/-/rrule-2.4.1.tgz",
+          "integrity": "sha512-+NcvhETefswZq13T8nkuEnnQ6YgUeZaqMqVbp+ZiFDPCbp3AVgQIwUvNVDdMNrP05bKZG9ddDULFp0qZZYDrxg==",
+          "requires": {
+            "luxon": "^1.3.3"
+          }
+        }
+      }
+    },
+    "ical-generator": {
+      "version": "4.1.0",
+      "resolved": "https://registry.npmjs.org/ical-generator/-/ical-generator-4.1.0.tgz",
+      "integrity": "sha512-5GrFDJ8SAOj8cB9P1uEZIfKrNxSZ1R2eOQfZePL+CtdWh4RwNXWe8b0goajz+Hu37vcipG3RVldoa2j57Y20IA==",
+      "requires": {
+        "uuid-random": "^1.3.2"
+      }
+    },
     "iconv-lite": {
       "version": "0.6.3",
       "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.6.3.tgz",
@@ -3650,6 +3857,16 @@
       "resolved": "https://registry.npmjs.org/robust-predicates/-/robust-predicates-3.0.1.tgz",
       "integrity": "sha512-ndEIpszUHiG4HtDsQLeIuMvRsDnn8c8rYStabochtUeCvfuvNptb5TUbVD68LRAILPX7p9nqQGh4xJgn3EHS/g=="
     },
+    "rrule": {
+      "version": "2.7.2",
+      "resolved": "https://registry.npmjs.org/rrule/-/rrule-2.7.2.tgz",
+      "integrity": "sha512-NkBsEEB6FIZOZ3T8frvEBOB243dm46SPufpDckY/Ap/YH24V1zLeMmDY8OA10lk452NdrF621+ynDThE7FQU2A==",
+      "optional": true,
+      "peer": true,
+      "requires": {
+        "tslib": "^2.4.0"
+      }
+    },
     "rw": {
       "version": "1.3.3",
       "resolved": "https://registry.npmjs.org/rw/-/rw-1.3.3.tgz",
@@ -3835,6 +4052,13 @@
         "punycode": "^2.1.1"
       }
     },
+    "tslib": {
+      "version": "2.5.2",
+      "resolved": "https://registry.npmjs.org/tslib/-/tslib-2.5.2.tgz",
+      "integrity": "sha512-5svOrSA2w3iGFDs1HibEVBGbDrAY82bFQ3HZ3ixB+88nsbsWQoKqDRb5UBYAUPEzbBn6dAp5gRNXglySbx1MlA==",
+      "optional": true,
+      "peer": true
+    },
     "type-check": {
       "version": "0.3.2",
       "resolved": "https://registry.npmjs.org/type-check/-/type-check-0.3.2.tgz",
@@ -3868,6 +4092,11 @@
         "requires-port": "^1.0.0"
       }
     },
+    "uuid-random": {
+      "version": "1.3.2",
+      "resolved": "https://registry.npmjs.org/uuid-random/-/uuid-random-1.3.2.tgz",
+      "integrity": "sha512-UOzej0Le/UgkbWEO8flm+0y+G+ljUon1QWTEZOq1rnMAsxo2+SckbiZdKzAHHlVh6gJqI1TjC/xwgR50MuCrBQ=="
+    },
     "vega": {
       "version": "5.25.0",
       "resolved": "https://registry.npmjs.org/vega/-/vega-5.25.0.tgz",

package.json

@@ -1,8 +1,8 @@
 {
   "name": "@doc-utils/docs2website",
-  "version": "0.1.3",
+  "version": "0.2.1",
   "publishConfig": {
-    "registry": "https://gitea.home.jbrumond.me/api/packages/doc-utils/npm/"
+    "registry": "https://gitea.jbrumond.me/api/packages/doc-utils/npm/"
   },
   "scripts": {
     "tsc": "tsc",
@@ -13,6 +13,7 @@
   },
   "main": "./build/index.js",
   "devDependencies": {
+    "@types/ical": "^0.8.0",
     "@types/jsdom": "^20.0.1",
     "@types/luxon": "^3.3.0",
     "@types/mustache": "^4.2.2",
@@ -21,10 +22,12 @@
     "typescript": "^5.0.4"
   },
   "dependencies": {
-    "@doc-utils/color-themes": "^0.1.14",
+    "@doc-utils/color-themes": "^0.2.0",
     "@doc-utils/jsonschema2markdown": "^0.1.1",
-    "@doc-utils/markdown2html": "^0.2.1",
+    "@doc-utils/markdown2html": "^0.3.6",
     "glob": "^10.2.3",
+    "ical": "^0.8.0",
+    "ical-generator": "^4.1.0",
     "luxon": "^3.3.0",
     "mustache": "^4.2.0",
     "xmlbuilder2": "^3.1.1",

src/build-files/helpers.ts

@@ -1,12 +1,16 @@
 
 import { dirname, join as path_join } from 'path';
-import { mkdirp, write_text } from '../fs';
 import { icons } from '../icons';
 import { BuildState } from './state';
-import { load_partials, FrontMatter, Context, load_layout, render_template } from '../template';
-import { render_theme_css_properties } from '../themes';
-import { render_markdown_to_html, render_markdown_to_html_inline_sync } from '@doc-utils/markdown2html';
+import { mkdirp, write_text } from '../fs';
 import { CalendarConfig, RSSConfig } from '../conf';
+import { render_theme_css_properties } from '../themes';
+import { load_partials, FrontMatter, Context, load_layout, render_template, EventFrontmatter } from '../template';
+import { render_markdown_to_html, render_markdown_to_html_inline_sync } from '@doc-utils/markdown2html';
+import { RSSEntry } from './rss';
+import { EventEntry } from './icalendar';
+import { as_context_time, from_iso } from '../time';
+import { FileMetadata } from '../metadata';
 
 export interface OutFileURL {
 	base_url: string;
@@ -26,9 +30,9 @@ export function map_output_file_to_url(state: BuildState, out_file: string, inde
 		rel_path = '/' + rel_path;
 	}
 
-	const base_url = state.conf.base_url.endsWith('/')
+	const base_url = state.conf.base_url?.endsWith('/')
 		? state.conf.base_url.slice(0, -1)
-		: state.conf.base_url;
+		: (state.conf.base_url ?? '');
 
 	return {
 		base_url,
@@ -78,14 +82,46 @@ export async function build_partials(state: BuildState) {
 	Object.assign(state.partials, state.extras);
 }
 
-export function mustache_context(state: BuildState, page_url: string, frontmatter?: FrontMatter) : Context {
+export function mustache_context(state: BuildState, page_url: string, metadata: FileMetadata, frontmatter?: FrontMatter) : Context {
+	let event: Context['event'];
+
+	if (frontmatter?.event) {
+		event = Array.isArray(frontmatter.event)
+			? frontmatter.event.map(to_context_event)
+			: to_context_event(frontmatter.event);
+
+		function to_context_event(event_fm: EventFrontmatter) {
+			const start = from_iso(event_fm.start, event_fm.time_zone);
+			const end = from_iso(event_fm.end, event_fm.time_zone);
+			
+			return {
+				start: as_context_time(start),
+				end: as_context_time(end),
+				time_zone: event_fm.time_zone,
+			};
+		}
+	}
+
+	const has_been_updated = metadata.first_seen_time !== metadata.last_updated_time;
+
 	return {
 		env: state.env,
 		page: frontmatter,
-		base_url: state.conf.base_url,
+		base_url: state.conf.base_url ?? '/',
 		page_url: page_url,
+		page_published: as_context_time(from_iso(metadata.first_seen_time), 'dt-published'),
+		page_updated: has_been_updated ? as_context_time(from_iso(metadata.last_updated_time), 'dt-updated') : null,
+		site_title: state.conf.title,
+		author: get_author(state, frontmatter),
+		event: event,
+		event_series: Array.isArray(event) && {
+			start: event[0].start,
+			end: event[event.length - 1].end,
+		},
 		build_time: state.build_time,
 		icons: icons,
+		rss_feeds: state.conf.rss || [ ],
+		calendars: state.conf.calendars || [ ],
 		themes: Object.values(state.themes),
 		theme_groups: structuredClone(state.theme_groups),
 		markdown: {
@@ -102,10 +138,10 @@ export function mustache_context(state: BuildState, page_url: string, frontmatte
 	};
 }
 
-export async function render_page(state: BuildState, out_file: string, out_url: OutFileURL, text: string, render_as_markdown: boolean, frontmatter?: any) {
+export async function render_page(state: BuildState, in_file: string, out_file: string, out_url: OutFileURL, text: string, render_as_markdown: boolean, hash: string, frontmatter?: any) {
 	if (render_as_markdown) {
 		const opts = Object.assign({ }, state.conf.markdown, {
-			base_url: out_url.abs_url
+			// base_url: out_url.abs_url,
 		});
 
 		text = await render_markdown_to_html(text, opts);
@@ -122,74 +158,150 @@ export async function render_page(state: BuildState, out_file: string, out_url:
 		layout = state.layouts[layout_file];
 	}
 
+	const hash_matches = file_hash_matches(state, in_file, hash);
+	const rel_in_file = in_file.slice(state.conf.input.root.length);
+	const old_metadata = state.old_metadata?.files?.[rel_in_file];
+	const new_metadata = hash_matches ? structuredClone(old_metadata) : {
+		first_seen_time: old_metadata?.first_seen_time || state.build_time.iso,
+		last_build_hash: hash,
+		last_updated_time: state.build_time.iso,
+	};
+
 	const tags = state.conf.templates?.tags;
-	const context = mustache_context(state, out_url.abs_url, frontmatter);
+	const context = mustache_context(state, out_url.abs_url, new_metadata, frontmatter);
 	const rendered = render_template(text, context, layout, structuredClone(state.partials), tags);
 	await write_text(out_file, rendered);
-	
-	handle_page_side_effects(state, out_file, out_url, frontmatter);
+
+	state.new_metadata.files[rel_in_file] = new_metadata;
+	handle_page_side_effects(state, in_file, out_file, out_url, text, frontmatter);
 }
 
-function handle_page_side_effects(state: BuildState, out_file: string, out_url: OutFileURL, frontmatter?: any) {
+function handle_page_side_effects(state: BuildState, in_file: string, out_file: string, out_url: OutFileURL, text: string, frontmatter?: any) {
 	// Only actual HTML webpages are registered with things like the RSS feed; This is
 	// to prevent things like CSS files showing up, which may be templated (and therefore
 	// pass through this function), but are not really "pages"
 	if (frontmatter && typeof frontmatter === 'object' && out_file.endsWith('.html')) {
 		if (state.conf.rss) {
-			if (Array.isArray(state.conf.rss)) {
-				for (const rss_conf of state.conf.rss) {
-					handle_rss(state, rss_conf, out_url, frontmatter);
+			for (const [index, rss_conf] of Object.entries(state.conf.rss)) {
+				if (in_file.startsWith(rss_conf.in_dir + '/')) {
+					const entries = (state.rss[index] = state.rss[index] || [ ]);
+					handle_rss(state, rss_conf, entries, in_file, out_url, text, frontmatter);
 				}
 			}
-
-			else {
-				handle_rss(state, { }, out_url, frontmatter);
-			}
 		}
 
-		handle_sitemap(state, out_url, frontmatter);
-		handle_event(state, out_url, frontmatter);
+		if (state.conf.sitemap) {
+			handle_sitemap(state, out_url, frontmatter);
+		}
 
-		if (state.conf.calendars) {
-			for (const cal_conf of state.conf.calendars) {
-				handle_calendar(state, cal_conf, out_url, frontmatter);
+		if (frontmatter?.event) {
+			if (state.conf.events) {
+				handle_event(state, in_file, out_url, frontmatter);
+			}
+	
+			if (state.conf.calendars) {
+				for (const [index, cal_conf] of Object.entries(state.conf.calendars)) {
+					if (in_file.startsWith(cal_conf.in_dir + '/')) {
+						const entries = (state.rss[index] = state.rss[index] || [ ]);
+						handle_calendar(state, cal_conf, entries, in_file, out_url, frontmatter);
+					}
+				}
 			}
 		}
 	}
 }
 
-function handle_rss(state: BuildState, rss_conf: RSSConfig, out_url: OutFileURL, frontmatter: any) {
-	// const field = rss_conf
-	// const rss_frontmatter = state.
-	// // 
-}
-
-function handle_sitemap(state: BuildState, out_url: OutFileURL, frontmatter: any) {
-	if (! state.conf.sitemap) {
+function handle_rss(state: BuildState, rss_conf: RSSConfig, entries: RSSEntry[], in_file: string, out_url: OutFileURL, text: string, frontmatter: FrontMatter) {
+	if (frontmatter?.rss?.skip) {
 		return;
 	}
 
-	const sitemap_frontmatter = state.conf.sitemap.front_matter_field
-		? frontmatter?.[state.conf.sitemap.front_matter_field] || { }
-		: frontmatter?.sitemap || { };
+	const author_or_authors = get_author(state, frontmatter);
+	const authors = author_or_authors && (Array.isArray(author_or_authors) ? author_or_authors : [ author_or_authors ]);
+
+	entries.push({
+		url: out_url.abs_url,
+		in_file: in_file,
+		html_content: text,
+		title: frontmatter?.title,
+		description: frontmatter?.description,
+		authors: authors,
+		tags: frontmatter?.tags,
+	});
+}
+
+function handle_sitemap(state: BuildState, out_url: OutFileURL, frontmatter: FrontMatter) {
+	if (frontmatter?.sitemap?.skip) {
+		return;
+	}
 
 	state.sitemap.push({
 		url: out_url.abs_url,
 		lastmod: state.build_time.iso,
-		change_freq: sitemap_frontmatter?.change_freq,
-		priority: sitemap_frontmatter?.priority,
+		change_freq: frontmatter?.sitemap?.change_freq,
+		priority: frontmatter?.sitemap?.priority,
 	});
 }
 
-function handle_event(state: BuildState, out_url: OutFileURL, frontmatter: any) {
-	// 
+function handle_event(state: BuildState, in_file: string, out_url: OutFileURL, frontmatter: FrontMatter) {
+	if (! state.conf.events) {
+		return;
+	}
+
+	const author_or_authors = get_author(state, frontmatter);
+	const author = Array.isArray(author_or_authors) ? author_or_authors[0] : author_or_authors;
+
+	if (Array.isArray(frontmatter.event)) {
+		state.event_series.push({
+			url: out_url.abs_url,
+			in_file: in_file,
+			title: frontmatter.title,
+			description: frontmatter.description,
+			author_name: author?.name,
+			author_email: author?.email,
+			entries: frontmatter.event.slice(),
+		});
+
+		return;
+	}
+
+	state.events.push({
+		url: out_url.abs_url,
+		in_file: in_file,
+		title: frontmatter.event.title || frontmatter.title,
+		description: frontmatter.description,
+		author_name: author?.name,
+		author_email: author?.email,
+		start: frontmatter.event.start,
+		end: frontmatter.event.end,
+		time_zone: frontmatter.event.time_zone,
+	});
 }
 
-function handle_calendar(state: BuildState, cal_conf: CalendarConfig, out_url: OutFileURL, frontmatter: any) {
-	// 
+function handle_calendar(state: BuildState, cal_conf: CalendarConfig, entries: EventEntry[], in_file: string, out_url: OutFileURL, frontmatter: FrontMatter) {
+	const author_or_authors = get_author(state, frontmatter);
+	const author = Array.isArray(author_or_authors) ? author_or_authors[0] : author_or_authors;
+
+	if (Array.isArray(frontmatter.event)) {
+		// todo: add each event to the calendar
+
+		return;
+	}
+
+	entries.push({
+		url: out_url.abs_url,
+		in_file: in_file,
+		title: frontmatter.title,
+		description: frontmatter.description,
+		author_name: author?.name,
+		author_email: author?.email,
+		start: frontmatter.event?.start,
+		end: frontmatter.event?.end,
+		time_zone: frontmatter.event?.time_zone,
+	});
 }
 
-export function file_hash_matches(state: BuildState, in_file: string, new_hash: string) {
+export function config_hash_matches(state: BuildState) {
 	const { old_metadata, new_metadata } = state;
 
 	if (! old_metadata.last_build?.config_hash) {
@@ -199,7 +311,11 @@ export function file_hash_matches(state: BuildState, in_file: string, new_hash:
 	if (old_metadata.last_build.config_hash !== new_metadata.last_build.config_hash) {
 		return false;
 	}
+	
+	return true;
+}
 
+export function file_hash_matches(state: BuildState, in_file: string, new_hash: string) {
 	in_file = in_file.slice(state.conf.input.root.length);
 	const old_hash = state.old_metadata.files[in_file]?.last_build_hash;
 	
@@ -217,14 +333,25 @@ export function file_hash_matches(state: BuildState, in_file: string, new_hash:
 export function skip_file(state: BuildState, in_file: string, out_file: string, out_url: OutFileURL, frontmatter?: any) {
 	in_file = in_file.slice(state.conf.input.root.length);
 	state.new_metadata.files[in_file] = structuredClone(state.old_metadata?.files?.[in_file]);
-	handle_page_side_effects(state, out_file, out_url, frontmatter);
+	handle_page_side_effects(state, in_file, out_file, out_url, frontmatter);
 }
 
-export function update_metadata(state: BuildState, in_file: string, hash: string) {
-	in_file = in_file.slice(state.conf.input.root.length);
-	state.new_metadata.files[in_file] = {
-		first_seen_time: state.old_metadata?.files?.[in_file]?.first_seen_time || state.build_time.iso,
-		last_build_hash: hash,
-		last_updated_time: state.build_time.iso,
-	};
+export function get_author(state: BuildState, frontmatter?: FrontMatter) {
+	if (! frontmatter?.author) {
+		return null;
+	}
+
+	if (Array.isArray(frontmatter.author)) {
+		const list = frontmatter.author
+			.map((author) => state.conf.authors?.[author])
+			.filter((author) => author);
+
+		if (! list.length) {
+			return null;
+		}
+
+		return list;
+	}
+
+	return state.conf.authors?.[frontmatter.author]
 }

src/build-files/icalendar.ts

@@ -0,0 +1,209 @@
+
+import { write_text } from '../fs';
+import { BuildState } from './state';
+import { map_input_file_to_output_file } from './helpers';
+// import { parseICS, CalendarComponent } from 'ical';
+import create_calendar, { ICalEventData, ICalCalendarData } from 'ical-generator';
+import { FrontMatterLocation } from '../template';
+
+export type { ICalEventData, ICalCalendarData, ICalAttendeeData, ICalAttendeeStatus } from 'ical-generator';
+
+export interface EventSeries {
+	url: string;
+	in_file: string;
+	title?: string;
+	description?: string;
+	author_name?: string;
+	author_email?: string;
+	entries: {
+		title?: string;
+		start?: string;
+		end?: string;
+		time_zone?: `${string}/${string}`;
+		location?: FrontMatterLocation;
+	}[];
+}
+
+export interface EventEntry {
+	url: string;
+	in_file: string;
+	title?: string;
+	description?: string;
+	author_name?: string;
+	author_email?: string;
+	start?: string;
+	end?: string;
+	time_zone?: `${string}/${string}`;
+	location?: FrontMatterLocation;
+}
+
+export async function write_events_and_calendars_if_needed(state: BuildState) {
+	if (state.conf.events) {
+		for (const entry of state.events) {
+			const event = icalendar_event(state, entry);
+			const cal_data: ICalCalendarData = {
+				prodId: {
+					company: 'jbrumond.me',
+					product: 'docs2website',
+					language: 'EN',
+				},
+				// ...
+			};
+
+			const calendar = create_icalendar(cal_data, event);
+			const out_file = await map_input_file_to_output_file(state, entry.in_file, [ '.html', '.md', '.markdown' ], '.ics');
+			await write_text(out_file, calendar);
+		}
+
+		for (const series of state.event_series) {
+			const events = series.entries.map((event) => {
+				return icalendar_event(state, {
+					url: series.url,
+					in_file: series.in_file,
+					title: event.title || series.title,
+					description: series.description,
+					author_name: series.author_name,
+					author_email: series.author_email,
+					start: event.start,
+					end: event.end,
+					time_zone: event.time_zone,
+					location: event.location,
+				});
+			});
+			
+			const cal_data: ICalCalendarData = {
+				name: series.title,
+				description: series.description,
+				url: series.url,
+				prodId: {
+					company: 'jbrumond.me',
+					product: 'docs2website',
+					language: 'EN',
+				},
+				// ...
+			};
+
+			const calendar = create_icalendar(cal_data, events);
+			const out_file = await map_input_file_to_output_file(state, series.in_file, [ '.html', '.md', '.markdown' ], '.ics');
+			await write_text(out_file, calendar);
+		}
+	}
+
+	if (state.conf.calendars) {
+		for (let index = 0; index < state.conf.calendars.length; index++) {
+			const cal_conf = state.conf.calendars[index];
+			const cal_entries = state.calendars[index];
+
+			for (const entry of cal_entries) {
+				const event = icalendar_event(state, entry);
+				const cal_data: ICalCalendarData = {
+					name: cal_conf.title,
+					prodId: {
+						company: 'jbrumond.me',
+						product: 'docs2website',
+						language: 'EN',
+					},
+					// ...
+				};
+
+				const calendar = create_icalendar(cal_data, event);
+				await write_text(cal_conf.out_file, calendar);
+			}
+		}
+	}
+}
+
+// export function parse_icalendar(contents: string) {
+// 	const parsed = parseICS(contents);
+// 	const calendar: CalendarComponent[] = [ ];
+
+// 	for (const data of Object.values(parsed)) {
+// 		calendar.push(data);
+// 	}
+
+// 	return calendar;
+// }
+
+export function create_icalendar(cal: ICalCalendarData, events: ICalEventData | ICalEventData[]) {
+	const calendar = create_calendar(cal);
+
+	if (Array.isArray(events)) {
+		for (const event of events) {
+			calendar.createEvent(event);
+		}
+	}
+
+	else {
+		calendar.createEvent(events);
+	}
+
+	return calendar.toString();
+}
+
+export function icalendar_event(state: BuildState, entry: EventEntry) : ICalEventData {
+	const in_file = entry.in_file.slice(state.conf.input.root.length);
+	const metadata = state.new_metadata.files[in_file];
+
+	return {
+		id: entry.url,
+		summary: entry.title,
+		description: entry.description || void 0,
+		start: entry.start,
+		end: entry.end,
+		url: entry.url,
+		timezone: entry.time_zone,
+		created: metadata.first_seen_time,
+		lastModified: metadata.last_updated_time,
+		organizer: {
+			name: entry.author_name || 'Unknown',
+			email: entry.author_email,
+		},
+		location: format_location(entry.location),
+		// attendees: post.mentions.flatMap((mention) : ICalAttendeeData | ICalAttendeeData[] => {
+		// 	if (mention.is_rsvp && mention.is_reply_to_this) {
+		// 		const ext = mention.external as ExternalEntry;
+		// 		const status = ext.rsvp_type === 'yes'
+		// 			? 'ACCEPTED' as const
+		// 			: ext.rsvp_type === 'no'
+		// 				? 'DECLINED' as const
+		// 				: ext.rsvp_type === 'maybe'
+		// 					? 'TENTATIVE' as const
+		// 					: 'NEEDS-ACTION' as const;
+
+		// 		return {
+		// 			name: mention.author_name,
+		// 			rsvp: ext.rsvp_type === 'yes',
+		// 			status: status as ICalAttendeeStatus
+		// 		};
+		// 	}
+
+		// 	return [ ];
+		// }),
+	};
+}
+
+function format_location(loc: FrontMatterLocation) {
+	if (! loc) {
+		return;
+	}
+
+	if (loc.description) {
+		if (loc.address) {
+			return `${loc.description} (${loc.address})`;
+		}
+		
+		if (loc.lat && loc.long) {
+			return `${loc.description} [${loc.lat}, ${loc.long}]`;
+		}
+
+		return loc.description;
+	}
+
+	if (loc.address) {
+		return loc.address;
+	}
+
+	if (loc.lat && loc.long) {
+		return `[${loc.lat}, ${loc.long}]`;
+	}
+}

src/build-files/index.ts

@@ -14,6 +14,9 @@ import { render_text_file_templates } from './mustache';
 import { render_markdown_files } from './markdown';
 import { render_json_schema_files } from './jsonschema';
 import { write_sitemap_if_needed } from './sitemap';
+import { write_rss_if_needed } from './rss';
+import { write_events_and_calendars_if_needed } from './icalendar';
+import { as_context_time, as_html_time } from '../time';
 
 export { BuildState, ThemeGroups } from './state';
 
@@ -55,11 +58,12 @@ export async function build_docs_project(conf: Config) {
 		},
 		extras: await load_extras(),
 		made_directories: new Set<string>(),
+		rss: [ ],
 		sitemap: [ ],
-		build_time: {
-			iso: now.toISO(),
-			rfc2822: now.toRFC2822(),
-		},
+		events: [ ],
+		event_series: [ ],
+		calendars: [ ],
+		build_time: as_context_time(now),
 	};
 
 	for (const theme of Object.values(themes)) {
@@ -87,8 +91,8 @@ export async function build_docs_project(conf: Config) {
 	// todo: other file types...
 
 	await write_sitemap_if_needed(state);
-	// todo: rss
-	// todo: events
+	await write_rss_if_needed(state);
+	await write_events_and_calendars_if_needed(state);
 
 	// Write the updated metadata file
 	await write_json(conf.metadata, state.new_metadata, true);

src/build-files/jsonschema.ts

@@ -4,7 +4,7 @@ import { BuildState } from './state';
 import { read_json, write_text, read_yaml } from '../fs';
 import { build_markdown_from_json_schema } from '@doc-utils/jsonschema2markdown';
 import { stringify as to_yaml } from 'yaml';
-import { build_partials, file_hash_matches, map_input_file_to_output_file, map_output_file_to_url, render_page, skip_file, update_metadata } from './helpers';
+import { build_partials, map_input_file_to_output_file, map_output_file_to_url, render_page } from './helpers';
 
 export async function render_json_schema_files(state: BuildState) {
 	const promises: Promise<any>[] = [ ];
@@ -113,10 +113,6 @@ export async function render_json_schema(state: BuildState, schema: unknown, in_
 
 	const out_url = map_output_file_to_url(state, out_file);
 
-	if (file_hash_matches(state, in_file, hash)) {
-		return skip_file(state, in_file, out_file, out_url, frontmatter);
-	}
-
 	const promises: Promise<any>[] = [ ];
 	const markdown = build_markdown_from_json_schema(schema);
 	
@@ -128,9 +124,8 @@ export async function render_json_schema(state: BuildState, schema: unknown, in_
 	}
 	
 	promises.push(
-		render_page(state, out_file, out_url, markdown, true, frontmatter)
+		render_page(state, in_file, out_file, out_url, markdown, true, hash, frontmatter)
 	);
 	
 	await Promise.all(promises);
-	update_metadata(state, in_file, hash);
 }

src/build-files/markdown.ts

@@ -2,7 +2,7 @@
 import { glob } from 'glob';
 import { read_text } from '../fs';
 import { BuildState } from './state';
-import { build_partials, file_hash_matches, map_input_file_to_output_file, map_output_file_to_url, render_page, skip_file, update_metadata } from './helpers';
+import { build_partials, map_input_file_to_output_file, map_output_file_to_url, render_page } from './helpers';
 
 export async function render_markdown_files(state: BuildState) {
 	const promises: Promise<any>[] = [ ];
@@ -34,15 +34,10 @@ export async function render_markdown_file(state: BuildState, in_file: string) {
 	const out_file = await map_input_file_to_output_file(state, in_file, [ '.md', '.markdown' ], '.html');
 	const out_url = map_output_file_to_url(state, out_file);
 	const { frontmatter, text, hash } = await read_text(in_file);
-
+	
 	if (frontmatter?.skip) {
 		return;
 	}
-
-	if (file_hash_matches(state, in_file, hash)) {
-		return skip_file(state, in_file, out_file, out_url, frontmatter);
-	}
 	
-	await render_page(state, out_file, out_url, text, true, frontmatter);
-	update_metadata(state, in_file, hash);
+	await render_page(state, in_file, out_file, out_url, text, true, hash, frontmatter);
 }

src/build-files/mustache.ts

@@ -2,7 +2,7 @@
 import { glob } from 'glob';
 import { read_text } from '../fs';
 import { BuildState } from './state';
-import { build_partials, file_hash_matches, map_input_file_to_output_file, map_output_file_to_url, render_page, skip_file, update_metadata } from './helpers';
+import { build_partials, map_input_file_to_output_file, map_output_file_to_url, render_page } from './helpers';
 
 export async function render_text_file_templates(state: BuildState) {
 	const promises: Promise<any>[] = [ ];
@@ -39,10 +39,5 @@ export async function render_text_file_template(state: BuildState, in_file: stri
 		return;
 	}
 
-	if (file_hash_matches(state, in_file, hash)) {
-		return skip_file(state, in_file, out_file, out_url, frontmatter);
-	}
-
-	await render_page(state, out_file, out_url, text, false, frontmatter);
-	update_metadata(state, in_file, hash);
+	await render_page(state, in_file, out_file, out_url, text, false, hash, frontmatter);
 }

src/build-files/rss.ts

@@ -0,0 +1,144 @@
+
+import type { XMLBuilder } from 'xmlbuilder2/lib/interfaces';
+import { create as create_xml } from 'xmlbuilder2';
+import { BuildState } from './state';
+import { write_text } from '../fs';
+import { AuthorConfig, app_version } from '../conf';
+import { map_output_file_to_url } from './helpers';
+import { DateTime } from 'luxon';
+import { FileMetadata } from '../metadata';
+
+export interface RSSEntry {
+	url: string;
+	in_file: string;
+	title?: string;
+	description?: string;
+	authors?: AuthorConfig[];
+	html_content?: string;
+	tags?: string[];
+}
+
+export async function write_rss_if_needed(state: BuildState) {
+	if (! state.conf.rss) {
+		return;
+	}
+
+	for (let index = 0; index < state.conf.rss.length; index++) {
+		const rss_conf = state.conf.rss[index];
+		const doc = create_xml({ version: '1.0', encoding: 'UTF-8' });
+		const { abs_url: self_url } = map_output_file_to_url(state, rss_conf.out_file);
+	
+		if (rss_conf.xsl) {
+			for (const url of rss_conf.xsl) {
+				doc.ins('xml-stylesheet', `href="${url}" type="text/xsl"`);
+			}
+		}
+		
+		const rss = doc.ele('rss', {
+			version: '2.0',
+			'xmlns:dc': 'http://purl.org/dc/elements/1.1/',
+			'xmlns:content': 'http://purl.org/rss/1.0/modules/content/',
+			'xmlns:atom': 'http://www.w3.org/2005/Atom',
+			// 'xmlns:docs2website': 'urn:uuid:7fc4e5d4-f68e-11ed-b0d0-00155ddef564',
+		});
+
+		const channel = rss.ele('channel');
+		channel.ele('generator').txt(`docs2website ${app_version}`);
+
+		if (rss_conf.title) {
+			channel.ele('title').txt(rss_conf.title);
+		}
+
+		if (rss_conf.link) {
+			channel.ele('link').txt(rss_conf.link);
+		}
+	
+		link(channel, 'application/rss+xml', 'self', self_url);
+
+		if (rss_conf.alternates?.length) {
+			for (const alt of rss_conf.alternates) {
+				link(channel, alt.type, 'alternate', alt.href);
+			}
+		}
+	
+		if (rss_conf.description) {
+			channel.ele('description').txt(rss_conf.description);
+		}
+		
+		if (rss_conf.language) {
+			channel.ele('language').txt(rss_conf.language);
+		}
+		
+		if (rss_conf.copyright) {
+			channel.ele('copyright').txt(rss_conf.copyright);
+		}
+	
+		channel.ele('lastBuildDate').txt(state.build_time.rfc2822);
+
+		// channel.ele('rating').txt('');  // see: https://www.w3.org/PICS/
+		// channel.ele('pubDate').txt(publish_date.toUTCString());
+		// channel.ele('categories').txt('');
+		// channel.ele('docs').txt('');
+		// channel.ele('managingEditor').txt('james@jbrumond.me');
+		// channel.ele('webMaster').txt('james@jbrumond.me');
+		// channel.ele('ttl').txt('');
+		// channel.ele('image').txt('');
+		// channel.ele('skipHours').txt('');
+		// channel.ele('skipDays').txt('');
+
+		let entries: (RSSEntry & { metadata: FileMetadata, first_seen: number })[] = [ ];
+	
+		for (const entry of state.rss[index] || [ ]) {
+			const in_file = entry.in_file.slice(state.conf.input.root.length);
+			const metadata = state.new_metadata.files[in_file];
+			entries.push({ ...entry, metadata, first_seen: DateTime.fromISO(metadata.first_seen_time).toUnixInteger() });
+		}
+
+		entries = entries.sort((a, b) => {
+			return b.first_seen - a.first_seen;
+		});
+
+		for (const entry of entries) {
+			const item = channel.ele('item');
+	
+			item.ele('link').txt(entry.url);
+
+			if (entry.title) {
+				item.ele('title').txt(entry.title);
+			}
+	
+			if (entry.description) {
+				item.ele('description').txt(entry.description);
+			}
+			
+			if (entry.authors) {
+				for (const author of entry.authors) {
+					item.ele('dc:creator').ele({ $: author.name || author.url || author.email });
+				}
+			}
+	
+			if (entry.tags) {
+				entry.tags.forEach((tag) => item.ele('category').txt(tag));
+			}
+	
+			item.ele('guid').txt(entry.url);
+			item.ele('pubDate').txt(DateTime.fromISO(entry.metadata.first_seen_time).toRFC2822());
+
+			if (entry.html_content) {
+				item.ele('content:encoded').ele({ $: entry.html_content });
+			}
+		}
+	
+		const xml = doc.toString({
+			indent: '  ',
+			prettyPrint: true,
+		});
+	
+		await write_text(rss_conf.out_file, xml);
+	}
+}
+	
+function link(channel: XMLBuilder, type: string, rel: string, href: string) {
+	// channel.ele('link', { href, rel, type, });
+	channel.ele('atom:link', { type, rel, href, });
+}

src/build-files/state.ts

@@ -3,6 +3,9 @@ import type { Config } from '../conf';
 import type { Metadata } from '../metadata';
 import type { ColorTheme } from '@doc-utils/color-themes';
 import type { SitemapEntry } from './sitemap';
+import { RSSEntry } from './rss';
+import { EventEntry, EventSeries } from './icalendar';
+import { ContextTime } from '../template';
 
 export interface BuildState {
 	conf: Config;
@@ -16,16 +19,12 @@ export interface BuildState {
 	made_directories: Set<string>;
 	old_metadata: Metadata;
 	new_metadata: Metadata;
-	// rss: {
-	// 	url: string;
-	// 	last_updated: string;
-	// }[];
+	rss: RSSEntry[][];
 	sitemap: SitemapEntry[];
-	// events: EventEntry[];
-	build_time: {
-		iso: string;
-		rfc2822: string;
-	};
+	events: EventEntry[];
+	event_series: EventSeries[];
+	calendars: EventEntry[][];
+	build_time: ContextTime;
 }
 
 export interface ThemeGroups {

src/conf.ts

@@ -4,31 +4,59 @@ import { parse as parse_yaml } from 'yaml';
 import { resolve as resolve_path, dirname } from 'path';
 import { MarkdownOptions } from '@doc-utils/markdown2html';
 
+export const app_version = require('../package.json').version;
+
 export async function read_config(file: string) {
 	const path = resolve_path(process.cwd(), file);
 	const yaml = await fs.readFile(path, 'utf8');
 	const config = parse_yaml(yaml);
+	
 	validate_config(config);
+
+	config.title = resolve_env_var_if_needed(config.title);
+	config.metadata = resolve_env_var_if_needed(config.metadata);
+	config.base_url = resolve_env_var_if_needed(config.base_url);
+	config.input.root = resolve_env_var_if_needed(config.input.root);
+	config.output.root = resolve_env_var_if_needed(config.output.root);
+
 	process_markdown_config(config);
 	resolve_paths(path, config);
+	
 	return config;
 }
 
 export interface RSSConfig {
-	dir_path?: string;
-	out_file?: string;
-	front_matter_field?: string;
+	in_dir: string;
+	out_file: string;
+	title?: string;
+	description?: string;
+	link?: string;
+	xsl?: string[];
+	language?: string;
+	copyright?: string;
+	alternates?: {
+		type: string;
+		href: string;
+	}[];
 }
 
 export interface CalendarConfig {
-	dir_path?: string;
+	in_dir?: string;
 	out_file?: string;
-	front_matter_field?: string;
+	title?: string;
+}
+
+export interface AuthorConfig {
+	name?: string;
+	email?: string;
+	url?: string;
 }
 
 export interface Config {
+	title: string;
 	metadata: string;
 	base_url: string;
+	authors?: Record<string, AuthorConfig>;
 	input: {
 		root: string;
 		raw?: string[];
@@ -55,11 +83,9 @@ export interface Config {
 	};
 	sitemap?: false | {
 		out_file?: string;
-		front_matter_field?: string;
 	};
 	rss?: false | RSSConfig[];
 	events?: false | {
-		front_matter_field?: string;
 	};
 	calendars?: false | CalendarConfig[];
 	markdown?: Omit<MarkdownOptions, 'base_url' | 'inline' | 'extensions'>;
@@ -68,7 +94,7 @@ export interface Config {
 	};
 	openapi?: {
 		// ;
-	}
+	};
 	// ...
 }
 
@@ -100,8 +126,8 @@ function resolve_paths(file_path: string, config: Config) {
 
 	if (Array.isArray(config.rss)) {
 		for (const rss_conf of config.rss) {
-			if (rss_conf.dir_path) {
-				rss_conf.dir_path = resolve_path(config.input.root, rss_conf.dir_path);
+			if (rss_conf.in_dir) {
+				rss_conf.in_dir = resolve_path(config.input.root, rss_conf.in_dir);
 				rss_conf.out_file = resolve_path(config.output.root, rss_conf.out_file);
 			}
 		}
@@ -113,8 +139,8 @@ function resolve_paths(file_path: string, config: Config) {
 
 	if (Array.isArray(config.calendars)) {
 		for (const cal_conf of config.calendars) {
-			if (cal_conf.dir_path) {
-				cal_conf.dir_path = resolve_path(config.input.root, cal_conf.dir_path);
+			if (cal_conf.in_dir) {
+				cal_conf.in_dir = resolve_path(config.input.root, cal_conf.in_dir);
 				cal_conf.out_file = resolve_path(config.output.root, cal_conf.out_file);
 			}
 		}
@@ -136,3 +162,11 @@ function process_markdown_config(config: any) {
 		}
 	}
 }
+
+function resolve_env_var_if_needed<T>(value: T | { from_env: string }) : T | string {
+	if (typeof value === 'object' && 'from_env' in value) {
+		return process.env[value.from_env];
+	}
+
+	return value;
+}

src/metadata.ts

@@ -1,16 +1,20 @@
 
 export interface Metadata {
-	last_build: {
-		time: string;
-		config_hash: string;
-	};
+	last_build: BuildMetadata;
 	files: {
-		[file_path: string]: {
-			first_seen_time: string;
-			last_build_hash: string;
-			last_updated_time: string;
-		};
+		[file_path: string]: FileMetadata;
 	};
 }
 
+export interface BuildMetadata {
+	time: string;
+	config_hash: string;
+}
+
+export interface FileMetadata {
+	first_seen_time: string;
+	last_build_hash: string;
+	last_updated_time: string;
+}
+
 // 

src/template.ts

@@ -1,5 +1,5 @@
 
-import { Config } from './conf';
+import { AuthorConfig, CalendarConfig, Config, RSSConfig } from './conf';
 import { render as mustache_render } from 'mustache';
 import { promises as fs } from 'fs';
 import { resolve as resolve_path } from 'path';
@@ -7,30 +7,94 @@ import { glob } from 'glob';
 import { load_from_dir } from './fs';
 import { ColorTheme } from '@doc-utils/color-themes';
 import { ThemeGroups } from './build-files';
+import { ChangeFreq } from './build-files/sitemap';
 
 export interface Context {
 	env?: Record<string, string>;
 	page?: FrontMatter;
 	base_url: string;
 	page_url: string;
+	page_published: ContextTime;
+	page_updated: ContextTime;
+	site_title: string;
+	author: AuthorConfig | AuthorConfig[];
+	event?: ContextEvent | ContextEvent[];
+	event_series?: {
+		start?: ContextTime;
+		end?: ContextTime;
+	};
 	icons: Record<string, string>;
 	themes: ColorTheme[];
 	theme_groups: ThemeGroups;
-	build_time: {
-		iso: string;
-		rfc2822: string;
-	};
+	rss_feeds: RSSConfig[];
+	calendars: CalendarConfig[];
+	build_time: ContextTime;
 	markdown: {
 		render_inline(): MustacheRenderer;
 	}
 }
 
-export interface FrontMatter {
+export interface ContextTime {
+	iso: string;
+	rfc2822: string;
+	html: string;
+}
+
+export interface ContextEvent {
 	title?: string;
+	start?: ContextTime;
+	end?: ContextTime;
+	time_zone?: `${string}/${string}`;
+	location?: ContextLocation;
+}
+
+export interface ContextLocation {
+	description?: string;
+	lat?: string;
+	long?: string;
+	// todo: represent this better?
+	address?: string;
+}
+
+export interface FrontMatter {
+	skip?: boolean;
 	layout?: string;
+	title?: string;
+	description?: string;
+	tags?: string[];
+	author?: string | string[];
+	rss?: RSSFrontmatter;
+	sitemap?: SitemapFrontmatter;
+	event?: EventFrontmatter | EventFrontmatter[];
 	[key: string]: unknown;
 }
 
+export interface SitemapFrontmatter {
+	skip?: boolean;
+	change_freq?: ChangeFreq;
+	priority?: number;
+}
+
+export interface EventFrontmatter {
+	title?: string;
+	start?: string;
+	end?: string;
+	time_zone?: `${string}/${string}`;
+	location?: FrontMatterLocation;
+}
+
+export interface FrontMatterLocation {
+	description?: string;
+	lat?: string;
+	long?: string;
+	// todo: represent this better?
+	address?: string;
+}
+
+export interface RSSFrontmatter {
+	skip?: boolean;
+}
+
 export function render_template(template: string, context: Context, layout?: string, partials: Record<string, string> = { }, tags?: [ string, string ]) {
 	partials['.content'] = template;
 	return mustache_render(layout || template, context, partials, tags);
@@ -40,6 +104,7 @@ export async function load_extras() {
 	const extras: Record<string, string> = Object.create(null);
 	const extras_dir = resolve_path(__dirname, '../extras');
 	const extras_files = [
+		'svg-links.js',
 		'components/color-scheme-toggle-button.js',
 		'components/outline-button.js',
 		'components/outline-inline.js',
@@ -51,6 +116,7 @@ export async function load_extras() {
 		'forms-inputs/spacious.css',
 		'forms-inputs/compact.css',
 		'forms-inputs/general.css',
+		'figures.css',
 	];
 
 	const promises = extras_files.map((file) => load_from_dir(extras_dir, file));

src/time.ts

@@ -0,0 +1,32 @@
+
+import { DateTime } from 'luxon';
+
+export function now(zone?: string) {
+	return zone
+		? DateTime.now().setZone(zone)
+		: DateTime.now();
+}
+
+export function from_iso(time: string, zone?: string) {
+	return zone
+		? DateTime.fromISO(time, { zone })
+		: DateTime.fromISO(time);
+}
+
+export function as_html_time(time: DateTime, classname = '', lang?: string, config?: Intl.DateTimeFormatOptions) {
+	if (lang && config) {
+		const formatter = new Intl.DateTimeFormat(lang, config);
+		const formatted = formatter.format(new Date(time.toISO()));
+		return `<time datetime="${time.toISO()}">${formatted}</time>`;
+	}
+
+	return `<time class="${classname}" datetime="${time.toISO()}">${time.toRFC2822()}</time>`;
+}
+
+export function as_context_time(time: DateTime, classname = '', lang?: string, config?: Intl.DateTimeFormatOptions) {
+	return {
+		iso: time.toISO(),
+		rfc2822: time.toRFC2822(),
+		html: as_html_time(time, classname, lang, config),
+	};
+}