@abreen/tada 1.0.2 → 1.2.0

package/README.md

@@ -11,18 +11,19 @@ A static site generator. The successor to Presto.
   * Renders headings, alert boxes, and `<hr>` elements
   * Highlights the heading currently being viewed
 - Built-in search powered by [Pagefind][pagefind]
-  * Only pages reachable by links on the site appear in search results
+  * Only pages in `content/` reachable from `/index.html` are indexed
 - Generated HTML pages for source code
   * Automatic code highlighting, clickable line numbers
   * Dynamic table of contents for each method/function
   * Converts new Markdown comment syntax ([added in Java 23][jep467]) to HTML
-  * Indexed by Pagefind
+  * Indexed by Pagefind (classes, interfaces, methods, and fields)
 - PDF files are copied into `dist/`
   - Text of each PDF page is extracted using [mutool][mutool] and indexed
 - External link handling (special visual treatment for external links)
 - Internal link validation at build time (broken links fail the build)
 - Internal links automatically prefixed with base path, if specified
 - Time zone chooser (automatically adjusts `<datetime>` elements)
+- LaTeX math rendered at build time via [KaTeX][katex]
 - Extended Markdown syntax
   * `<<< details ... <<<` renders a collapsible box
   * `::: section ... :::` renders a special section with a fancy background
@@ -69,22 +70,27 @@ Visit [http://localhost:8080/index.html](http://localhost:8080/index.html).
 ### `tada init <dirname>`
 
 Create a new Tada site in a new directory. Prompts for:
-- **Site title** --- displayed in the header and `<title>` tag
-- **Symbol** --- short text (1-5 uppercase characters) shown in the logo and favicon
-- **Theme color** --- HSL color, e.g. `hsl(195 70% 40%)`
-- **Background tint hue** --- hue (0-360) for background/foreground tinting (defaults to `20`)
-- **Background tint amount** --- percentage (0-100) of tint to apply (defaults to `100`)
-- **Default time zone** --- for `<datetime>` elements (defaults to your system zone)
-- **Production base URL** --- e.g. `https://example.edu`
-- **Production base path** --- e.g. `/cs101` (defaults to `/`)
+- **Site title**: displayed in the header and `<title>` tag
+- **Symbol**: short text (1-5 uppercase characters) shown in the logo and favicon
+- **Theme color**: HSL color, e.g. `hsl(195 70% 40%)`
+- **Background tint hue**: hue (0-360) for background/foreground tinting (defaults to `20`)
+- **Background tint amount**: percentage (0-100) of tint to apply (defaults to `100`)
+- **Default time zone**: for `<time>` elements (defaults to your system zone)
+- **Production base URL**: e.g. `https://example.edu`
+- **Production base path**: e.g. `/cs101` (defaults to `/`)
 
-Pass `--default` to use the default values for all options without being
-prompted.
+Pass `--no-interactive` to skip prompts and use default values for all options.
+You can also override specific defaults with flags:
+
+    tada init mysite --no-interactive --prod-base https://example.edu --prod-base-path /cs101
+
+Available flags: `--title`, `--symbol`, `--theme-color`, `--tint-hue`,
+`--tint-amount`, `--default-time-zone`, `--prod-base`, `--prod-base-path`.
 
 
 ### `tada dev`
 
-Build the site for local development (using `config/site.dev.json`)
+Build the site for local development (using `site.dev.json`)
 into the `dist/` directory.
 
 
@@ -101,12 +107,69 @@ Start a development web server, watch for changes and rebuild automatically.
 
 ### `tada clean`
 
-Remove the `dist/` directory.
+Remove the `dist/` directory. Pass `--prod` to also prune old production
+builds (keeps the latest two versions).
 
 
 ### `tada prod`
 
-Build the site for production (uses `config/site.prod.json`).
+Build the site for production (uses `site.prod.json`). Each prod build is
+saved to a versioned directory under `dist-prod/` (e.g., `dist-prod/v1/`,
+`dist-prod/v2/`) with a manifest file that records the SHA-256 hash of every
+output file.
+
+
+### `tada diff`
+
+Compare two production builds and list added, changed, and removed files.
+With no arguments, compares the last two builds. You can also specify version
+numbers explicitly:
+
+    tada diff          # compare latest two builds
+    tada diff 1 3      # compare v1 and v3
+
+Use `--copy <dir>` to copy only the changed and added files to a directory:
+
+    tada diff --copy upload/
+
+The output directory will also include a `manifest.json` for the newer build.
+
+
+## Development vs. production builds
+
+`tada dev` and `tada watch` build to the `dist/` directory using
+`site.dev.json` (typically `localhost` URLs). `tada watch` includes a
+development server with live reload; `tada serve` is a standalone server
+for previewing a `tada dev` build. Dev builds overwrite `dist/` each time.
+
+`tada prod` builds to a new versioned directory under `dist-prod/` each time
+it runs. Previous production builds are preserved, so you can compare any
+two versions with `tada diff`.
+
+
+## Deploying to S3
+
+If you host your site in an S3 bucket, `tada diff --copy` lets you upload
+only the files that changed between prod builds instead of re-uploading
+everything.
+
+First time:
+
+```
+tada prod
+# Upload the entire dist-prod/v1/ directory to your S3 bucket
+```
+
+After making changes:
+
+```
+tada prod
+tada diff --copy upload/
+# Upload just the upload/ directory to S3 (only changed files)
+```
+
+If `tada diff` reports removed files, delete those from your S3 bucket
+manually.
 
 
 ## Prerequisites
@@ -125,10 +188,10 @@ Build the site for production (uses `config/site.prod.json`).
 
 Build-time site config lives in:
 
-- `config/site.dev.json` (used by `tada dev` / `tada watch`)
-- `config/site.prod.json` (used by `tada prod`)
-- `config/nav.json` (navigation structure)
-- `config/authors.json` (author data)
+- `site.dev.json` (used by `tada dev` / `tada watch`)
+- `site.prod.json` (used by `tada prod`)
+- `nav.json` (navigation structure)
+- `authors.json` (author data)
 
 Example site configuration JSON file:
 
@@ -156,7 +219,7 @@ Example site configuration JSON file:
 | `title` | Title for the whole site (also used to derive `titlePostfix`) |
 | `titlePostfix` | *Optional*, the string to append to each page's `title` |
 | `symbol` | Text (1-5 chars) displayed in header (also used as the favicon symbol) |
-| `themeColor` | HSL theme color for the site, e.g. `"hsl(195 70% 40%)"` |
+| `themeColor` | Theme color for the site (e.g., `"tomato"`, `"#c04040"`, `"hsl(195 70% 40%)"`) |
 | `tintHue` | *Optional*, hue (0-360) for background and foreground tinting (default `20`) |
 | `tintAmount` | *Optional*, percentage (0-100) of tint to apply (default `100`) |
 | `faviconSymbol` | *Optional*, the text to use instead of `symbol` in the favicon |
@@ -167,7 +230,7 @@ Example site configuration JSON file:
 | `basePath` | URL prefix for deployment under a subpath (e.g., `"/cs101"`), use `"/"` at root |
 | `internalDomains` | Domain names treated as internal by link processing (not marked external) |
 | `codeLanguages` | Map file extension to Shiki language (e.g., `"java": "java"`) |
-| `faviconColor` | *Optional*, HSL color override for favicon (defaults to `themeColor`) |
+| `faviconColor` | *Optional*, background color for favicon (defaults to `themeColor`) |
 | `faviconFontWeight` | *Optional*, font weight used for favicon text (default `700`) |
 | `vars` | Arbitrary key/value variables exposed to templates/content (e.g., `<%= staffEmail %>`) |
 
@@ -224,27 +287,15 @@ with `name`, `avatar`, and optionally `url`.
 ```
 
 
-### Log level
-
-Set the `TADA_LOG_LEVEL` environment variable to control build log verbosity.
-Valid levels (from most to least verbose): `debug`, `info`, `warn`, `error`.
-The default level is `info`. To see *all* logs generated by Tada, set the env
-var to `debug`:
-
-```
-TADA_LOG_LEVEL=debug tada dev
-```
-
-
 ## Content
 
 Site content lives in the `content/` directory. Markdown is converted to HTML.
-HTML files should contain front matter and are also built, but not processed
-like Markdown files are.
+HTML files should contain front matter and are also built.
+
+Any other kinds of files are copied into `dist/` in the same locations.
 
-PDF, `.txt`, ZIP, images, and other kinds of files are copied into `dist/`
-in the same locations. All files in `public/` are copied directly into `dist/`
-with zero processing.
+All files in `public/` are copied directly into `dist/` with zero processing.
+Files in `public/` are **not** included in the search index.
 
 
 ### Front matter fields
@@ -256,31 +307,27 @@ list of variables parsed using the [`front-matter`][front-matter] library).
 |-------|-------------|
 | `title` (required) | Page title (`<title>` tag and page heading) |
 | `skip` | Set to `true` to skip building this page completely |
-| `author` | Author handle (e.g. `jsmith`) resolved to a full object via `config/authors.json` |
+| `author` | Author handle (e.g. `jsmith`) resolved to a full object via `authors.json` |
 | `description` | Meta description for the page |
 | `toc` | Set to `true` to show a table of contents |
 | `parent` & `parentLabel` | URL and label for a breadcrumb link displayed above the title |
 | `published` | Year, month, and day of publishing (e.g, `2025-09-09`) |
 
+You may also add arbitrary fields in a page's front matter, and access them
+using Lodash syntax (see below).
+
 
 ### Variable substitution
 
 Plain text content (e.g., HTML and Markdown) are processed using [Lodash
 templates][lodash].
 
-- Site config values are available under `site` (e.g., `site.title`, `site.symbol`)
-- Page variables (from front matter) are available under `page` (e.g., `page.author`)
+- Site config values are available under `site` (e.g., `site.title`)
+- Page variables (from front matter) are available under `page`
 - Custom variables from the `"vars"` property of the config are available
   without any prefix (e.g., `<%= staffEmail %>`)
 
 
-## Templates
-
-HTML page layouts are internal to the Tada package. You don't need to modify
-them; they are designed to work with the client-side components and styles
-bundled in the package.
-
-
 
 [inter]: https://fonts.google.com/specimen/Inter
 [lodash]: https://lodash.info/doc/template
@@ -288,3 +335,4 @@ bundled in the package.
 [pagefind]: https://pagefind.app/
 [mutool]: https://mupdf.readthedocs.io/en/latest/tools/mutool.html
 [jep467]: https://openjdk.org/jeps/467
+[katex]: https://katex.org/