docrev 0.9.18 → 0.10.0

package/issues.md

@@ -1,180 +0,0 @@
-# docrev — Open Issues
-
-Three issues identified during real-world use on the ADAPT proposal build. Working through one by one.
-
-Status legend: `[ ]` planned · `[~]` in progress · `[x]` shipped
-
----
-
-## Issue 1 — Allow custom pandoc filters / args through `rev build`  `[x]`
-
-### Problem
-
-Source markdown with custom raw-LaTeX commands needs a pandoc filter to convert them for docx (e.g. `\tofill{X}` → bold `[X]`). `rev build docx` has no escape hatch:
-
-- `rev build --help` exposes no `--filter` / `--lua-filter` / `--pandoc-arg`.
-- `rev.yaml` exposes `docx.reference` and `docx.keepComments` but no generic pandoc passthrough.
-
-Working around it requires letting `rev build` produce `paper.md` as a side effect, then calling pandoc manually — which defeats the point of `rev build`.
-
-### Design (agreed)
-
-**rev.yaml**: top-level `pandoc-args` (applied to every format) plus per-format `<format>.pandoc-args` (concatenated *after* the top-level list so format-specific can override):
-
-```yaml
-pandoc-args:
-  - --lua-filter=tofill_filter.lua
-docx:
-  pandoc-args:
-    - --lua-filter=docx_only.lua
-pdf:
-  pandoc-args:
-    - --variable=papersize:a4
-```
-
-**CLI**: repeatable `--pandoc-arg <arg>` on `rev build`, appended *after* config args so CLI wins:
-
-```bash
-rev build docx --pandoc-arg=--lua-filter=tofill.lua --pandoc-arg=--shift-heading-level-by=1
-```
-
-**Verbose mode**: `rev build --verbose` already exists but doesn't echo the pandoc invocation. Print the full `pandoc <args>` command (one line per format) so users can copy-paste to replicate manually.
-
-### Touch points
-
-- `lib/build.ts` — `BuildConfig` + `DEFAULT_CONFIG` (add `pandocArgs: string[]`; add `pandocArgs` to each format config), `buildPandocArgs()` (append top-level then format-specific), `runPandoc()` (echo command under verbose), `loadConfig()` (read hyphenated `pandoc-args` key and map to camelCase `pandocArgs`).
-- `lib/commands/build.ts` — add `--pandoc-arg <arg>` (repeatable via custom collector), forward through `BuildOptions`, ensure CLI args are appended last.
-- `lib/schema.ts` — declare `pandoc-args` (array of strings) at top level and inside each format object.
-- `skill/SKILL.md` + `skill/REFERENCE.md` — document new field and flag with a `--lua-filter=` example.
-- `test/build.test.js` — cover (a) top-level only, (b) format-specific only, (c) both concatenated in order, (d) CLI overrides config.
-
-### Open questions
-
-None. Hyphenated YAML key + camelCase TS field is consistent with how the rest of the schema is read (we're already free-form on the JS side, just need a small key transform in `loadConfig`).
-
----
-
-## Issue 2 — Output filename is auto-truncated mid-word and not configurable  `[x]`
-
-### Problem
-
-Default output landed at `output/adapt-alien-dark-diversity-across-plant-communitie.docx` — title slugified and hard-truncated at 50 chars (`communitie` missing the trailing `s`). No `-o` flag, no `output:` field in `rev.yaml`.
-
-Root cause: `lib/build.ts:1055-1056` (`runPandoc`) and `lib/commands/build.ts:591-592` (`--show-changes` path):
-
-```ts
-const baseName = config.title
-  ? config.title.toLowerCase().replace(/[^a-z0-9]+/g, '-').slice(0, 50)
-  : 'paper';
-```
-
-`.slice(0, 50)` is a blind cut.
-
-### Design (agreed)
-
-**rev.yaml**: per-format `output:` map. Extensions optional — added if missing.
-
-```yaml
-output:
-  docx: ADAPT_proposal_draft.docx
-  pdf: ADAPT_proposal_draft.pdf
-```
-
-**CLI**: `-o, --output <path>` on `rev build`. When multiple formats are built, applies as basename to all (extension swapped per format); for single-format builds, used verbatim.
-
-**Truncation fix**: when no `output:` is configured, slug at last `-` boundary at-or-before 50 chars instead of mid-word. Also bump the cap to 80 — 50 is conservative.
-
-**Doc fix**: surface the default `output/` directory in `rev build --help` and SKILL.md "Project Structure" tree (already mentioned in passing — make it explicit).
-
-### Touch points
-
-- `lib/build.ts` — `BuildConfig` (`output?: Record<string, string>`), `DEFAULT_CONFIG`, `runPandoc()` (resolve filename: `config.output[format]` → CLI `-o` → slug). Helper: `resolveOutputName(config, format, cliOverride)`.
-- `lib/commands/build.ts` — add `-o, --output <path>` flag, wire into `BuildOptions`; same fix applied to the `--show-changes` branch's `baseName` construction.
-- `lib/schema.ts` — declare `output` as object mapping format → string.
-- `skill/SKILL.md` — "Project Structure" tree explicitly notes `output/`; new `output:` example under config.
-- `test/build.test.js` — cover (a) `output:` per-format honored, (b) `-o` CLI override, (c) word-boundary truncation when title >50 chars.
-
-### Resolved
-
-- `-o` relative paths resolve under `outputDir`; absolute paths bypass it. Same rule applies to values in `output:`.
-- Cap raised from 50 → 80 chars; fallback truncates at the last `-` boundary at-or-before the cap so words stay whole (the ADAPT title now slugs cleanly without losing the trailing "s" on "communities").
-- `--show-changes` and `--dual` derived filenames (`-changes.docx`, `_comments.docx`, `_comments.pdf`) follow the chosen base name.
-- Fixed an unrelated misleading example in SKILL.md that showed `output: { docx: { reference-doc: ... } }` — the real config key is `docx.reference` (top-level), not nested under `output:`.
-
----
-
-## Issue 3 — Raw LaTeX figure blocks silently disappear in docx builds  `[x]`
-
-### Problem
-
-Source markdown with `\begin{figure}[H]\includegraphics{...}\end{figure}` blocks renders correctly in the PDF target but produces a docx where all figures are silently missing. Pandoc strips the raw LaTeX because docx has no LaTeX rendering pipeline. No warning is emitted.
-
-This catches you only on careful inspection — a less careful user would ship a docx with no figures and not notice until a reviewer asks.
-
-### Design (agreed)
-
-Three layers, combined:
-
-**1. Warn during build (always on).** In `applyFormatTransforms()` for docx, scan for raw LaTeX figure environments (`\begin{figure}` … `\end{figure}` containing `\includegraphics`). Emit:
-
-```
-Warning: 3 raw LaTeX figure block(s) won't render in docx.
-  intro.md:42  \begin{figure}[H] ... \includegraphics{figures/map.pdf} ...
-  methods.md:118
-  results.md:201
-  Hint: use ![caption](path){#fig:label width=80%} for format-portable figures, or
-        pass --pandoc-arg=--lua-filter=<your.lua> to translate them yourself.
-```
-
-Counted by file/line so the user can jump to fix.
-
-**2. Auto-translate the common shape (opt-out via `docx.translateRawFigures: false`).** Convert
-
-```latex
-\begin{figure}[H]
-\centering
-\includegraphics[width=0.8\textwidth]{figures/map.pdf}
-\caption{Map of study sites.}
-\label{fig:map}
-\end{figure}
-```
-
-→
-
-```markdown
-![Map of study sites.](figures/map.pdf){#fig:map width=80%}
-```
-
-Cover the 80% case. If the block has anything more exotic (`\subfloat`, `\rotatebox`, multi-`\includegraphics`), skip auto-translate, warn loudly, and leave the block as-is.
-
-Width conversion: `0.8\textwidth` → `80%`; bare `8cm` → `8cm`; missing → omit.
-
-**3. Document.** SKILL.md "Cross-References" section currently mentions `@fig:label` and `{#fig:label}` but doesn't show how to *insert* a figure. Add:
-
-```markdown
-![Caption text.](figures/foo.pdf){#fig:foo width=80%}
-```
-
-Note this is the format-portable form. Also mention that raw `\begin{figure}` blocks are PDF-only.
-
-### Touch points
-
-- `lib/build.ts` — new helper `detectRawLatexFigures(content): {file?, line, block}[]` and `translateRawLatexFigures(content): {translated, untranslatedCount}`. Wire into `applyFormatTransforms()` for docx (after `convertDynamicRefsToDisplay`).
-- `lib/build.ts` — propagate warnings up via the existing `warnings: string[]` returned by `build()`. `rev build` already prints from there.
-- `lib/commands/build.ts` — surface warnings in normal output (not just verbose).
-- `lib/schema.ts` — declare `docx.translateRawFigures: boolean` (default true).
-- `skill/SKILL.md` — figure-insertion example under "Cross-References".
-- `test/build.test.js` — cover (a) detection counts blocks correctly, (b) auto-translate of `\includegraphics{path}`, (c) auto-translate of `\includegraphics[width=0.8\textwidth]{path}` → `width=80%`, (d) exotic block → not translated, warned, left alone, (e) opt-out via `translateRawFigures: false`.
-
-### Open questions
-
-- Should auto-translate also handle bare `\includegraphics{...}` outside a `figure` env? Lean no — keep scope to figure environments. If a user writes raw `\includegraphics` without wrapping, that's a deliberate choice we shouldn't second-guess.
-- Width unit handling: `0.8\textwidth` → `80%` is unambiguous. `\linewidth` → `100%`? Yes. Other relative units → leave raw and warn.
-
----
-
-## Working order
-
-1. **Issue 1** first — unblocks immediate workflow needs and provides the manual escape hatch for issue 3 even before auto-translate ships.
-2. **Issue 2** next — small, low-risk, quality-of-life win.
-3. **Issue 3** last — biggest behavior change; benefits from the verbose pandoc echo (Issue 1) for debugging the lua-filter fallback path.

package/site/assets/extra.css

@@ -1,208 +0,0 @@
-/* ── Base ──────────────────────────────────────────────── */
-html, body {
-  height: 100%;
-}
-
-body {
-  background-color: #F5F6F8;
-  color: #3E3F3A;
-  display: flex;
-  flex-direction: column;
-  min-height: 100vh;
-  padding-top: 4rem;
-  font-family: "Roboto", -apple-system, BlinkMacSystemFont, "Segoe UI", system-ui, sans-serif;
-}
-
-.container { flex: 1; }
-footer { margin-top: auto; }
-
-/* ── Navbar (pkgdown-style subtle tint, not bg-primary) ── */
-.navbar {
-  background: color-mix(in oklab, color-mix(in oklab, var(--bs-body-bg) 95%, var(--bs-primary)) 95%, var(--bs-body-color));
-  border-bottom: 1px solid #DFD7CA;
-  line-height: initial;
-}
-
-.navbar .nav-link.active {
-  font-weight: 600;
-  color: var(--bs-primary) !important;
-}
-
-/* ── Links ─────────────────────────────────────────────── */
-a { color: #325D88; }
-a:hover { color: #1E3D5C; }
-
-/* ── Headings ──────────────────────────────────────────── */
-h1 { font-size: 2rem; font-weight: 600; margin-bottom: 1rem; }
-h2 {
-  font-size: 1.4rem; font-weight: 600;
-  margin-top: 2rem; margin-bottom: .65rem;
-  padding-bottom: .3rem;
-  border-bottom: 1px solid #DFD7CA;
-}
-h3 { font-size: 1.1rem; font-weight: 600; margin-top: 1.5rem; }
-h4 { font-size: 1rem;   font-weight: 600; margin-top: 1.2rem; }
-
-/* ── Code ──────────────────────────────────────────────── */
-pre, div.sourceCode {
-  background-color: #EEEEED;
-  border: 1px solid #DFD7CA;
-  border-radius: .375rem;
-  padding: .9rem 1.1rem;
-  font-size: .85rem;
-  overflow-x: auto;
-  margin: 1em 0;
-}
-
-code {
-  background-color: #EEEEED;
-  color: #3E3F3A;
-  border-radius: .25rem;
-  padding: .1em .35em;
-  font-size: .875em;
-}
-
-pre code, div.sourceCode code {
-  background: none;
-  padding: 0;
-  border-radius: 0;
-  font-size: inherit;
-  color: inherit;
-}
-
-div.sourceCode { padding: 0; }
-div.sourceCode pre { border: none; margin: 0; }
-
-/* ── Tables ────────────────────────────────────────────── */
-table {
-  width: 100%;
-  border-collapse: collapse;
-  margin: 1em 0;
-  font-size: .9rem;
-}
-
-thead th {
-  background-color: #DFD7CA;
-  color: #3E3F3A;
-  font-weight: 600;
-  padding: .5rem .75rem;
-  border-bottom: 2px solid #c8c0b4;
-  text-align: left;
-}
-
-td, th { padding: .4rem .75rem; border-bottom: 1px solid #e8e2d8; }
-tbody tr:hover { background-color: rgba(223,215,202,.2); }
-
-/* ── TOC sidebar ───────────────────────────────────────── */
-aside#toc, aside .toc, aside nav.toc { font-size: .875rem; }
-
-aside h2.h6 {
-  text-transform: uppercase;
-  font-size: .68rem;
-  letter-spacing: .07em;
-  color: #6c757d;
-  font-weight: 600;
-  margin-bottom: .5rem;
-  border: none;
-  padding: 0;
-}
-
-aside .toc, aside #TOC {
-  position: sticky;
-  top: 5rem;
-  max-height: calc(100vh - 6rem);
-  overflow-y: auto;
-}
-
-aside ul {
-  list-style: none;
-  padding-left: .9rem;
-  margin: 0;
-}
-aside > nav > .toc > ul,
-aside .toc > ul { padding-left: 0; }
-
-aside li { margin: .1rem 0; }
-
-aside a {
-  color: #6c757d;
-  text-decoration: none;
-  display: block;
-  line-height: 1.55;
-}
-aside a:hover { color: #325D88; }
-
-/* ── Home page cards ───────────────────────────────────── */
-.doc-card {
-  border: 1px solid #DFD7CA;
-  border-radius: .375rem;
-  padding: 1.1rem 1.25rem;
-  height: 100%;
-  background: #fff;
-  transition: border-color .15s, box-shadow .15s;
-}
-.doc-card:hover {
-  border-color: #325D88;
-  box-shadow: 0 2px 8px rgba(50,93,136,.1);
-}
-.doc-card h5 { font-size: 1rem; font-weight: 600; margin-bottom: .4rem; }
-.doc-card p  { font-size: .875rem; color: #6c757d; margin-bottom: .6rem; }
-.doc-card a.stretched-link::after { z-index: 1; }
-
-/* ── Badges row ────────────────────────────────────────── */
-.badge-row { margin-bottom: 1rem; line-height: 2; }
-.badge-row img { margin-right: .25rem; }
-
-/* ── ── ── DARK MODE ── ── ── ──────────────────────────── */
-
-[data-bs-theme="dark"] body  { background-color: #343739; color: #DFD7CA; }
-
-[data-bs-theme="dark"] .navbar {
-  background: color-mix(in oklab, color-mix(in oklab, #343739 92%, var(--bs-primary)) 95%, #DFD7CA);
-  border-bottom-color: #495057;
-}
-
-[data-bs-theme="dark"] a       { color: #7ba8d0; }
-[data-bs-theme="dark"] a:hover { color: #a5c4e8; }
-
-[data-bs-theme="dark"] .navbar .nav-link.active { color: #7ba8d0 !important; }
-
-[data-bs-theme="dark"] h1,
-[data-bs-theme="dark"] h2,
-[data-bs-theme="dark"] h3,
-[data-bs-theme="dark"] h4 { color: #DFD7CA; }
-
-[data-bs-theme="dark"] h2 { border-color: #495057; }
-
-[data-bs-theme="dark"] pre,
-[data-bs-theme="dark"] div.sourceCode {
-  background-color: #2C2F31;
-  border-color: #495057;
-  color: #DFD7CA;
-}
-
-[data-bs-theme="dark"] code {
-  background-color: #2C2F31;
-  color: #DFD7CA;
-}
-
-[data-bs-theme="dark"] div.sourceCode span[class] { color: #DFD7CA !important; }
-
-[data-bs-theme="dark"] thead th {
-  background-color: #3d4043;
-  color: #DFD7CA;
-  border-color: #495057;
-}
-[data-bs-theme="dark"] td,
-[data-bs-theme="dark"] th  { border-color: #3d4043; }
-[data-bs-theme="dark"] tbody tr:hover { background-color: rgba(73,80,87,.3); }
-
-[data-bs-theme="dark"] aside a       { color: #8e9499; }
-[data-bs-theme="dark"] aside a:hover { color: #7ba8d0; }
-
-[data-bs-theme="dark"] .doc-card {
-  background: #2C2F31;
-  border-color: #495057;
-}
-[data-bs-theme="dark"] .doc-card:hover { border-color: #7ba8d0; }
-[data-bs-theme="dark"] .doc-card p     { color: #8e9499; }