Switch 11ty config from JS to TS (#6255)

Resolves #6254

- Add a config for TypeScript and enabling running the TypeScript files
- Convert existing 11ty-related files from JS to TS
- Convert type annotations from JS doc to TS doc
- Add other missing type annotations
- Fix a few surfaced issues

This makes the code more self documenting and will help facilitate
automated linting and formatting of the code in the future.

eleventy.config.js → eleventy.config.ts

@@ -2,10 +2,11 @@
 // It configures the core 11ty behavior and registers
 // plugins and customization that live in `/src/_11ty`.
 
-import { registerFilters } from './src/_11ty/filters.js';
-import { registerShortcodes } from './src/_11ty/shortcodes.js';
-import { markdown } from './src/_11ty/plugins/markdown.js';
-import { configureHighlighting } from './src/_11ty/plugins/highlight.js';
+import {registerFilters} from './src/_11ty/filters.js';
+import {registerShortcodes} from './src/_11ty/shortcodes.js';
+import {markdown} from './src/_11ty/plugins/markdown.js';
+import {configureHighlighting} from './src/_11ty/plugins/highlight.js';
+import {UserConfig} from '@11ty/eleventy';
 
 import minifier from 'html-minifier-terser';
 import yaml from 'js-yaml';
@@ -14,13 +15,9 @@ import * as path from 'node:path';
 import * as sass from 'sass';
 
 // noinspection JSUnusedGlobalSymbols
-/**
- * @typedef {import('11ty/eleventy/UserConfig')} EleventyConfig
- * @param {EleventyConfig} eleventyConfig
- */
-export default function (eleventyConfig) {
-  const isProduction = process.env.PRODUCTION === 'true';
-  const shouldOptimize = process.env.OPTIMIZE === 'true';
+export default function (eleventyConfig: UserConfig) {
+  const isProduction = process.env['PRODUCTION'] === 'true';
+  const shouldOptimize = process.env['OPTIMIZE'] === 'true';
 
   eleventyConfig.on('eleventy.before', async () => {
     await configureHighlighting(markdown);
@@ -30,7 +27,7 @@ export default function (eleventyConfig) {
 
   eleventyConfig.setLibrary('md', markdown);
 
-  eleventyConfig.addDataExtension('yml,yaml', (contents) =>
+  eleventyConfig.addDataExtension('yml,yaml', (contents: string) =>
     yaml.load(contents),
   );
 
@@ -48,7 +45,7 @@ export default function (eleventyConfig) {
   eleventyConfig.addWatchTarget('src/_sass');
   eleventyConfig.addExtension('scss', {
     outputFileExtension: 'css',
-    compile: function (inputContent, inputPath) {
+    compile: function (inputContent: string, inputPath: string) {
       const parsedPath = path.parse(inputPath);
       if (parsedPath.name.startsWith('_')) {
         return;
@@ -88,7 +85,7 @@ export default function (eleventyConfig) {
   if (shouldOptimize) {
     // If building for production, minify/optimize the HTML output.
     // Doing so during serving isn't worth the extra build time.
-    eleventyConfig.addTransform('minify-html', async function (content) {
+    eleventyConfig.addTransform('minify-html', async function (content: string) {
       if (this.page.outputPath && this.page.outputPath.endsWith('.html')) {
         // Minify the page's content if it's an HTML file.
         // Other options can be enabled, but each should be tested.

package.json

@@ -9,9 +9,9 @@
     "url": "https://github.com/dart-lang/site-www.git"
   },
   "scripts": {
-    "serve": "PRODUCTION=false eleventy --serve",
-    "build-site-for-staging": "PRODUCTION=false OPTIMIZE=true eleventy",
-    "build-site-for-production": "PRODUCTION=true OPTIMIZE=true eleventy"
+    "serve": "PRODUCTION=false tsx node_modules/@11ty/eleventy/cmd.cjs --serve --config=eleventy.config.ts",
+    "build-site-for-staging": "PRODUCTION=false OPTIMIZE=true tsx node_modules/@11ty/eleventy/cmd.cjs --config=eleventy.config.ts",
+    "build-site-for-production": "PRODUCTION=true OPTIMIZE=true tsx node_modules/@11ty/eleventy/cmd.cjs --config=eleventy.config.ts"
   },
   "engines": {
     "node": ">=20.14.0",
@@ -23,6 +23,9 @@
   },
   "devDependencies": {
     "@11ty/eleventy": "^3.0.0",
+    "@types/hast": "^3.0.4",
+    "@types/markdown-it": "^14.1.2",
+    "@types/node": "^22.10.1",
     "firebase-tools": "^13.28.0",
     "hast-util-from-html": "^2.0.3",
     "hast-util-select": "^6.0.3",
@@ -35,6 +38,7 @@
     "markdown-it-container": "^4.0.0",
     "markdown-it-deflist": "^3.0.0",
     "sass": "^1.82.0",
-    "shiki": "^1.24.0"
+    "shiki": "^1.24.0",
+    "tsx": "^4.19.2"
   }
 }