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:
You can write the document using the first command. The second command generates a directory
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.
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:
@nota-lang/nota-components: A set of React components for structuring documents.
@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.
@nota-lang/nota-syntax package exports two key functions:
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!
notaPlugin and add it to your list of plugins:
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:
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.
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.
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:
Then incorporate it into your build script:
And then provide the configuration path to the editor:
If your document contains local URLs to assets like images, then you can configure the editor to serve files out of a given directory: