Nota Integration Guide

After installing Nota, the simplest way to use it is to input a single document and output a single web page. For example, by running:

nota edit index.nota
nota build index.nota

You can write the document using the first command. The second command generates a directory dist containing the ready-to-distribute files, including HTML, CSS, Javascript, and other assets like images. You can put these files on any web hosting service, such as Github Pages.

If you want to use Nota in a broader context, such as a personal website or an online academic journal, the remainder of this guide will explain Nota's overall architecture, and how it can fit into your use case.

Table of Contents
  1. Architecture
  2. Building
    1. esbuild
  3. Editing
    1. Build configuration
    2. Asset folder

1 Architecture

A Nota document is a React program. Therefore Nota can be used anywhere React can be used. More specifically, Nota is comprised of three main pieces:

  1. @nota-lang/nota-syntax: A document-authoring language that compiles to React JavaScript.

  2. @nota-lang/nota-components: A set of React components for structuring documents.

  3. @nota-lang/nota-editor: An editor designed for Nota documents.

The complete Nota pipeline (in the @nota-lang/nota package) turns a Nota document into a standalone web page. This pipeline includes bundling via esbuild, as well as server-side rendering via ReactDOMServer.

2 Building

The @nota-lang/nota-syntax package exports two key functions:

let tryParse(input: string): Result<lezer.Tree>;
let translate(input: string, tree: lezer.Tree): {code: string; map?: string};

These functions parse and translate, respectively, a Nota document into a React program (via a Lezer tree). If possible, you should not call these functions directly but rather use a bundler integration. Currently we only support esbuild, but other integrations are welcome!

2.1 esbuild

First, import notaPlugin and add it to your list of plugins:

import { notaPlugin } from "@nota-lang/nota-syntax/dist/esbuild-plugin.js";
import esbuild from "esbuild";

esbuild.build({
/* your configuration... */
plugins: [notaPlugin()]
})

This plugin will allow you to import a file with a .nota extension. The file's default export will be the document's React component. For example:

import React from "react";
import ReactDOM from "react-dom";
import Doc from "./index.nota";

let App = () => <div>
<h1>My Website</h1>
<Doc />
</div>;

ReactDOM.renderToString(<App />, document.getElementById('app'));

If you follow the approach above, all pipeline issues like bundling and server-side rendering are up to you. Alternatively, you can use the @nota-lang/esbuild-utils package to get a simple Nota-enabled static site generator that includes bundling and SSR. Check out the build.mjs file for nota-lang.org and willcrichton.net as examples.

3 Editing

You can still use the Nota editor on documents that are not built via nota build. The nota edit command can take additional flags to interoperate with your personal build pipeline.

3.1 Build configuration

If you are using esbuild and have custom esbuild flags, e.g. a plugin like esbuild-sass-plugin, then you can define a configuration file like so:

// nota.config.mjs
import { sassPlugin } from "esbuild-sass-plugin";

export default {
plugins: [sassPlugin()];
}

Then incorporate it into your build script:

// build.mjs
import config from "./nota.config.mjs";
import esbuild from "esbuild";

esbuild.build({
entryPoints: ["./src/index.nota"],
...config
})

And then provide the configuration path to the editor:

nota edit src/index.nota --config nota.config.mjs

3.2 Asset folder

If your document contains local URLs to assets like images, then you can configure the editor to serve files out of a given directory:

nota edit src/index.nota --static assets