Writing
The console, the editor, history and knowledge points.
Authors, editors and admins write in the Console (the last item of the top bar). Its dashboard lists your drafts, review requests and recent activity.
Books and pages
- Create a book from Books, in a library. You become its maintainer.
- Build the outline: add chapters and pages, and drag them into place. With a row focused, Alt+↑ and Alt+↓ move it, Alt+→ nests it under the row above and Alt+← moves it out. Shift- or Mod-click selects several rows to move together.
- Write each page in the editor. Drafts save automatically and are visible only in the console.
- Publish when the page is ready. Readers see the published version until you publish again.
Pages can be Markdown, MDX, Jupyter notebooks (.ipynb) or a LaTeX subset (.tex); all of them
compile to the same reading page. See the Markdown reference for the syntax.
Book settings
| Section | Settings |
|---|---|
| General | Title, subtitle, description, edition, level, audience, prerequisites, keywords, tags, icon, ISBN, DOI, a citation text of your own and the citation format readers see first |
| People | Authors and their roles on the book |
| Cover | Cover picture or a generated cover |
| Appearance | Accent color, the article style (for readers who have not chosen one), and the reading font and width the book prefers |
| Structure and numbering | Chapter styles and numbering |
| Math and code | Math packages, a preamble of macros, code options |
| Reader features | Highlights and notes, knowledge panel, reading progress, citations, printing, resources, automatic glossary links, read aloud |
| Sharing and search | The title and description used for links and search engines, and whether to be indexed |
| Access and publishing | Visibility, publishing, featuring on the home page, deleting the book |
| Schedule | A course calendar: sessions and deadlines that readers can subscribe to |
The editor
The editor has four modes:
| Mode | Keys | What it is |
|---|---|---|
| Source | Mod+Alt+1 | Markdown with highlighting, previews and completion |
| Visual | Mod+Alt+2 | Edit the page as it will look, with the article's own styles |
| Split | Mod+Alt+3 | Source next to a live preview; the two scroll together |
| Preview | Mod+Alt+4 | The compiled page with its warnings |
Mod+/ switches between Source and Visual, and Mod+S saves a checkpoint. The visual editor is available for Markdown pages.
Toolbar and components
The toolbar formats text, inserts links, math, code, diagrams and tables, and Insert component adds any component from the catalog with its required attributes. In the visual editor, type / at the start of an empty line for the same list; component titles, labels and attributes are edited in place, with the gear button for the rest.
Pictures
Insert a picture from the toolbar to choose a file from the book's assets or your files, or upload one, with its description (alt text). Pasting or dropping a picture uploads it. In source mode, pictures show as thumbnails under their line (or on hover). Click one for its tools: preview, replace, edit the description, size, position and copy the address. Mermaid diagrams show a rendered preview after their fence. Both are set in the editor's preferences.
Size and placement are written after the picture, ``. In the
visual editor, select a picture for its toolbar: align it left, center or right, let the text wrap
around it on either side, pick a size, edit its description, replace it, or add a caption
(which makes it a numbered figure). Drag its side handles to resize; sizes snap to 25, 33, 50,
66, 75 and 100% (hold Shift for any size). See the Markdown reference for
the syntax.
Math
Write $…$ for inline math and $$ … $$ (or a ```math fence) for display math. Typing \
inside math lists TeX commands, each with a small drawing of what it makes; the panel beside the
list shows its arguments, a description and a larger drawing. \begin{ lists environments,
and inside \frac{…}{…} a hint names the argument you are in. Commands from math packages the
book does not enable are not offered.
Source mode draws display math under its source (and, if you turn it on in the preferences, a
small preview after inline math). Macros from the book's preamble, the page's front matter
(math: preamble:) and any \newcommand on the page are known to every preview.
In the visual editor, click a formula (or select it and press Enter) to edit its TeX with the same completion, while the drawing updates as you type; a formula that does not compile keeps its last good drawing, outlined. Enter (inline) or Mod+Enter (display) and Esc finish; ← at the start or → at the end leave the formula on that side.
TikZ diagrams
The toolbar's TikZ button (or /tikz in the visual editor) inserts a ```tikz fence. Write
the picture's commands, an environment such as tikzcd or circuitikz, or a pgfplots
axis; \usetikzlibrary{…} lines at the top are its preamble. The diagram is drawn under
the fence (in the visual editor, under its code block) by a TeX engine that runs in your browser;
the first diagram loads it (about 5 MB, once). TeX errors show with the line that caused them.
Drawings are saved with the book as they appear and again when you publish, so readers get them
as part of the page, in the text colour. Give each diagram an alt="…" description, and wrap it
in :::figure for a caption and a number. See the Markdown reference.
Self-check questions
Three kinds of question let readers check themselves, alone or grouped in a :::quiz (which
shows a score once every question is answered):
choice: a task list where[x]marks the right option (several make it "select all that apply"). A quote indented under an option (> …) is shown when a reader picks it.numeric:answer=6 unit=V tolerance=2%. Readers may answer6,6 V,6000 mVor6e0; the tolerance is a percentage or an amount.short-answer:accept="ohm|ohms|Ω"; case, accents and extra spaces do not matter.
An :::explain block inside a question opens once it is answered. Answers travel in the page
encoded, so they are not in search results. Readers' answers are kept (in their account, or in
the browser until they sign in), and a labelled question ({#q-ohm}) becomes a knowledge
point: it can be reviewed, rates itself in a review session, and comes back for review after a
wrong answer. Statistics in the console lists the questions readers find hardest.
Glossary
A :::glossary holds the book's terms as a definition list (:::keyterms lists count too):
:::glossaryResistor {aka="resistors, R"}: A component that opposes the flow of current.:::aka lists other forms of the term. Elsewhere, :term[resistor] links to the definition
(:term[resistors]{key=resistor} when the text differs); readers see it on hover, focus or tap.
Terms can be defined on any published page of the book; a term that is not defined anywhere is
flagged. With Reader features → Link glossary terms on (the default), the first use of each
term on a page is linked by itself (not in headings, links, code or math). Published terms are
listed on the book's glossary page.
Charts
The toolbar's chart button opens the chart builder: paste cells from a spreadsheet (or CSV,
TSV or JSON), upload a CSV, TSV, JSON or Excel file, link a data file from the book's files, or
use a labelled table on the page. Choose the chart type, the columns for each axis and the
options; the preview is drawn exactly as readers will see it. The builder writes a
```chart fence, which you can also type directly (/chart, or /plot for a function
plot such as a Bode diagram). Completion suggests its options, their values and the column
names of its data.
Both editors draw the chart under its fence as you type; problems (a misspelt column, an
expression that does not parse) show under it in the compiler's words. In the visual editor,
Edit chart… reopens the builder; from the toolbar, Chart from this table… charts the
table at the cursor. A linked file (src=) is read again when you publish, so editing the
file updates the chart. Give every chart an alt="…" description: readers can also show its
data as a table and download it as CSV.
Tables
The toolbar's table button opens a size grid: pick the number of columns and rows (the first row is the header). In the visual editor:
- Tab and Shift+Tab move between cells; Tab in the last cell adds a row.
Enter moves down a column (adding a row at the end), Mod+Enter inserts a row
below, Shift+Enter breaks the line inside a cell (saved as
<br>), and Alt+↑ ↓ move the row. - Hover the strip above or beside the table: a + on the border between two columns or rows inserts one there, and the bars after the last row and column add one at the end.
- The grip above a column or beside a row selects it and opens its menu: insert, move, align, sort the rows by that column, or delete.
- While the cursor is in a table, its toolbar adds a row or column, aligns the column, adds a
caption (a numbered
:::table) or deletes the table. - Paste cells copied from a spreadsheet to make a table, or to fill the table the cursor is in.
Tables stay plain Markdown: one header row, one alignment per column and no merged cells or column widths. The table button's Grid editor… edits the table at the cursor (or a new one) as a spreadsheet-like grid: arrow keys move between cells, blocks of cells paste in, CSV, TSV and Excel files import, and Apply writes the table back in one change.
In source mode, the cursor's table gets its own tools:
- A small toolbar above the table inserts and deletes rows and columns, aligns and sorts by the
cursor's column, lines the columns up, opens the grid editor and makes a chart of the table
(labelling it
:::table{#id}and linking the chart withdata=#id); More moves rows and columns, transposes, copies the table as CSV or TSV, or adds a caption. Esc hides it. - The header row is bold, the pipes are muted and the cursor's column is tinted; the status bar shows the row and column.
- Tab and Shift+Tab move between cells, Enter goes down a column (on an
empty last row it leaves the table), Shift+Enter writes
<br>, Mod+Enter inserts a row, and Alt with the arrow keys moves rows (and, with Shift, columns). - Columns line up by themselves a moment after you stop typing (Editor preferences → Align tables: while typing, on save, or off); undo takes the typing and the alignment back together.
- Rows with too few or too many cells, a missing separator row and a
|inside code are flagged, each with a one-click fix. - Cells pasted from a spreadsheet become a table; pasted into a table, they fill it from the cursor and grow it as needed (the toast offers Paste as plain text instead).
Completion
Source mode completes as you type, and Ctrl+Space asks for suggestions:
- components after
:::,::and:, and their attributes and values; - labels for
:ref[and:cite[, forrequires=anduses=(several, separated by commas), and from other books asbook-slug/label; - a suggested label after
{#, made from the component's title (duplicates are underlined); - canvases for
::canvas{src=, pages forlink-cardaddresses, presets for sizes; [[for a link to another page of the book, and> [!for alert kinds.
History
Every page keeps checkpoints of its draft: one at most every 10 minutes while you write, one each time you press Mod+S, and one before a restore. Published versions are kept too. Checkpoints are thinned over time (hourly after a day, daily after a week) and removed after 30 days; published versions stay.
The History tab lists them by day with the lines and words changed. Compare any two entries as rendered pages (changed paragraphs marked word by word), side by side, or as a unified diff, and restore an older version.
Knowledge points
Give a statement a label and it becomes a knowledge point when the page is published:
:::definition[Limit]{#def-limit difficulty=1}The value $f(x)$ approaches as $x$ approaches $a$.:::
:::theorem[Squeeze theorem]{#thm-squeeze difficulty=2 requires="def-limit"}If $g \le f \le h$ near $a$ and $g, h \to L$, then $f \to L$.:::requires lists the points a statement depends on and uses the ones a solution or proof
applies; together they draw the knowledge graph. difficulty runs from 1 (core) to 3 (challenging), and aka lists other names for the point.