Command line and editors

:::meta description: The tern command line (new, check, parse, build, mv, corpus), the language server, its tern/outline notification and the language module editors can embed, editor setup for Neovim, VS Code and Helix, a skill for coding agents, and the note-detection rule editors share. ::: ::site-nav # Command line and editors {#top} ::toc Tern has one command-line program, `tern-cli.js`. It writes new notes, checks them, prints their syntax tree, pre-renders them into static pages, moves them with their links, and runs a language server for your editor. It runs under Node and is never loaded by a note: a note needs only `tern.js`. Every command runs the same engine the browser runs, on the same note, with the same vocabulary. So `tern check` reports the same diagnostics as the browser's panel, for everything the browser does not find only at run time (an add-on that fails, a script that calls `document.write`), and your editor shows them again as you type. The examples on this page are real output, run against the engine in this repository. Paths in them are relative to the folder the command ran in. A few long absolute paths are shortened with `…`. ## Installing and running {#install} You need **Node 22 or later** (`package.json` asks for `node >= 22`). The command line has no dependencies of its own: a checkout of the repository is all it needs. | How | Command | Notes | |---|---|---| | Directly | `node path/to/tern/tern-cli.js check notes/` | Works from anywhere. | | npx, inside the checkout | `npx --no -- tern check notes/` | Uses the `bin` entry of the checkout's `package.json`. | | A `tern` command | `npm link` in the checkout | Puts `tern` on your `PATH`, linked to the checkout. | | A symbolic link | `ln -s ~/src/tern/tern-cli.js ~/.local/bin/tern` | `tern-cli.js` is executable and starts with `#!/usr/bin/env node`. | The rest of this page writes `tern` for whichever you chose. :::warning Run `npx` only inside the checkout. Elsewhere, `npx tern` looks for a package called `tern` on the npm registry, which is an unrelated project. The `--no` flag makes `npx` refuse to install anything, so a mistake fails instead of downloading it. Also put `--` before the command: `npx --no tern --version` prints npm's own version. ::: `tern help` (or `tern` alone, `tern --help`, `tern -h`) prints the usage to stdout and exits 0. `tern --version` (or `-v`, `version`) prints the engine's version: ```sh $ tern --version 0.6.0 $ tern bogus tern: unknown command "bogus" usage: tern COMMAND … … $ echo $? 2 ``` | Command | What it does | Section | |---|---|---| | `tern new FILE` | writes a new note's first line | [tern new](#new) | | `tern check PATH…` | prints the diagnostics of notes; exits 1 on errors | [tern check](#check) | | `tern parse FILE` | prints the note's syntax tree as JSON | [tern parse](#parse) | | `tern build FILE` | writes a static, pre-rendered page | [tern build](#build) | | `tern mv FROM… TO` | moves notes and files, rewriting the links to and from them | [tern mv](#mv) | | `tern search QUERY` | searches notes by word, each hit at its file and line | [tern search](#search) | | `tern index [PATH…]` | writes `notes.json` and `search.json`, what the `::notes` and `::search` add-ons read | [tern index](#index) | | `tern corpus PATH…` | prints documentation pages' live examples as corpus cases | [tern corpus](#corpus) | | `tern lsp [--stdio]` | the language server, over stdio | [The language server](#lsp) | ## What every command shares {#common} ### Exit codes {#exit-codes} | Code | Meaning | |---|---| | `0` | Done. | | `1` | `tern check` found a diagnostic at or above `--fail-on`, `tern new` refused to write the file, `tern mv` refused to move or a move failed, `tern search` found nothing, `tern index --check` found a file missing or stale, or `tern corpus` left out an example. | | `2` | A usage error (a missing argument, an unknown option, a bad value), or a path that cannot be used: a missing or unreadable file, or, for `tern parse` and `tern build`, a file that is not a note. | Every command takes `--help` (or `-h`), which prints its synopsis and exits 0. Options are strict: an unknown option is a usage error, printed with the synopsis. When the reader of the output closes before the command is done (`tern parse FILE | head`), the command ends quietly with exit 0. ```sh $ tern new x.html --bogus tern new: Unknown option '--bogus'. To specify a positional argument starting with a '-', place it at the end of the command after '--', as in '-- "--bogus" usage: tern new FILE [--tern=PATH] [--use=LIST] [--title=TEXT] [--guarded] [--force] ``` ### How diagnostics print {#output} `tern check` and `tern build` print each diagnostic on one line, with its hint indented on the next: ```sh notes/kernel.html:6:1: error block.unclosed: `:::aside` opened on line 5 is still open at line 9 add `:::` or `:::/aside` ``` The parts are `FILE:LINE:COLUMN: SEVERITY CODE: MESSAGE`. This is the shape most editors and CI systems recognise as a clickable location. - **Lines are file lines.** The note starts on the line after the `tern.js` tag, so with the canonical first line, note line 5 is file line 6. Your editor shows file lines, so these are the numbers to jump to. - **Messages cite note lines.** The message comes from the engine, which counts lines from the first line of the note. Above, `opened on line 5` is the same line as `:6:1`. - **Columns** count UTF-16 code units from 1, as the engine does. They are the same in the file and in the note. Every code, with what it means and how to fix it, is on the [Diagnostics](diagnostics.html#top) page. ### Which files are notes {#notes} A file is a note when one of its lines loads `tern.js` with a plain script tag. The rule is exact and shared by every command, the language server and editors; it is [Note detection](#detection) below. The note is everything after that line, and everything before the tag is the preserved head. When a command is given a file that is not a note, it says why: | The file | What the commands say | |---|---| | has no line loading `tern.js` | `no line loads tern.js` | | loads it with `defer`, `async` or `type=module` | `it loads tern.js with defer, so tern.js does not render it; use a plain ``` | Option | What it does | |---|---| | `--tern=PATH` | The `src` of the script tag, as given: a relative path, a root-relative path, or a URL. Without it, see below. | | `--use=LIST` | The add-ons, written as a [`:::use` block](syntax-blocks.html#use), one per line, after the `:::meta` block, and each preloaded from the first line (``, `as="script"` or `as="style"`), so the browser fetches it alongside `tern.js` instead of after the note has arrived. Separate them with commas or spaces; the option may repeat. | | `--title=TEXT` | Adds a `:::meta` block with `title: TEXT`, then a blank line. One non-empty line. | | `--guarded` | Adds the guard, which shows the note's source when `tern.js` does not run. See [The guard](#guarded). | | `--force` | Overwrites an existing file. | ### The path to tern.js {#new-path} Without `--tern`, `tern new` looks for a file called `tern.js` in the new note's folder, then in each folder above it, and writes the nearest one as a relative path with forward slashes. Two folders down, that is `../../tern.js`. When there is none, it writes `tern.js` (the note's own folder) and says so on stderr: ```sh $ tern new note.html created note.html, loading tern.js tern new: no tern.js in . or above; the note loads tern.js from its own directory ``` Relative paths are what you want for publishing: they keep working when the folder is copied, opened from disk, or served under a sub-path such as a GitHub project page (see [Publishing](publishing.html#github-pages)). ### Add-ons and a title {#new-options} ```sh $ tern new notes/first.html --title="Linear maps" --use=theorems.js,theme.css created notes/first.html, loading ../tern.js tern new: :::use names theorems.js, which does not exist yet tern new: :::use names theme.css, which does not exist yet $ cat notes/first.html :::meta title: Linear maps ::: :::use theorems.js theme.css ::: ``` - `--use=a.js,b.css`, `--use "a.js b.css"` and `--use=a.js --use=b.css` all give the same `:::use` block, `a.js` then `b.css`, one per line, and the same two preloads on the first line. `tern.js` preloads `data-use` entries itself as it starts; a `:::use` entry it finds only once the note has arrived, so the head's preload saves a round trip there. - A local add-on that does not exist yet (relative to the note's folder) gets a note on stderr. The file is still written: you may be about to create it. Remote URLs and root-relative paths are not checked. - `--title` is written as `:::meta` (see [Metadata](elements.html#metadata)). Before writing, `tern new` reads the file back and checks that the title survives as written, and that the add-ons read back from `:::use`; a title that would not is refused. ### The guard (--guarded) {#guarded} A note whose `tern.js` does not load shows its source run together as one paragraph of text, with any raw HTML in it rendered. The guard makes that case readable: it shows a one-line message, then the note exactly as written. ```sh $ tern new notes/guarded.html --guarded created notes/guarded.html, loading ../tern.js, guarded $ cat notes/guarded.html ``` The guard is the rest of the first line, after the tag. It is still one line, so the file is still a note. What happens in each case (all three are tested in Chromium and Firefox): | Case | What the reader sees | How | |---|---|---| | `tern.js` loads | the rendered note | `tern.js` takes everything after its tag as text, the guard included, and the note starts on the next line. The guard is never parsed as HTML. | | `tern.js` does not load | "tern.js did not load; the source follows.", then the note as plain text | The `<noscript>` is inert while scripts run. The guard's script finds no `tern`, writes the message and a hidden `<xmp>`, which the `</xmp>` right after closes. `<plaintext>` shows the rest as text. | | JavaScript is off | "JavaScript is off; the source follows.", then the note as plain text | The `<noscript>`'s paragraph starts the body, and its hidden `<xmp>` hides the guard script up to the same `</xmp>`. Then `<plaintext>`. | - The guard adds nothing to the rendered page: when `tern.js` loads, its script never runs. - **CSP.** The guard's script is an inline script. When `tern.js` loads, the guard is never parsed, so it causes no violation. When `tern.js` does not load under a Content-Security-Policy that blocks inline scripts, the guard's script is blocked: the reader sees the note as plain text, without the message line. - `tern build` drops the guard from the page it writes (see [tern build](#build)). ### Refusals {#new-refusals} `tern new` writes one file, creates no folders, and overwrites only with `--force`. When it declines, it says why on stderr and exits 1: | Situation | Message | |---|---| | the file exists | `tern new: notes/kernel.html exists; --force overwrites it` | | the path is a directory | `tern new: notes is a directory` | | the folder does not exist (it creates none) | `tern new: there is no directory drafts` | | `--tern` names a file not called `tern.js` | `tern new: <script src="lib/tern.min.js"> would not make notes/min.html a note: the src must name a file called tern.js` | | the title does not read back from `:::meta` | `tern new: the title does not read back from :::meta` | Before writing, `tern new` checks that the line it would write is detected as a note line, with the same rule every tool uses. That is why `--tern=lib/tern.min.js` is refused: a file called `tern.min.js` is not detected, so the result would not be a note. These are usage errors instead, which exit 2 and print the synopsis: no `FILE`, more than one, a path with no file name (`notes/`, `.`, `..`), an empty `--title` or one with a line break, an empty `--tern`, an unknown option. ## tern check {#check} `tern check` prints every diagnostic of one or more notes, and exits 1 when any is serious enough. It is the gate for CI and for publishing. :::syntax[tern check] ```sh tern check PATH… [--json] [--fail-on=error|warning|info] [--quiet] [--no-scripts] ``` ::: ```sh $ tern check notes/kernel.html notes/kernel.html:4:5: warning ref.dangling: no id in this note has this name, so the reference stays text if it is not a reference, write \@rank notes/kernel.html:6:1: error block.unclosed: `:::aside` opened on line 5 is still open at line 9 add `:::` or `:::/aside` notes/kernel.html:9:1: error math.unclosed: `$$` opened on line 8 is never closed add a line holding only `$$` tern check: 1 note: 2 errors, 1 warning, 0 infos $ echo $? 1 ``` The diagnostics go to stdout, in the order they occur in each file. The summary line goes to stderr. The note it checked is this one, after the canonical first line; here it is live, so you can see the same three diagnostics at note lines 3, 5 and 8: ```tern {.live expect="ref.dangling block.unclosed math.unclosed"} # The kernel See @rank for the dimension count. :::aside Every linear map has a kernel. $$ \ker f = \{ v : f(v) = 0 \} ``` | Option | What it does | |---|---| | `PATH…` | Files and folders, at least one. Each file is checked once, even if named twice. | | `--fail-on=LEVEL` | The lowest severity that makes the exit code 1: `error` (the default), `warning` or `info`. Anything else is a usage error. | | `--quiet` | Prints only the diagnostics at or above `--fail-on`, and no summary and no notes about skipped files. | | `--json` | Prints one JSON array of the diagnostics instead of lines. See [--json](#check-json). | | `--no-scripts` | Analyses without running the notes' head scripts and add-ons ([Running a note's code](#sandbox)): their vocabulary is unknown, but nothing in the notes runs. | ### Folders {#check-folders} A folder is searched for notes: - every `.html` and `.htm` file in it and below, in sorted order; - folders whose names start with a dot, and `node_modules`, are skipped; - symbolic links to files are followed, symbolic links to folders are not; - a file found this way that is not a note is skipped silently. A file you **name** that is not a note is skipped with a note on stderr, and does not change the exit code: ```sh $ tern check notes/plain.html notes/deferred.html tern check: notes/plain.html is not a note (no line loads tern.js); skipped tern check: notes/deferred.html is not a note (it loads tern.js with defer, so tern.js does not render it; use a plain <script src>); skipped tern check: no notes found $ echo $? 0 ``` A path that does not exist is a usage error (exit 2). A file that exists but cannot be read is reported on stderr; the other files are still checked, and the exit code is 2. ### --fail-on and --quiet {#check-fail-on} `--fail-on` decides the exit code; `--quiet` decides what is printed. Without `--quiet`, every diagnostic is printed whatever `--fail-on` says. | The notes have | default | `--fail-on=warning` | `--fail-on=info` | |---|---|---|---| | an error | exit 1 | exit 1 | exit 1 | | a warning, no error | exit 0 | exit 1 | exit 1 | | only infos | exit 0 | exit 0 | exit 1 | | nothing | exit 0 | exit 0 | exit 0 | ```sh $ tern check notes --quiet notes/kernel.html:6:1: error block.unclosed: `:::aside` opened on line 5 is still open at line 9 add `:::` or `:::/aside` notes/kernel.html:9:1: error math.unclosed: `$$` opened on line 8 is never closed add a line holding only `$$` $ tern check notes --quiet --fail-on=warning notes/kernel.html:4:5: warning ref.dangling: no id in this note has this name, so the reference stays text if it is not a reference, write \@rank notes/kernel.html:6:1: error block.unclosed: `:::aside` opened on line 5 is still open at line 9 … ``` In CI, `tern check site/ --quiet` prints only what fails the build. Add `--fail-on=warning` to hold notes to a stricter standard, broken links between notes included. **Encoding.** Notes are read as UTF-8. A file that is not valid UTF-8 is checked with each byte sequence that is not read as U+FFFD, and said on stderr; a UTF-16 file, which starts with a byte order mark, is not read as a note, and said too. Every command that reads notes says the same, as `tern COMMAND: …`: ```sh $ tern check notes/latin.html notes/wide.html tern check: notes/latin.html is not valid UTF-8; 1 byte sequence that is not was read as U+FFFD tern check: notes/wide.html is UTF-16 (it starts with a byte order mark); Tern reads UTF-8, so it is not read as a note tern check: notes/wide.html is not a note (no line loads tern.js); skipped tern check: 1 note: 0 errors, 0 warnings, 0 infos ``` ### --json {#check-json} `--json` prints one array with every diagnostic of every note, in the same order as the lines would be. `--quiet` filters it the same way; with nothing to report, the array is empty (`[]`). The summary line still goes to stderr unless `--quiet`. ```sh $ tern check notes/warn.html --json [ { "file": "notes/warn.html", "code": "ref.dangling", "severity": "warning", "message": "no id in this note has this name, so the reference stays text", "position": { "start": { "line": 1, "column": 5, "offset": 4 }, "end": { "line": 1, "column": 13, "offset": 12 } }, "hint": "if it is not a reference, write \\@nowhere", "filePosition": { "start": { "line": 2, "column": 5 }, "end": { "line": 2, "column": 13 } } } ] tern check: 1 note: 0 errors, 1 warning, 0 infos ``` (The real output puts each `line`, `column` and `offset` on a line of its own.) | Field | What it holds | |---|---| | `file` | The path as named, or as found in a folder. | | `code` | The diagnostic's code, such as `ref.dangling`. | | `severity` | `error`, `warning` or `info`. | | `message` | What happened. It cites note lines. | | `position` | Where, in the note: `start` and `end`, each with `line` and `column` (1-based) and `offset` (0-based UTF-16 index into the note). The end is exclusive. Missing for `addon.failed`, `addon.remote` and `head.script`, which are about the file, not the note. | | `hint` | How to fix it, when there is a hint. | | `filePosition` | Where, in the file: `start` and `end`, each with `line` and `column`. Always present. | The engine's own diagnostics have the shape described on [Diagnostics](diagnostics.html#positions) and in the [JavaScript API](api.html#diagnostics); `file` and `filePosition` are what the command line adds. ### Add-ons and head scripts {#check-vocabulary} `tern check` loads the note's vocabulary as described in [Vocabulary under Node](#vocabulary). Problems loading it come first in a file's diagnostics. This note has a head script on a remote origin, an inline head script that throws, a missing add-on and a remote one: ```html <!doctype html><meta charset="utf-8"> <script src="vocab.js"></script> <script src="https://cdn.example/analytics.js"></script> <script>window.TERN.schema.leaf = { toc: { tag: 'nav', transform: 'toc' } }; undefinedFunction();</script> <script src="../tern.js" data-use="theorems.js missing.js https://cdn.example/remote.js theme.css"></script> ``` ```sh $ tern check notes/addons.html theorems.js loaded notes/addons.html:3:1: info head.script: the head script https://cdn.example/analytics.js is not run under node, so vocabulary it declares in window.TERN.schema is unknown here notes/addons.html:4:1: warning head.script: the head script inline script on line 4 threw under node: undefinedFunction is not defined; vocabulary it declares may be missing notes/addons.html:5:1: error addon.failed: the add-on missing.js did not load: cannot read …/site/notes/missing.js notes/addons.html:5:1: info addon.remote: the add-on https://cdn.example/remote.js is not loaded under node; names it declares are unknown to tern check tern check: 1 note: 1 error, 1 warning, 2 infos ``` - `theorems.js loaded` is the add-on's own `console.log`, on stderr. - `vocab.js` and `theorems.js` loaded, so the names they declare are known, and the note's theorems are numbered as in the browser. - `theme.css` is a stylesheet, so it is not loaded under Node. Only its path is checked, as a [link](#check-links). - The inline script set `window.TERN.schema.leaf` before it threw, and that part stays in effect. - An entry of a [`:::use` block](syntax-blocks.html#use) is loaded and checked the same way, and a problem with one is reported at the entry's line in the note. ### Links between files {#check-links} `tern check` also follows each note's links to other files and checks them against the disk. A broken one is a warning, so it fails the check only with `--fail-on=warning`; a wrong path to the `tern.js` the note loads is an error, since the note does not render: - [`link.missing`](diagnostics.html#link-missing): the file does not exist, the link names a folder with no `index.html`, or the name's case differs from the file's; - [`link.dangling`](diagnostics.html#link-dangling): the file exists, but the fragment after `#` names no id in it. ```sh $ tern check notes notes/index.html:4:5: warning link.missing: kernal.html does not exist fix the path: it resolves from the folder of this note notes/rank.html:4:4: warning link.dangling: maps.html has no element with the id thm-rank check the id after #: ids are case-sensitive tern check: 3 notes: 0 errors, 2 warnings, 0 infos ``` **What it checks:** - Tern links and images: `[text](maps.html#thm-rn)`, `![alt](img/kernel.svg)`; - the `href`, `src`, `poster` and `data` of elements, as in `::video{src=media/tide.mp4}`; - `href` and `src` in raw HTML, in the note and in the head, such as a `<link rel="stylesheet">`; - on the `tern.js` line: the path to `tern.js` itself, since a wrong one means the note does not render; `data-css`; and the stylesheets in `data-use` or `:::use`. Script add-ons and head scripts are not, being [`addon.failed`](diagnostics.html#addon-failed)'s and [`head.script`](diagnostics.html#head-script)'s. **How a link resolves:** - from the note's folder, as a browser does. A query (`?v=2`) is ignored, and escapes such as `%20` are decoded; - a folder (`vectors/`, or `vectors` when it is one) means its `index.html`; - a fragment names an id: - in a note, any id its HTML would have; - in another HTML file, an `id` or an `<a name>`; - in a Markdown file, a heading's GitHub anchor. `#top` always counts. A fragment in other files, such as `paper.pdf#page=3`, is not checked. A Tern link to `#id` in the same note is the engine's [`ref.dangling`](diagnostics.html#ref-dangling), reported with the note's other diagnostics. **What it leaves alone:** - URLs with a scheme, such as `https:` and `mailto:`, and URLs starting with `//`: they are elsewhere; - URLs starting with `/`, which depend on where the site is served; - all the links of a note with a `<base href>`, since its URLs do not resolve from its folder; - anything in code, math and comments; - ids that a script adds when the page runs. Each file is read once per run, however many links name it. A note a link names is analysed with its own add-ons, so its ids are the ones it has in the browser. The language server checks the same links as you type ([links in the editor](#lsp-links)). ## tern parse {#parse} `tern parse` prints the note's syntax tree as JSON: the AST that `tern.parse` returns, with the note's vocabulary and head. :::syntax[tern parse] ```sh tern parse FILE [--transformed] [--compact] [--no-scripts] ``` ::: | Option | What it does | |---|---| | `--transformed` | Runs the transforms first, so the tree has ids, numbers, labels, resolved references and `root.data.tern` (see [The transformed AST](api.html#transformed-ast)). | | `--compact` | One line of JSON instead of two-space indentation. | | `--no-scripts` | Parses without running the note's head scripts and add-ons ([Running a note's code](#sandbox)). | ```sh $ cat notes/small.html <!doctype html><meta charset="utf-8"><script src="../tern.js"></script> # Hello {#top} See @top. $ tern parse notes/small.html --transformed --compact | jq '.data.tern.ids' { "top": { "kind": "heading", "explicit": true, "line": 1, "column": 10 } } ``` - **Positions are note positions**: line 1 is the line after the `tern.js` tag. Add the number of lines up to and including the tag to get file lines. - **No diagnostics.** `tern parse` prints the tree and nothing else; use `tern check` for diagnostics. With `--transformed`, the transforms' own diagnostics are in `root.data.tern.diagnostics`. - **Vocabulary problems** (a missing or remote add-on, a head script or transform that threw) are printed on stderr as `tern parse: …` and do not change the exit code. - **Exit codes.** 0 when the tree is printed; 2 when the file is missing or is not a note. The node types and their fields are on [The AST](api.html#ast). ## tern build {#build} `tern build` turns a note into a static page: the same HTML the browser would mount, already in the file. The page still loads `tern.js`, which adds what HTML alone cannot: behaviours, math, the diagnostics panel, copy and print handling. When to use it, and when not to, is on [Publishing](publishing.html#build). :::syntax[tern build] ```sh tern build FILE [-o OUT] [--math katex|mathml] [--json] [--no-scripts] ``` ::: | Option | What it does | |---|---| | `-o OUT`, `--output=OUT` | Where to write the page. Without it, or with `-o -`, the page goes to stdout. When `OUT` ends with `/`, or is an existing folder, the page is written into that folder under the note's file name, and the folder is created if needed. Any other `OUT` is the page's file name, and missing folders on its path are created. `OUT` may not be the note itself. | | `--math katex|mathml` | Pre-renders the math: `katex` to typeset HTML with the `katex` package, `mathml` to native MathML with the `temml` package. `--katex` is short for `--math katex`. See [pre-rendered math](#build-katex). | | `--json` | Prints one JSON object on stdout instead of the page: see [--json](#build-json). | | `--no-scripts` | Builds without running the note's head scripts and add-ons ([Running a note's code](#sandbox)): the page still loads `tern.js`, but the note's own vocabulary is not applied to the pre-rendered HTML. | ```sh $ tern build notes/maps.html -o dist/ theorems.js loaded notes/maps.html:14:13: warning ref.dangling: no id in this note has this name, so the reference stays text if it is not a reference, write \@nowhere tern build: relative URLs (tern.js, add-ons, images, links) are kept as written, so they resolve from dist tern build: wrote dist/maps.html; 2 formulas ``` - **Diagnostics** go to stderr, in the same format as `tern check`. The page is written whatever they are, and the exit code is 0, just as a browser renders a note whatever its diagnostics. Run `tern check` first if problems should stop you. - **Relative URLs** in the note, the head and the tag are kept exactly as written. When `OUT` is in a different folder from the note, `tern build` warns you, because they now resolve from the new folder. Above, `../tern.js` now points one level above `dist/`. - **Folders.** `-o dist/` writes `dist/maps.html`, creating `dist/`. `-o out/deep/page.html` creates `out/deep/`. Without the final `/`, a name that is not an existing folder is a file name, and the build says so: ```sh $ tern build notes/maps.html -o dist2 … tern build: wrote dist2; 2 formulas tern build: dist2 is written as a file; end -o with / to write maps.html into a directory of that name ``` - **Warnings** about the note's files go to stderr too, prefixed `tern build:`: a missing doctype or charset that the page adds, a head script or add-on that did not load (the page then writes its names without its schema), and a remote add-on, which is not loaded under Node: ```sh tern build: the add-on https://cdn.example/remote.js is not loaded under node, so the page uses its names without its schema ``` - **Not a note**, `-o` naming the note itself, a missing file: exit 2. - The last line says how many formulas the page has, and with `--math` how many were pre-rendered, and as what. ### --json {#build-json} `--json` prints one object on stdout: `file`, `out` (the page's path, or `null` without `-o`), `math` (`total`, `prerendered`, `engine`: `"katex"`, `"mathml"` or `null`), `warnings` (the `tern build:` notes, as strings), `diagnostics` (the note's, as [`tern check --json`](#check-json) gives them, `math.error` among them), and, without `-o`, `html`, the page itself. With `-o` the page is written as usual. The lines still go to stderr, so a tool reads one JSON document and a person still sees what happened: ```sh $ tern build notes/maps.html --json | jq '{out, math, warnings, diagnostics: (.diagnostics | length)}' { "out": null, "math": { "total": 2, "prerendered": 0, "engine": null }, "warnings": [], "diagnostics": 1 } ``` ### The built page {#built-page} The page `tern build` writes has these parts, in order. This is `dist/maps.html` from the example above, with tern.css cut short: ```html <!doctype html><html lang="en"><meta charset="utf-8"> <style id="tern-style"> :root { color-scheme: light dark; … </style> <title>Linear maps</title> <meta name="author" content="O. Carrera"> <meta name="viewport" content="width=device-width, initial-scale=1"> <meta name="color-scheme" content="light dark"> <script data-built src="../tern.js" data-use="theorems.js"></script><script src="theorems.js"></script> <main class="tern"><h1 id="linear-maps">Linear maps</h1> <section id="rn" class="t-block theorem" data-t="theorem" data-pos="9:1"><div class="t-title"><span class="t-label">Theorem 1</span> Rank–nullity</div><p>For <span class="t-math" data-pos="10:5">f : V \to W</span>, …</p> </section> <p>See <a class="t-ref" href="#rn">Theorem 1</a> and @nowhere.</p> </main> <script type="text/tern" id="tern-source" data-line="1">:::meta title: Linear maps … </script> <script type="application/json" id="tern-diagnostics">[{"code":"ref.dangling","severity":"warning",…}]</script> ``` 1. **The preserved head**, as written. When it lacks `<!doctype html>` or a `<meta charset>`, the page gets them, with a warning for each: ```sh tern build: the note has no <!doctype html>; the page adds it tern build: the note has no <meta charset>; the page adds <meta charset="utf-8"> ``` 2. **`:::meta`, written statically**, as the browser would write it at mount: `<title>`; `lang` and `dir` on `<html>` (into its tag, or a new `<html>` tag after the doctype); a `<meta name>` for every other key. A key the head already sets is left alone. Then a viewport meta and a `color-scheme` meta, unless the head has them. 3. **Tern's stylesheets**, in the order the runtime uses, placed before the head's first stylesheet of your own, so yours win: - KaTeX's CSS, when math was pre-rendered; - the base: tern.css inlined as `<style id="tern-style">`. If the head links `tern.css` (or the `data-css` URL), that link is the base and stays where it is; `data-css` without such a link becomes a `<link>`; - each CSS add-on of `data-use` and of the `:::use` block, as a `<link>`, not inlined, so its relative `url()`s keep working; - with `data-nonce`, each of them carries the nonce, and so do the script add-on tags. The `tern.js` tag is kept as written: give it a `nonce` yourself if your policy needs one. 4. **The `tern.js` tag**, as written plus `data-built` (always just `data-built`, with no value). When the note has a [`:::use` block](syntax-blocks.html#use), its entries are merged into the tag's `data-use`, after the tag's own: the block emits nothing, and `tern.js` on a built page reads the tag alone. Anything after the tag on its line, such as a [guard](#guarded), is dropped. Then each script add-on, as a static `<script src>` tag, in order. Both run before the body is parsed, so the note's own scripts find `tern` and the add-ons' globals, as after a mount. A formula the build did not pre-render typesets at view time only if `data-use` lists a [math add-on](addons.html#katex). 5. **`<main class="tern">`** holding the emitted HTML, exactly what `tern.toHTML` returns for the note, with its vocabulary and head. So the page has its layout before any script runs. 6. **The note's source**, in `<script type="text/tern" id="tern-source" data-line="N">`, where `N` is the number of file lines before the note. See [The source kept](#build-source). 7. **The diagnostics**, when there are any, in `<script type="application/json" id="tern-diagnostics">`: the parse and transform diagnostics, at note positions, as JSON with each `<` written `\u003c`. A built page is not a note: its tag has `data-built`, which [detection](#detection) refuses. `tern check dist/maps.html` skips it and tells you to check its source note. ### The source kept {#build-source} The page keeps the note so that `tern.js` can position problems it finds on the page (a failed add-on), and so that the source can be read back. Script contents cannot hold `</script` or `<script src="tern.js"></script>` | a comment closed before the tag | | `<script src="tern.js" data-use="async.js defer.css" data-async="1"></script>` | `async` and `defer` inside other attributes do not count | **Lines that do not:** | Line | Why | |---|---| | `<script src="mytern.js"></script>`, `<script src="tern.min.js"></script>`, `<script src="tern.json"></script>` | the file name is not exactly `tern.js` | | `` | inside a comment | | `<script defer src="tern.js"></script>`, `<script src="tern.js" async></script>` | `defer` or `async` | | `<script type="module" src="tern.js"></script>` | a module | | `<script data-built src="tern.js"></script>` | a built page | | `<script data-src="tern.js"></script>` | `data-src` is not `src` | | `<link rel="preload" href="tern.js" as="script">`, `<img src="tern.js">` | not a script tag | **Limits.** A tag split over two lines, or a comment that spans lines, is not seen, so a tag inside a multi-line comment still counts. Each attempt stops at the next `<` or `>`, so testing a line takes time linear in its length, even on hostile input. ### The pattern and its fixtures {#detection-fixtures} `test/fixtures/detect.json` holds the pattern, its flags and 42 cases (20 lines that match, each with the tag it must capture, and 22 that do not). Load it in your editor's tests rather than copying the pattern by hand. `test/cli.js` checks that its pattern is `DETECT` itself and that every case holds. ```json { "description": "Lines that make an HTML file a Tern note, and lines that do not …", "pattern": "^(?:[^<]|<(?!!--)|)*?(<script(?=[\\s>/])…", "flags": "i", "tagGroup": 1, "match": [ { "why": "the canonical first line", "line": "<!doctype html><meta charset=\"utf-8\"><script src=\"tern.js\"></script>", "tag": "<script src=\"tern.js\">" }, … ], "noMatch": [ { "why": "a file named mytern.js", "line": "<script src=\"mytern.js\"></script>" }, … ] } ``` - **`pattern`** and **`flags`** build the regular expression. It uses lookahead, lazy repetition and a back-reference. JavaScript and Python's `re` run it unchanged and pass every case, capture included; PCRE (`grep -P`) matches the same lines. - **`tagGroup`** is the capture group holding the tag. Everything on the line before the tag is the end of the preserved head. - **`match`** cases give the line and the tag the group must capture; **`noMatch`** cases must not match at all. Each says why in `why`. In JavaScript: ```js const fixture = require('./test/fixtures/detect.json'); const DETECT = new RegExp(fixture.pattern, fixture.flags); // The note's first line (0-based), or -1 when the file is not a note. function noteStart(lines) { const i = lines.findIndex((line) => DETECT.test(line)); return i < 0 ? -1 : i + 1; } ``` From Node, `cli/note.js` exports `DETECT` itself, `detect(line)`, which returns `{index, tag}` (the tag and where it starts on the line) or `null`, and `split(text)`, which returns `{head, tag, note, line}` for a whole file, `line` being the number of file lines before the note.