Nice work as usual, Will. How do you plan to convince users that this is not just a research prototype that will be abandoned after being published, and won't suffer from bit-rot 5 to 10 years from now? You talk about this a bit at the end of the longer paper on Nota, but I'd be curious if you have additional thoughts. Seems like we need something like Talos/immutable infrastructure but for the web (does that exist already?).
Thanks! Currently, I have no plans to convince users of Nota's longevity. It is a research prototype, and I will pursue it as long as I have the time and still think it's a good idea.
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.
I don't understand what it does or is. Is it a sophisticated markup language with embedded JavaScript? What can it do that makes it worth the complexity compared with a markup language - an example would be great. Also, what is the output, a single file?
Also, what are the differences between it and a CMS, such as a wiki?
"Sophisticated markup language with embedded JavaScript" is a fine model of Nota. You can also think about it as another syntax for a React program, like an alternative to JSX that's oriented at writing documents (prose-first) rather than writing websites (code-first).
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.
This is fascinating; I (well, with some support from my advisor IIRC!) implemented some things like this in latex for my thesis, but it was very limited. It still did help me keep track of all the variables and letters.
I'm curious why not do this in MDX instead? Would that have been possible? It seems like it might be a good base that can then interact with other things (e.g. I'd love to just use this in https://motif.land).
I originally tried using MDX. But in my experience, JSX syntax is better suited for writing websites than writing documents. The <Tag></Tag> syntax is more verbose than @Tag{}. I ended up having to do lots of raw string embedding too, like <Component>{r`content...`}</Component> which is even worse. Basically you either had a really concise syntax for special Markdown-supported operations, or you had a really annoying syntax for non-special operations. Nota instead provides a uniform somewhat-nice syntax for both.
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.
This makes a lot of sense. I have been working on something similar, along the lines of mixing Latex and Markdown, and christened it "Recursive TeXt". Currently it only exists as a macOS app with me as the only user (it is still early stage with lots of changes ahead, but all articles on https://practal.com are done with it).
Making React part of this makes a lot of sense on one hand, but on the other hand it feels to me that documents should be more long-lived than React might be. So a compromise might be to use React under the hood for components, but to abstract it away in a document DSL. But that might be just overthinking it.
Latex has its purpose for high quality and fully controllable templating. Does nota try to achieve the same?
Latex, however cluttered its syntax is, benefits a lot from strong tooling that has matured over the decades.
So I'm wondering what the plans are for nota, given that it is a subset of HTML and a subset of latex (judging from reading the examples).
Why not use commonmark? The dynamic argument is kind of invalid, given that markdown.js and other parsers exist and are used heavily on social media web apps and sites.
If the feature gap can be identified as bringing latex to the web: why not implement something like latex.js, which could be embedded in web browsers similar to how pdf.js changed the web?
Nota can express any HTML document. It uses KaTeX for math, so it is as expressive as KaTeX.
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 once felt like I'd like to learn LaTeX (unrelated to math/science, just for casual typesetting). I gave up in half an hour as it became vividly obvious to me it will take a life to master. To me it seems the most alien language I ever seen.
Cool language, I wish it wasn't react though. I guess there's more interactivity possible than shown in the demos; the only thing I've seen are popups for terms. Don't really need react for that.
My original paper on the system shows some more interesting examples, such as logical inference rules that can toggle between natural language and mathematical symbols: https://willcrichton.net/nota/
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.
file formats are really important -- every saas app in 2017 would have been a file format in 1996, and this is an underappreciated reason that computers generally worked better in 96 vs now
file formats, unlike apps, can be declarative. (or pretend to be, but even 'pretend declarative' leads to good tool integrations)
of course saas apps have collaboration and messaging, and file formats don't; whoever figures out how to do messaging in semi-declarative formats will be a player in the 'future of web' space
FWIW: every time you double tap a Nota link something is added to the browser history, at least in mobile Safari, which impacts back button usage by "trapping" you on the page.
The aim seems similar to Quarto (https://quarto.org/) - an "open-source scientific and technical publishing system built on Pandoc" which "create[s] dynamic content with Python, R, Julia, and Observable". @wcrichton how does Nota relate to Quarto and similar prior efforts?
Quarto is a good example where their design requires users to understand many different DSLs to achieve the end result. Just in their code sample you have:
* 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()
}
When code or structured data is involved, Nota is "just Javascript" (e.g. exporting metadata, specifying code literals). When text is involved, Nota provides a small core set of sigils like @Component[attr=value]{content}.
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.
Not yet, but that is a high priority TODO. The simplest toolchain is just "Page Print > Save to PDF", but I need to first improve the printer-oriented CSS.
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.
Would be nice to think about how it compares to something like Pandoc which -- as far as I can tell from the Tutorial -- has all the expressiveness Nota has without being tied down to a particular output stack.
Also Nota doesn't absolve you of having to learn React, JS, etc. which is fine. Lightweight markup often winds up being a DSL over some more powerful underlying stack. But the goal is to separate authoring from styling. I.e. at the authoring stage you don't need to specify how a sidenote or a definition list would be implemented. Nota seems to mix these up.
AFAIK Pandoc doesn't really have a story for interaction. Like, "show a tooltip when someone clicks on this text". That's the main value add for Nota.
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.
What this needs IMNSHO is guarantees that once the document is loaded it won't do anything funny.
My preferred approach is a 1. small subset of modern HTML and css 2. (optional) that can link to a common package of JS to do things like partial updates ans autocomplete.
Main point is: Once the page has loaded nothing goes on in the background unless the user is explicitly changing the document, i.e. regardless of how many such pages you open, your CPU quickly goes to 0 and stay there.
A goal for Nota is to gracefully degrade in the absence of Javascript. This already mostly works, since we do server-side rendering to fully generate the HTML contents of the document before providing it to the client. When you first visit nota-lang.org or willcrichton.net you are seeing the pre-rendered document.
Is there a security model for preventing injection attacks? I'm thinking of content-based injection attacks like those that try to break out of language parser enclosures in HTML or Liquid or SQL or etc.
Presumably the responsibility would largely fall on the component authors but I was curious if there were any language-level threat model or mitigation approach in mind here.
There isn't, and I would say Nota is not suitable for e.g. a commenting syntax on a forum. It's intended for blog posts, papers, or other documents coming from more trusted sources.
[+] [-] moab|3 years ago|reply
[+] [-] wcrichton|3 years ago|reply
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.
[+] [-] wolverine876|3 years ago|reply
Also, what are the differences between it and a CMS, such as a wiki?
[+] [-] wcrichton|3 years ago|reply
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.
[+] [-] account-5|3 years ago|reply
[+] [-] wcrichton|3 years ago|reply
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.
[+] [-] Semiapies|3 years ago|reply
[+] [-] avivo|3 years ago|reply
I'm curious why not do this in MDX instead? Would that have been possible? It seems like it might be a good base that can then interact with other things (e.g. I'd love to just use this in https://motif.land).
[+] [-] wcrichton|3 years ago|reply
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.
[+] [-] practal|3 years ago|reply
Making React part of this makes a lot of sense on one hand, but on the other hand it feels to me that documents should be more long-lived than React might be. So a compromise might be to use React under the hood for components, but to abstract it away in a document DSL. But that might be just overthinking it.
[+] [-] cookiengineer|3 years ago|reply
Latex, however cluttered its syntax is, benefits a lot from strong tooling that has matured over the decades.
So I'm wondering what the plans are for nota, given that it is a subset of HTML and a subset of latex (judging from reading the examples).
Why not use commonmark? The dynamic argument is kind of invalid, given that markdown.js and other parsers exist and are used heavily on social media web apps and sites.
If the feature gap can be identified as bringing latex to the web: why not implement something like latex.js, which could be embedded in web browsers similar to how pdf.js changed the web?
[+] [-] wcrichton|3 years ago|reply
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.
[+] [-] qwerty456127|3 years ago|reply
[+] [-] tonyg|3 years ago|reply
[1] https://docs.racket-lang.org/scribble/index.html
[+] [-] wcrichton|3 years ago|reply
[+] [-] danmur|3 years ago|reply
[+] [-] wcrichton|3 years ago|reply
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.
[+] [-] awinter-py|3 years ago|reply
file formats, unlike apps, can be declarative. (or pretend to be, but even 'pretend declarative' leads to good tool integrations)
of course saas apps have collaboration and messaging, and file formats don't; whoever figures out how to do messaging in semi-declarative formats will be a player in the 'future of web' space
[+] [-] notreallyserio|3 years ago|reply
[+] [-] wcrichton|3 years ago|reply
[+] [-] sm1ch|3 years ago|reply
[+] [-] wcrichton|3 years ago|reply
* 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:
When code or structured data is involved, Nota is "just Javascript" (e.g. exporting metadata, specifying code literals). When text is involved, Nota provides a small core set of sigils like @Component[attr=value]{content}.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:
[+] [-] martopix|3 years ago|reply
[+] [-] jrm4|3 years ago|reply
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.
[+] [-] WolfOliver|3 years ago|reply
I'm thinking if I could make use of this in MonsterWriter. The export in MonsterWriter is based on LaTex which is a little tricky to handle.
Props for building this project, and props for making it a MIT license!
[+] [-] wcrichton|3 years ago|reply
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.
[+] [-] destedexplan|3 years ago|reply
Also Nota doesn't absolve you of having to learn React, JS, etc. which is fine. Lightweight markup often winds up being a DSL over some more powerful underlying stack. But the goal is to separate authoring from styling. I.e. at the authoring stage you don't need to specify how a sidenote or a definition list would be implemented. Nota seems to mix these up.
[+] [-] wcrichton|3 years ago|reply
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.
[+] [-] eitland|3 years ago|reply
My preferred approach is a 1. small subset of modern HTML and css 2. (optional) that can link to a common package of JS to do things like partial updates ans autocomplete.
Main point is: Once the page has loaded nothing goes on in the background unless the user is explicitly changing the document, i.e. regardless of how many such pages you open, your CPU quickly goes to 0 and stay there.
So this could work too.
[+] [-] wcrichton|3 years ago|reply
[+] [-] yodon|3 years ago|reply
Presumably the responsibility would largely fall on the component authors but I was curious if there were any language-level threat model or mitigation approach in mind here.
[+] [-] wcrichton|3 years ago|reply
[+] [-] teg4n_|3 years ago|reply
[+] [-] foobarandlmj|3 years ago|reply
[+] [-] ssl232|3 years ago|reply