Nota Tutorial

This page explains the basics of Nota's language syntax and component library. You can either edit the examples here interactively, or you can follow the instructions on the home page to install Nota and edit files on your own computer.

    Syntax

    A Nota document is text mixed with commands, typically contained in a .nota file. A basic Nota document looks like this:

    Nota: A Document Language for the Browser

    NOTA is my favorite way to write documents!

    Nota supports three kinds of commands:

    @-commands

    @-commands add document components to the output. This includes HTML elements, like @em for italics, as well as React components, like @Title. Nota provides a standard library of components such as @Title, @Section, @Ref, and many more. And you can also provide your own!

    Here are some examples of translations between an atcmd and the corresponding component (in JSX syntax).

    Nota Translated
    @a <a />
    @a{Text} <a>Text</a>
    @a[href="url"]{Text} <a href="url">Text</a>
    @(window.a)[href="url"]{Text} <window.a href="url">Text</window.a>

    Commands generally have three pieces: a name, code arguments, and text arguments.

    • A name is a Javascript expression: either a plain identifier, like a, or a parenthesized expression like (window.a).
    • Code arguments use [square brackets] take Javascript code as input, for instance @a[href="url"]. atcmds only take named code arguments, indicated by href=.
    • Text arguments use {curly braces} and take text (and Nota commands) as input, such as {Text}. An atcmd can only take one text argument.

    #-commands

    #-commands add Javascript expressions to the output. For example, #sysname embeds the value of the variable sysname. With parentheses, one can use any Javascript expression such as #(sysname.toUpperCase()).

    Here are some examples of translations between an hashcmd and the corresponding component (in Javascript syntax).

    Nota Translated
    #sysname sysname
    #toUpperCase[sysname] toUpperCase(sysname)
    #toUpperCase{#sysname} toUpperCase([sysname])
    #(sysname.toUpperCase()) sysname.toUpperCase()
    #charCodeAt[sysname][0] charCodeAt(sysname, 0)

    If a hashcmd has no arguments, it is treated as a variable. If it is given arguments, then it is treated as a function call. Because Javascript only supports positional arguments, the code arguments to hashcmds do not have names, and the order of arguments matters.

    Because text arguments may contain commands, they are not translated directly to strings, but rather to heterogenous arrays containing strings and document components. For instance:

    Nota Translated
    Hello world. ["Hello world."]
    Hello #sysname. ["Hello ", sysname, "."]
    Hello @em{world}. ["Hello ", React.createElement("em", ...["World"]), "."]

    %-commands

    %-commands add Javascript statements to the output. For example, %(let sysname = "Nota") is not inherently visible in the document, but can be used in expressions like #sysname. pctcmds take no arguments. You simply put %(...) and add any Javascript statement, including imports and exports.}

    Statements are scoped, so variables defined are only accessible after the statement and within the current text block. For example, the command:

    @span{%(let x = 1) x = #x}

    translates to (in JSX):

    <span>{(()=>{let x = 1; return [" x = ", x]})}</span>

    Javascript

    Nota extends Javascript with the ability to embed an atcmd within a Javascript expression. This feature can be useful for creating utility functions, or for passing Nota text into third party libraries. For example, the equivalent of a LaTeX \newcommand macro:

    The expression means or .

    Components

    The best way to understand the many Nota components is to read through an example on the Examples page. But we will review a few common and special ones here.

    Document structure

    A Nota document is always contained within a @Document component. Within a document, the main structural components are @Title, @Section, and @p. A @Document does things to help you simplify structure and reduce nesting. First, sections are automatically nested based on the order of headers. Second, paragraphs are automatically generated based on newlines. For example, this Nota input on the leftdoc is translated to the equivalent on the rightdoc.

    Definitions and references

    Nota provides @Definition and @Ref components for defining things and referencing them in a general way. For example:

    Nota is a document language for the browser. Have you tried writing nota?

    A definition has four pieces:

    1. name: required, string by which to reference this definition.
    2. Label: optional, element that is shown (by default) for a reference to this definition.
    3. Tooltip: optional, element to show when a reference to this definition is clicked (by default the definition's body).
    4. The definition body.

    A reference's text argument is the definition's name. You can optionally define the content of the reference:

    Nota is a document language for the browser. Have you tried writing nota?

    Math / TeX

    Nota provides inline and block math elements, $ and $$ respectively. Currently these use the KaTeX library for rendering.

    The Cauchy-Schwarz inequality states that for all vectors and of an inner product space it is true that

    While you can use TeX macros if necessary, it is recommended to use Javascript variables and functions as shown above. Macros are only essential for referencing TeX builtins such as \leq for .

    The KaTeX integration for Nota provides special support for definitions and references. For example:

    The judgment is defined as:

    Nota provides the function tex_ref for TeX code which refers to a Nota definition, such as "reaches" here. Then any reference to the judgment via the reaches function will support definition-reference features: click to see the definition, and double-click to jump to it.

    Code

    Nota currently uses Codemirror 6 for code editing and viewing. For example:

    Codemirror does not support server-side rendering and currently has limited language support, so contributions for other syntax highlighting libraries are welcome!

    Citations

    The @References component takes as input a BibTeX string (usually imported from a .bib file) and does two things:

    1. It creates a @Definition for each citation where the name is the one provided in bibtex.
    2. It shows the references of all citations used in the document.

    For example:

    Nota is a document language for the browser crichton2021nota.

    References

    Styling

    Nota components do not have much default styling to allow authors greater flexibility in their own designs. To add your own styling, you can use CSS. For example, directly via a style tag:

    I love the color red!

    You can also import an external stylesheet. For example, Nota provides a set of themes. The current list of Nota themes: is:

    To use a theme, you simply import its CSS, such as: