@abreen/tada 1.8.1 → 1.10.1

package/init/content/lectures/01/index.md

@@ -8,6 +8,12 @@ author: alex
 
 Here is a sample description of the topics covered at the first lecture.
 
+The value of `vars.foobar` is <%= vars.foobar %>.
+
+You can add any variables you want to the `site.dev.json` and `site.prod.json`
+files under the `"vars"` property and access them using Lodash template syntax
+from Markdown files, HTML files, and source code. (Lodash template subtitution
+only works in source code files when `features.code` is `true`.)
 
 ## Slides
 

package/init/content/lectures/01/rectangle.py

@@ -1,3 +1,8 @@
+#
+# rectangle.py
+#
+# Here's vars.foobar: <%= vars.foobar %>
+#
 class Rectangle:
     """A rectangle with integer side lengths.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abreen/tada",
-  "version": "1.8.1",
+  "version": "1.10.1",
   "type": "module",
   "description": "A static site generator",
   "license": "MIT",
@@ -15,26 +15,37 @@
   "files": [
     "bin/",
     "build/",
+    "watch/",
     "src/",
     "templates/",
     "fonts/",
     "init/",
     "schema/",
     "types/",
+    "python/",
     "tsconfig.json",
-    "!**/*.test.ts"
+    "!**/*.test.ts",
+    "!**/__pycache__",
+    "!**/__pycache__/**",
+    "!**/*.pyc"
   ],
   "scripts": {
-    "prepare": "bunx husky && bun run scripts/check-deps.ts",
-    "prepack": "bun run scripts/prepack.ts",
+    "prepare": "bunx husky",
+    "check-deps": "bun run scripts/check-deps.ts",
+    "init-example": "bun run bin/tada.ts init example --no-interactive",
+    "iew": "bun run scripts/init-example-watch.ts",
     "lint": "eslint src/ build/ bin/",
+    "lint:sass": "bun run scripts/lint-sass.ts",
     "typecheck": "tsc --noEmit",
+    "format": "prettier --write \"**/*.{ts,js,scss,json}\"",
+    "test:playwright": "bun run scripts/test.ts playwright",
     "test:functional": "bun run scripts/test.ts functional",
     "test:all": "bun run scripts/test.ts all",
     "test:coverage": "bun run scripts/test.ts coverage",
-    "test:playwright": "bun run scripts/test.ts playwright",
-    "init-example": "bun run bin/tada.ts init example --no-interactive",
-    "iew": "if [ -d example ]; then cd example; else bun run init-example && cd example; fi && ../bin/tada.ts watch"
+    "setup:python": "bun run scripts/setup-python.ts",
+    "lint:python": "bun run scripts/python-module.ts ruff check functional_tests/",
+    "fix:python": "bun run scripts/python-module.ts ruff check --fix functional_tests/",
+    "format:python": "bun run fix:python && bun run scripts/python-module.ts ruff format functional_tests/"
   },
   "engines": {
     "bun": ">=1.0.0"
@@ -46,8 +57,8 @@
   ],
   "dependencies": {
     "@vscode/markdown-it-katex": "^1.1.2",
-    "ajv": "^8.17.1",
-    "chokidar": "^4.0.0",
+    "ajv": "^8.18.0",
+    "chokidar": "^4.0.3",
     "culori": "^4.0.2",
     "d3-flextree": "^2.1.2",
     "d3-hierarchy": "^3.1.2",
@@ -55,36 +66,40 @@
     "front-matter": "^4.0.2",
     "java-parser": "^3.0.1",
     "jsdom": "^26.1.0",
-    "katex": "^0.16.40",
-    "lodash": "^4.17.21",
-    "markdown-it": "^14.1.0",
+    "katex": "^0.16.45",
+    "lodash": "^4.18.1",
+    "markdown-it": "^14.1.1",
     "markdown-it-anchor": "^9.2.0",
     "markdown-it-container": "^4.0.0",
     "markdown-it-deflist": "^3.0.0",
     "markdown-it-footnote": "^4.0.0",
-    "pagefind": "^1.4.0",
+    "pagefind": "^1.5.2",
     "png-to-ico": "^3.0.1",
     "quote-quote": "^1.2.0",
-    "sass": "^1.91.0",
+    "sass": "^1.99.0",
     "sharp": "^0.34.5",
-    "shiki": "^4.0.1",
+    "shiki": "^4.0.2",
     "string-strip-html": "^8.5.0",
-    "ws": "^8.18.0"
+    "ws": "^8.20.0"
   },
   "lint-staged": {
     "*.{ts,js}": "prettier --write",
     "*.scss": "prettier --write",
-    "*.json": "prettier --write"
+    "*.json": "prettier --write",
+    "functional_tests/**/*.py": [
+      "bun run scripts/python-module.ts ruff check --fix",
+      "bun run scripts/python-module.ts ruff format"
+    ]
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@playwright/test": "^1.59.1",
     "@saintedlama/lcov-parse": "^1.0.1",
-    "@types/bun": "^1.3.10",
+    "@types/bun": "^1.3.12",
     "@types/culori": "^4.0.1",
     "@types/d3-flextree": "^2.1.4",
     "@types/d3-hierarchy": "^3.1.7",
-    "@types/fontkit": "^2.0.8",
+    "@types/fontkit": "^2.0.9",
     "@types/istanbul-lib-coverage": "^2.0.6",
     "@types/istanbul-lib-instrument": "^1.7.8",
     "@types/istanbul-lib-report": "^3.0.3",
@@ -92,16 +107,20 @@
     "@types/lodash": "^4.17.24",
     "@types/markdown-it-container": "^4.0.0",
     "@types/ws": "^8.18.1",
-    "eslint": "^10.0.3",
+    "eslint": "^10.2.1",
     "husky": "^9.1.7",
     "istanbul-lib-coverage": "^3.2.2",
     "istanbul-lib-instrument": "^6.0.3",
     "istanbul-lib-report": "^3.0.1",
     "istanbul-reports": "^3.2.0",
     "lint-staged": "^16.4.0",
-    "prettier": "^3.6.2",
+    "postcss-scss": "^4.0.9",
+    "prettier": "^3.8.3",
     "prettier-plugin-curly": "^0.4.1",
-    "typescript": "^5.4.5",
-    "typescript-eslint": "^8.57.1"
+    "stylelint": "^17.8.0",
+    "stylelint-config-recess-order": "^7.7.0",
+    "stylelint-config-standard-scss": "^17.0.0",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.58.2"
   }
 }

package/python/command.ts

@@ -0,0 +1,95 @@
+import {
+  execFileSync,
+  spawnSync,
+  type ExecFileSyncOptionsWithStringEncoding,
+  type SpawnSyncOptions,
+} from 'child_process';
+
+export interface PythonCommand {
+  shell: 'direct' | 'powershell';
+  command: 'python' | 'python3';
+}
+
+const WINDOWS_PYTHON_CANDIDATES = ['python', 'python3'] as const;
+
+function psQuote(arg: string): string {
+  return `'${arg.replaceAll("'", "''")}'`;
+}
+
+function buildPowerShellArgs(
+  command: PythonCommand['command'],
+  args: string[],
+): string[] {
+  return [
+    '-NoProfile',
+    '-NonInteractive',
+    '-Command',
+    [command, ...args.map(psQuote)].join(' '),
+  ];
+}
+
+function commandExists(
+  command: string,
+  args: string[] = ['--version'],
+): boolean {
+  return spawnSync(command, args, { stdio: 'ignore' }).status === 0;
+}
+
+export function resolvePythonCommand(): PythonCommand | null {
+  if (process.platform === 'win32') {
+    for (const command of WINDOWS_PYTHON_CANDIDATES) {
+      if (commandExists(command)) {
+        return { shell: 'direct', command };
+      }
+    }
+
+    for (const command of WINDOWS_PYTHON_CANDIDATES) {
+      if (
+        commandExists(
+          'powershell.exe',
+          buildPowerShellArgs(command, ['--version']),
+        )
+      ) {
+        return { shell: 'powershell', command };
+      }
+    }
+
+    return null;
+  }
+
+  return commandExists('python3')
+    ? { shell: 'direct', command: 'python3' }
+    : null;
+}
+
+export function execFileSyncPython(
+  args: string[],
+  options: ExecFileSyncOptionsWithStringEncoding,
+  python: PythonCommand,
+): string {
+  if (python.shell === 'direct') {
+    return execFileSync(python.command, args, options);
+  }
+
+  return execFileSync(
+    'powershell.exe',
+    buildPowerShellArgs(python.command, args),
+    options,
+  );
+}
+
+export function spawnSyncPython(
+  args: string[],
+  options: SpawnSyncOptions,
+  python: PythonCommand,
+) {
+  if (python.shell === 'direct') {
+    return spawnSync(python.command, args, options);
+  }
+
+  return spawnSync(
+    'powershell.exe',
+    buildPowerShellArgs(python.command, args),
+    options,
+  );
+}

package/python/module.ts

@@ -0,0 +1,18 @@
+import { resolvePythonCommand, spawnSyncPython } from './command';
+
+export function runPythonModuleSync(
+  moduleName: string,
+  args: string[],
+  options: { env?: NodeJS.ProcessEnv; stdio?: 'inherit' | 'ignore' } = {},
+): number {
+  const pythonCommand = resolvePythonCommand();
+  if (!pythonCommand) {
+    console.error(`Error: Python is required to run the ${moduleName} module.`);
+    return 1;
+  }
+
+  return (
+    spawnSyncPython(['-m', moduleName, ...args], options, pythonCommand)
+      .status ?? 1
+  );
+}

package/src/_alerts.scss

@@ -1,9 +1,9 @@
 @use 'mixins' as *;
 
 .alert {
-  border: 2px solid var(--bg2-color);
   position: relative;
   margin: 1rem 0;
+  border: 2px solid var(--bg2-color);
 }
 
 .alert.warning {
@@ -29,8 +29,8 @@
 
   tt,
   code {
-    background: inherit;
     padding: inherit;
+    background: inherit;
   }
 
   time[datetime].is-modified {
@@ -40,6 +40,7 @@
 
   a {
     @include link-underline;
+
     color: var(--fg-color);
 
     &:hover {
@@ -65,12 +66,12 @@
 }
 
 .alert .title::before {
-  content: '';
-  left: 8px;
-  top: 8px;
   position: absolute;
+  top: 8px;
+  left: 8px;
   width: 32px;
   height: 32px;
+  content: '';
 }
 
 .alert.warning .title::before {
@@ -79,9 +80,10 @@
 
 i.warning {
   @include contained-mask(var(--icon-warning));
+
   display: inline-block;
-  height: 1em;
   width: 1em;
+  height: 1em;
   vertical-align: sub;
 }
 
@@ -90,10 +92,11 @@ i.warning {
 }
 
 .alert .title {
-  font-weight: 700;
-  @include user-select(none);
   padding-left: 48px;
   margin: 0;
+  font-weight: 700;
+
+  @include user-select(none);
 }
 
 .alert > p:last-child {

package/src/_base.scss

@@ -2,16 +2,13 @@
 
 :root {
   --box-border-width: 5px;
-
   --gap: 12px;
   --border-radius: 12px;
   --control-border-width: 2px;
   --label-border-width: 2px;
-
   --table-padding: 12px;
   --details-padding: 12px;
   --section-padding: 64px;
-
   --main-width: 900px;
 }
 
@@ -22,9 +19,9 @@ h4,
 h5,
 h6 {
   font-family: var(--heading-font);
+  line-height: 1.3;
   -webkit-break-after: avoid;
   break-after: avoid;
-  line-height: 1.3;
 }
 
 h1 {
@@ -33,13 +30,9 @@ h1 {
 }
 
 body {
-  color: var(--fg-color);
-  background-color: var(--bg-color);
-
   font-family: var(--font);
   font-size: var(--font-size);
   font-weight: var(--font-weight);
-  line-height: var(--line-height);
 
   /*
    * Enable Inter's features:
@@ -51,12 +44,13 @@ body {
    * cv10 - capital G with spur (style)
    */
   font-feature-settings: 'liga', 'calt', 'ss03', 'cv01', 'cv05', 'cv10';
+  line-height: var(--line-height);
+  color: var(--fg-color);
+  background-color: var(--bg-color);
 
   @media (prefers-color-scheme: dark) {
-    & {
-      text-rendering: optimizeLegibility;
-      -webkit-font-smoothing: antialiased;
-    }
+    text-rendering: optimizelegibility;
+    -webkit-font-smoothing: antialiased;
   }
 }
 
@@ -72,6 +66,7 @@ a {
   @media (hover: hover) {
     &:hover {
       color: var(--link-color-hover);
+
       @include link-underline;
     }
   }
@@ -89,26 +84,25 @@ code {
 
 tt,
 code {
+  padding: var(--mono-padding);
   font-size: var(--mono-font-size);
+  overflow-wrap: anywhere;
   background: var(--bg2-color);
   border-radius: var(--mono-border-radius);
-  padding: var(--mono-padding);
-  overflow-wrap: anywhere;
 }
 
 pre {
-  background: var(--bg2-color);
-  border-radius: var(--mono-border-radius);
+  padding: var(--gap);
+  overflow: auto hidden;
+  overscroll-behavior-x: none;
   font-size: var(--mono-font-size);
   line-height: var(--mono-line-height);
-  overflow-x: auto;
-  overflow-y: hidden;
-  overscroll-behavior-x: none;
-  padding: var(--gap);
+  background: var(--bg2-color);
+  border-radius: var(--mono-border-radius);
 
   code {
-    font-size: inherit;
     padding: 0;
+    font-size: inherit;
   }
 }
 
@@ -121,9 +115,10 @@ details .content > *:last-child {
 }
 
 details summary {
+  padding: var(--details-padding);
   cursor: pointer;
+
   @include user-select(none);
-  padding: var(--details-padding);
 }
 
 main details summary:focus {
@@ -143,6 +138,7 @@ details .content {
 @media (hover: hover) {
   details summary:hover {
     color: var(--fg2-color);
+
     @include link-underline;
   }
 }
@@ -153,34 +149,34 @@ details summary:active {
 
 main details {
   margin-bottom: 1rem;
-  border-radius: var(--border-radius);
   border: 2px solid var(--fg-color);
+  border-radius: var(--border-radius);
 }
 
 input[type='text'],
 input[type='search'] {
+  padding: 4px;
   font-family: var(--font);
-  background: var(--bg-color);
+  font-size: 12pt;
   color: var(--fg-color);
+  background: var(--bg-color);
   border: var(--control-border-width) solid var(--fg2-color);
   border-radius: var(--border-radius);
-  font-size: 12pt;
-  padding: 4px 4px;
 }
 
 input[type='search'] {
+  min-width: 0;
+  padding-left: 2rem;
   background-color: var(--bg-color);
   background-image: var(--icon-search);
   background-repeat: no-repeat;
   background-position: left 6px center;
   background-size: 16px 16px;
-  padding-left: 2rem;
   border-radius: 18px;
-  min-width: 0;
 
   &:disabled {
-    opacity: 0.4;
     cursor: not-allowed;
+    opacity: 0.4;
   }
 }
 

package/src/_layout.scss

@@ -5,15 +5,15 @@
 }
 
 html {
-  margin: 0;
   padding: 0;
+  margin: 0;
   overflow-y: auto;
   scroll-padding-top: calc(var(--header-collapsed-height) + var(--gap));
 }
 
 body {
-  margin: 0;
   padding: 0;
+  margin: 0;
 }
 
 body > .container {
@@ -74,8 +74,8 @@ body.literate main table {
 
   body.default.toc-is-active nav.toc,
   body.literate.toc-is-active nav.toc {
-    background: var(--bg2-color);
     padding: var(--gap);
+    background: var(--bg2-color);
   }
 
   body.code.toc-is-active nav.toc {
@@ -107,21 +107,21 @@ body.literate main table {
   }
 
   .toc-is-active .main-content > .body {
-    order: 1;
     flex: 1;
+    order: 1;
     min-width: 0;
   }
 
   body.toc-is-active nav.toc {
+    position: sticky;
+    top: var(--header-collapsed-height);
     box-sizing: border-box;
-    width: var(--toc-width);
     flex-shrink: 0;
     align-self: flex-start;
-    position: sticky;
-    top: var(--header-collapsed-height);
+    width: var(--toc-width);
     height: calc(100vh - var(--header-collapsed-height));
-    overflow-y: auto;
     margin-bottom: 0;
+    overflow-y: auto;
   }
 
   body.code.toc-is-active nav.toc {
@@ -130,7 +130,7 @@ body.literate main table {
   }
 }
 
-@media (min-width: 1300px) {
+@media (width >= 1300px) {
   .toc-is-active .main-content {
     max-width: calc(var(--toc-width) + var(--gap) + 960px);
     margin: 0 auto;
@@ -139,11 +139,12 @@ body.literate main table {
 
 .info {
   @include user-select(none);
+
   display: grid;
   grid-template-columns: 1fr auto;
   align-items: baseline;
-  color: var(--fg2-color);
   font-size: var(--font-size-smaller);
+  color: var(--fg2-color);
 
   @media (width < 450px) {
     grid-template-columns: 1fr;
@@ -186,8 +187,8 @@ body.literate main table {
     .avatar {
       width: 24px;
       height: 24px;
-      vertical-align: middle;
       margin-left: 4px;
+      vertical-align: middle;
       border: 1px solid transparent;
     }
   }
@@ -201,9 +202,10 @@ body.literate main table {
 
 footer {
   @include user-select(none);
-  text-align: center;
+
   padding: 2rem 0 1rem;
   color: var(--fg2-color);
+  text-align: center;
 
   a {
     color: var(--fg2-color);
@@ -220,12 +222,13 @@ footer {
     }
 
     &::after {
-      content: '';
       display: inline-block;
       width: 1.5em;
       height: 1.5em;
-      vertical-align: middle;
       margin-left: 0.2em;
+      vertical-align: middle;
+      content: '';
+
       @include contained-mask(var(--icon-tada));
     }
   }

package/src/_mixins.scss

@@ -5,8 +5,8 @@
 
 @mixin link-underline {
   text-decoration-line: underline;
-  text-decoration-color: currentColor;
   text-decoration-thickness: 1px;
+  text-decoration-color: currentcolor;
   text-underline-offset: 0.11rem;
 }
 
@@ -17,6 +17,7 @@
   @media (hover: hover) {
     &:hover {
       color: var(--fg2-color);
+
       @include link-underline;
     }
   }
@@ -27,23 +28,23 @@
 }
 
 @mixin contained-icon {
-  background-size: contain;
   background-repeat: no-repeat;
   background-position: center center;
+  background-size: contain;
 }
 
 @mixin contained-mask($url) {
+  // The icon's visible fill is the background color, which browsers strip
+  // when printing by default. Preserve it so masked icons remain visible.
+  -webkit-print-color-adjust: exact;
+  print-color-adjust: exact;
+  background-color: currentcolor;
   -webkit-mask-image: $url;
   mask-image: $url;
-  -webkit-mask-size: contain;
-  mask-size: contain;
   -webkit-mask-repeat: no-repeat;
   mask-repeat: no-repeat;
   -webkit-mask-position: center center;
   mask-position: center center;
-  background-color: currentColor;
-  // The icon's visible fill is the background color, which browsers strip
-  // when printing by default. Preserve it so masked icons remain visible.
-  -webkit-print-color-adjust: exact;
-  print-color-adjust: exact;
+  -webkit-mask-size: contain;
+  mask-size: contain;
 }

package/src/anchor/style.scss

@@ -3,17 +3,19 @@
 a.heading-anchor {
   position: relative;
   display: inline-block;
+
   @include subdued-link;
 }
 
 a.heading-anchor::after {
-  content: '';
   display: inline-block;
-  height: 1em;
   width: 1em;
+  height: 1em;
   margin-left: 4px;
   vertical-align: middle;
+  content: '';
   opacity: 0;
+
   @include contained-mask(var(--icon-anchor));
 }