# 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!

%(let sysname = "Nota")

@Section{#sysname: A Document Language for the Browser}

#(sysname.toUpperCase()) is my @em{favorite} way to write @a[href="https://en.wikipedia.org/wiki/Document"]{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 @-command 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"]. @-commands 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 @-command 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 #-command 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 #-command 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 #-commands 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. %-commands 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 @-command 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 .

%(let or = (x, y) => @{#x \vee #y})
The expression @${#or{x}{y}} means @q{@${x} or @${y}}. ## 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 left is translated to the equivalent on the right. @Document{ @Title{My Document} @Section{Introduction} The intro... @Subsection{Contributions} I did... @Section{Related work} It be like... } @Document{ @Title{My Document} @SectionBody{ @SectionTitle{Introduction} @p{The intro...} @SectionBody{ @SectionTitle{Contributions} @p{I did...} } } @SectionBody{ @SectionTitle{Related work} @p{It be like...} } } ### 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? @Definition[name="nota"][label="Nota"]{ Nota is a document language for the browser. } Have you tried writing @Ref{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? @Definition[name="nota"]{ Nota is a document language for the browser. } Have you tried writing @Ref[label=@strong{Nota}]{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 The Cauchy-Schwarz inequality states that for all vectors @{u} and @{v} of an inner product space it is true that %( let u = @{\mathbf{u}}; let v = @{\mathbf{v}}; let vec = (x, y) => @{\langle #x, #y \rangle}; ) @$${
| #vec[u][v] |^2 \leq #vec[u][u] \cdot #vec[v][v]
}

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:
%(let reaches = (u, v) => texRef("reaches", @{#u ~ \mathsf{reaches} ~ #v}))
@Definition[name="reaches"]{
The judgment @${#reaches{n_1}{n_2}} is defined as: @div{ @IR[Top=()=>null][Bot=()=>@${#reaches{n}{n}}]
@IR[Top=()=>@PremiseRow{
@Premise{@${#reaches{n_1}{n_2}}} @Premise{@${#reaches{n_2}{n_3}}}
}][Bot=()=>@\${#reaches{n_1}{n_3}}]
}
}

Nota provides the function texRef 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:

fn char_at(s: &str, i: usize) -> char {
s.chars().nth(i).unwrap()
}
%(import {rust} from "@codemirror/lang-rust")
@Listing[language=rust()]{
fn char_at(s: &str, i: usize) -> char {
s.chars().nth(i).unwrap()
}
}

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 [Crichton 2021].

## References

Will Crichton. 2021. A New Medium for Communicating Research on Programming Languages. Proceedings of the 1st Workshop on Human Aspects of Types and Reasoning Assistants.
Nota is a document language for the browser @Ref{crichton2021nota}.

@References{
\@inproceedings{crichton2021nota,
title={A New Medium for Communicating Research on Programming Languages},
author={Crichton, Will},
booktitle={Proceedings of the 1st Workshop on Human Aspects of Types and Reasoning Assistants},
year={2021}
}
}

## 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!

@style{ span.text-red { color: red; } }

%(let Red = ({children}) =>
@span[className="text-red"]{#children})

I love the color @Red{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:

%(import "@nota-lang/nota-theme-acm/dist/index.css")