Tern

:::meta description: Tern is a document format with the full power of HTML, CSS and JavaScript and none of HTML's verbosity: one file that renders itself in the browser. ::: ::site-nav # Tern {#top} ::toc **Tern gives you the full power of HTML, CSS and JavaScript without the verbosity of HTML.** A note is one HTML file that renders itself: its first line loads `tern.js`, and everything below it is written in a light, Markdown-like syntax that the browser turns into real HTML when the file is opened. ## A first note {#first-note} This line is all the setup a note needs: ```html ``` Everything after it is the note. Save the file next to `tern.js`, open it in a browser, and it renders: ```tern {.live} # Hello This is a note. It has *emphasis*, a [link](https://example.com), a formula, $e^{i\pi} + 1 = 0$, and a key to press, :kbd[Ctrl]+:kbd[S]. - [x] Write the first line - [ ] Publish it ``` Every example on these pages is live: it shows the source, the result, the HTML Tern made, and any diagnostics, all computed by `tern.js` in your browser. ## A tour {#tour} ### Math {#tour-math} TeX between dollars, typeset by KaTeX. A display formula with an id is numbered, and `@id` refers to it. ```tern {.live} The roots of $ax^2 + bx + c = 0$ are $$ x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}. $$ {#eq-roots} By @eq-roots, a real root needs $b^2 \ge 4ac$. Prices like $5 stay prices. ``` ### Blocks {#tour-blocks} Three colons and a name wrap anything in an element. HTML names become that element; other names become a `div` with the name as its class, ready for your CSS. ```tern {.live} :::details[Why is the sky blue?] Short wavelengths scatter more: *Rayleigh scattering*. ::: :::aside This is an `

