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.
A Nota document is text mixed with commands, typically contained in a
.nota file. A Nota document looks like this:
Nota syntax is based on Markdown, specifically CommonMark with some Github Flavored extensions. In the example above,
*favorite* becomes favorite. Some examples of Markdown features are shown in Figure 1.
@, e.g. to use a custom section header
%, e.g. to define variables like
#, e.g. to put the value of
sysname in the header.
Next, we will explore how each of these features works.
Markdown supports a fixed set of components: bold, italics, headers, lists, and so on. But what if you want to use a component that wasn't built in, like an interactive chart? Then you can use a custom component, like
@VegaLite from the Vega-Lite package:
Try clicking on the legend!
If there isn't a component that does exactly what you want, then you can write your own using ReactJS. For example, here's a component that lets users interactively change the text color of the component's children:
At its core, a component has a name (required), a set of attributes (optional), and a sequence of children components (optional). One of Nota's goals is to make it reasonably concise to write components, so there are several syntaxes for writing components. They are:
If you want to learn more about how to write React components, I recommend following a React tutorial such as: https://reactjs.org/tutorial/tutorial.html
One tricky part about using Nota components is how they integrate with Markdown parsing. Markdown is very sensitive to indentation and newlines. For example:
Example 1: this list starts an indentation, matching newlines are part of the same item,
even after empty lines.
But reducing the indentation breaks the list!
**Example 2: you can't bold
over multiple lines.**
In short, Markdown (and CSS) distinguishes block and inline elements. Block elements are things like headers, lists, and paragraphs — they generally take the full width of the page, and stack vertically. Inline elements are things like text, styled text (bold / italics / strikethrough), hyperlinks, and buttons — they flow together horizontally in a sequence.
In Markdown, an empty line is used to delimit inline sequences. So in the example above, the bolding doesn't work because an empty line separates the initial
** from the final
**. This fact means that a program like this would not make sense:
Therefore Nota currently has the following restriction. If a component is in inline position, then its contents MUST not contain any empty newlines.
Another issue arises over whether a Nota command should be treated as a block or inline element. For example, consider these two programs:
The first line should compile into a block element, i.e. a standalone div. The second line should compile into a paragraph that contains the span and the remainder of the text. But this means that the parser doesn't know whether a component is inline or not until reading past the component.
For now, to resolve this ambiguity, the parser assumes that all components at the beginning of a line are block components. You can explicitly indicate that such a component is an inline component by adding a period before @, e.g.
Markdown allows you to write rich text, but it doesn't support any kind of programming. Programming can be useful when writing a document, for example:
I named my system Nota. But if I decide to rename Nota later, then I can just change the variable!
I have a common pattern in my document, like a math formula . So I can use it in equations like:
I have a common structure to my content. So I can encode it in a data structure and write my UI once:
% for a one-line statement, and
%%% for multi-line statements. A %-command does not change the visual display of your document — it only defines data that will be available as the document renders.
Macros: When working with components that take complex string inputs such as , it's useful to have concisely define string-generating macros. Nota adds a new keyword
macro that works like this:
This macro is syntactic sugar for:
With the ability to define variables, you need the ability to use them! A #-command has three roles:
You can use # to embed a variable like Nota in the document.
You can use # to call a function, like
This is a non-exhaustive list of some components that are provided in Nota's standard library.
@Ref components for defining things and referencing them in a general way. For example:
A definition has four pieces:
name: required, string by which to reference this definition.
label: optional, element that is shown (by default) for a reference to this definition.
tooltip: optional, element to show when a reference to this definition is clicked (by default the definition's body).
The definition body.
A reference's text argument is the definition's name. Because references are common in documents, Nota provides a shorthand for writing references:
&def_name (because you're making a pointer to something!). You can optionally define the content of the reference:
Nota provides inline and block math elements,
$$ 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 KaTeX integration for Nota provides special support for definitions and references. For example:
The judgment is defined as:
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.
Nota uses Codemirror 6 for code editing and viewing. For example:
Note that you need to import the corresponding
lang package to get the right syntax highlighting.
@References component takes as input BibTeX string (usually imported from a
.bib file) and does two things:
It creates a
@Definition for each citation where the
name is the one provided in bibtex.
It shows the references of all citations used in the document.
Nota is a document language for the browser .
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:
(...That's it so far! If you make your own theme, we can add it to this list.)
To use a theme, you simply import its CSS, such as: