bc027579f81bd61a816afc1e63ef6232d840e042
braney
  Wed Jul 29 12:16:12 2026 -0700
Docent: publish the language reference as a generated page refs #37892

mkref.sh renders README.md to a standalone HTML page (default
~/public_html/docent.html), so the published reference is regenerated
from the README rather than hand-maintained -- the previous hand-written
page went stale as soon as the language was renamed.

Also document the top-of-file `position:` key, which docent.js reads but
the README did not list.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

diff --git src/hg/utils/docent/README.md src/hg/utils/docent/README.md
index e9d93e6a676..209798a43a1 100644
--- src/hg/utils/docent/README.md
+++ src/hg/utils/docent/README.md
@@ -34,30 +34,31 @@
 
 Outputs, relative to the script's own directory:
 
 - mp4 → `../<base>.mp4` (override with `mp4:` or a second argument)
 - stills → `stills/<base>/<name>.png` (override with `stills:`)
 
 `docent.mk` in this directory has the make rules — include it from a project that keeps
 a set of scripts and it rebuilds only the ones whose source changed. See the usage
 comment at the top of that file.
 
 ## Top of file (all optional)
 
 ```yaml
 target: genome-test     # or rr, hgwdev, hgwbeta, hgwdev-<user>, or a full https://.../cgi-bin
 db: hg38                # source assembly
+position: chr7:155.8M   # starting position (tracked from then on; `go:` sets it too)
 reset: true             # cartReset first (clean cart + fresh quickLift hub)
 size: [1000, 760]       # viewport
 pix: 850                # browser image width
 pace: 1.2               # seconds to dwell after each step
 shotHold: 2.2           # extra seconds the video pauses at a shot
 trackAnim: false        # skip the visible dropdown gesture on `track:` (nav only)
 fast: false             # true = figures only: no dwells, no cursor animation, no mp4
 pinMouseovers: false    # record every mouseover for `pinShot:` (see below)
 mp4: ../myname.mp4      # override output paths if you want
 stills: stills/AP1
 ```
 
 `target:` defaults to genome-test, so a script that forgets to say where it runs will
 not quietly hit someone's personal sandbox.