`, because `aside` is an HTML element. ::: ``` ### Numbered theorems {#tour-theorems} A note's vocabulary turns names into numbered, labelled elements. This example uses the demo vocabulary from [the Vocabulary page](docs/schema.html#demo-schema); a note declares its own in one script. ```tern {.live schema=demo} :::theorem[Pythagoras]{#thm-py} In a right triangle with legs $a$, $b$ and hypotenuse $c$, $a^2 + b^2 = c^2$. ::: :::proof Arrange four copies of the triangle inside a square of side $a + b$. ::: By @thm-py, a triangle with sides 3, 4 and 5 has a right angle. ``` ### Tables {#tour-tables} Pipe tables, with alignment from the colons. ```tern {.live} | Element | Symbol | Mass | |---|:-:|--:| | Hydrogen | H | 1.008 | | Helium | He | 4.003 | | Lithium | Li | 6.94 | ``` ### Figures {#tour-figures} An image with an id becomes a figure, its bracket text the caption (demo vocabulary, for the number). ```tern {.live schema=demo} ![Osprey over the estuary, at dawn.](examples/img/osprey.svg){#fig-osprey width=320} @fig-osprey was drawn from memory. ``` ### References {#tour-references} `@id` links to anything with an id, and its text comes from the target: a heading's text, a title, a number. Nothing to keep in sync by hand. ```tern {.live} ## Results {#results} :::aside[A caveat]{#caveat} The sample was small. ::: See @results, and read @caveat before relying on them. ``` ### Footnotes {#tour-footnotes} ```tern {.live} Terns are long-distance migrants.[^arctic] [^arctic]: The Arctic tern's yearly journey, from the Arctic to the Antarctic and back, is among the longest of any animal. ``` ### Grids {#tour-grids} `+++` splits a block into cells, and the block becomes a grid. On a phone, it is one column. ```tern {.live} :::row{cols=3} **Write** a note in any editor. +++ **Open** it in a browser. +++ **Publish** it on any static host. ::: ``` ## Why Tern {#why} - **One file.** A note is a single `.html` file next to `tern.js`. Open it from disk, keep it in a repository, put it on any static host. There is no project to set up. - **No build.** The browser renders the note when it opens. `tern build` can pre-render a page for search engines, but you never need it to see your work. - **Real HTML out.** Every construct becomes ordinary, accessible HTML: headings, sections, figures, tables, real `` and ``. Labels such as "Theorem 1" are text, so they copy, print and are found by search. When you need more, HTML, CSS and JavaScript are right there in the note. - **Your vocabulary.** Theorems, callouts, cards or web components: a note names what it needs, and a few lines of schema give the names labels, numbers and behaviour. - **Diagnostics.** Nothing is lost silently. Malformed markup stays visible where you wrote it, and Tern reports a positioned diagnostic with a hint that spells the fix: ```tern {.live expect="block.unclosed ref.dangling"} :::aside An aside nobody closed, with a reference to @nowhere. ``` - **A language server.** `tern lsp` brings the same diagnostics to your editor as you type, with completion of names and ids, go to definition, rename, an outline, and links fixed when you move a file. `tern check` prints them for a whole folder of notes. ## Get started {#get-started} 1. **Download [`tern.js`](tern.js)** and put it in the folder where your notes live. It is the whole engine, with no dependencies. 2. **Start a note.** Write the first line yourself, or let the command line write it with the right path: ```sh node tern-cli.js new notes/hello.html --title="Hello" ``` 3. **Open the file** in your browser, from disk. Edit, save, reload. A panel in the corner lists any problems while you work. Then read [the Guide](docs/guide.html#top), which goes from the first line to vocabularies, styling and publishing. ## Documentation {#documentation} | Page | What it covers | |---|---| | [Guide](docs/guide.html#top) | a complete tutorial, from the first line to schemas, publishing and the editor | | [Syntax: blocks](docs/syntax-blocks.html#top) | the eight rules, attributes, and every block construct | | [Syntax: inline](docs/syntax-inline.html#top) | every inline construct, the ambiguity rules, escapes | | [Elements and output](docs/elements.html#top) | how names become elements, titles and labels, numbering, references, ids, figures, raw HTML, metadata | | [Vocabulary and behaviour](docs/schema.html#top) | schemas, `window.TERN.schema`, add-ons, `tern.define`, styling, themes | | [Add-ons](docs/addons.html#top) | the add-ons that come with Tern: math, code highlighting, Mermaid diagrams, search, a list of notes | | [Diagnostics](docs/diagnostics.html#top) | every diagnostic: when it fires, what happens to the content, the fix | | [Command line and editors](docs/tools.html#top) | `tern new`, `check`, `parse`, `build`, `mv`, `corpus` and `lsp`; editor setup; a skill for coding agents | | [Publishing](docs/publishing.html#top) | hosting, `tern build`, CSP, KaTeX and offline use, browsers, trust | | [JavaScript API](docs/api.html#top) | `tern.*`, the AST, the runtime lifecycle, events, config | ## Examples {#examples} Complete notes, each declaring its own vocabulary in a few lines at the top. Open one, then view its source next to the result. | Example | What it shows | |---|---| | [Lecture notes](examples/lecture.html) | numbered definitions and theorems, proofs, numbered equations, references, macros, a footnote, a figure | | [Cheat sheet](examples/cheatsheet.html) | keys, highlight and strikethrough, a three-column grid of tables, callouts, task lists | | [Code notes](examples/code.html) | a numbered listing with line numbers and highlights, code spans, escapes, raw HTML, a note script | | [Field notes](examples/media.html) | images and numbered figures, video, an embedded page, a web component, a plot drawn by a script | | [Project plan](examples/layout.html) | a floating contents box, rows and grids of cards, collapsible sections, a captioned table | ## Status {#status} **1.0.** The syntax these pages describe is Tern 1.0. These pages and the engine's conformance tests are its reference, and every live example on these pages is checked against the engine. Tern is MIT licensed; the source is at [github.com/OzkrAC/tern](https://github.com/OzkrAC/tern).