Nota: A Document Language for the Browser

My hope is that in the near-term, I (or other early-adopters) will create a gallery of documents that use Nota's features to convey information in a compelling way. Those examples will convince more people to adopt Nota for their blog or website. Maybe a forward-looking academic workshop convinces its authors to write their papers in Nota. And eventually some Nota will gather some institutional momentum to fund its development. Once there are enough Nota documents worth archiving, then people/orgs will invest resources into archival stability.

So right now, I'm more interested in convincing people that using Nota can enable them to write documents that are significantly better for readers without significantly more effort on behalf of the authors.

The complexity of Javascript and React gives you two main benefits:

1. You can use Javascript as a metalanguage to manipulate the document, e.g. to make and reference variables, perform computations, and so on.

2. You can use React to provide semantic structure and interactivity to your document, e.g. to mark definitions of vocabulary and link references back to the definition.

Nota consists of a syntax, a compiler that goes from Nota document to React program, and a set of React components that are commonly used in Nota documents. You could integrate it into a website or CMS, but it is not inherently any kind of information management system.

1. An alternative syntax (vs. JSX) for writing React programs.

2. A set of React components for structuring a web document

As a syntax, Nota is meant to make writing prose-heavy React easier. As a set of components, Nota is meant to help readers use the document's structure for understanding the document's content, e.g. by showing the definition of a term when you click on it. It's not a replacement for HTML or Javascript, but an alternative syntax for them with a rich standard library.

Additionally, I found the composition semantics between Markdown and JSX somewhat confusing. Random whitespace and newlines would sometimes have a very significant effect on the resulting document. It wasn't really clear when you would be in Markdown mode vs. JSX mode.

FWIW the Nota React components (e.g. @Definition and @Ref) could be used with MDX. The Nota syntax and Nota runtime are separate.

The goal isn't really to compete with lightweight markup languages like Markdown. There are plenty of those. The goal is to provide a language for writing complex, interactive documents like academic papers.

It isn't as simple as bringing LaTeX to the web. There are many things that LaTeX cannot do or express (e.g. like a tooltip popping up when you click on a reference to a definition). The goal of Nota is to make things like that possible.

I'll be adding an "Examples" page with more interesting content soon.

The reason for using React is that it provides a nice model for components that encapsulate state and interactivity, so a user can just write "@Component{contents}" and the component author can deal with all the tricky UI issues. A design goal for Nota is to be as declarative as possible, while still integrating nicely with Javascript.

* YAML for the page metadata (title: ...)

* Markdown (```{python}...```)

* Custom in-text notations (@fig-polar)

* Custom markdown notations (#| label: fig-polar)

Whereas in Nota, this would look like:

    %(export let metadata = {
      title: "matplotlib demo",
      format: {html: {codeFold: true}},
      jupyter: "python3"
    })

    For a demonstration of a line plot on a polar axis, see @Ref{fig-polar}.

    @Code[language=Python][label="fig-polar"][figCap="A line plot on a polar axis"]{
      import numpy as np
      import matplotlib.pyplot as plt

      r = np.arange(0, 2, 0.01)
      theta = 2 * np.pi * r
      fig, ax = plt.subplots(
        subplot_kw = {'projection': 'polar'} 
      )
      ax.plot(theta, r)
      ax.set_rticks([0.5, 1, 1.5, 2])
      ax.grid(True)
      plt.show()
    }

Note that Quarto's "#| fig-cap" annotation probably doesn't allow for rich text captions, since it only allows strings. But Nota allows deep composition, so you could do:

    @Code[figCap=@{A @strong{line plot} on a @em{polar axis}}]{
      ...
    }

There's probably a phrase for what I'm describing but that markdown does well -- something like, keep the "source" as clean as possible and only invoke "code" as absolutely needed. Moreover, strive to be human friendly when you do that.

There's a broader issue of layout, like if you want to print a Nota document and a figure is split across two pages. I'm not sure how to handle that, or if it even makes sense to. The goal of Nota is to move away from the paper document model, although people of course still like to print things and scribble on them.

Nota doesn't require users to specify the implementations of things like footnotes. The goal is the user just says "@Footnote{content}" and the document renderer takes care of all the layout. And you can swap in different implementations of the Footnote component.