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:

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.

    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.

    Building

    The @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!

    esbuild

    First, import nota_plugin 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.

    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.

    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:

    Then incorporate it into your build script:

    And then provide the configuration path to the editor:

    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: