@curvenote/schema

!CI

Schema for interactive scientific writing, with translations to MyST flavoured markdown, LaTeX, and HTML.

!@curvenote/schema in curvenote.com

Overview & Goals

- Provide a typed schema for writing reactive scientific documents using @curvenote/components
- Uses Web Components in the rendered HTML output for non-standard components
- Uses standard html for all other compnents, with no styling enforced
- Interoperability with CommonMark markdown and MyST
- Through fromMarkdown and toMarkdown methods
- Provide components for WYSIWYG editing of reactive documents
- See @curvenote/editor or curvenote.com for the editor!

Choices

- The internal representation for the library is a ProseMirror Document structure (that can be rendered as JSON)
- markdown-it is used parse and tokenize markdown content

Schema

The schema has Nodes and Marks where Nodes are basically a block of content (paragraph, code, etc.), and Marks are inline modifications to the content (bold, emphasis, links, etc.). See the ProseMirror docs for a visual explanation.

Overview of Nodes

- Basic Markdown
- text
- paragraph
- heading
- blockquote
- code_block
- image
- horizontal_rule
- hard_break
- ordered_list
- bullet_list
- list_item
- Presentational Components
- callout
- aside
- math
- equation
- Reactive Components
- variable
- display
- dynamic
- range
- switch

Overview of Marks

- link
- code
- em
- strong
- superscript
- subscript
- strikethrough
- underline
- abbr

Simple Example

This moves from markdown --> JSON --> HTML. The JSON is the intermediate representation for @curvenote/editor.

``javascript
import { Schema, nodes, marks, fromMarkdown, toHTML } from '@curvenote/schema';
import { JSDOM } from 'jsdom';

const schema = new Schema({ nodes, marks });

const content = '# Hello @curvenote/schema!';
const doc = fromMarkdown(content, schema);

console.log(doc.toJSON());
>> {
"type": "doc",
"content": [
{
"type": "heading",
"attrs": { "level": 1 },
"content": [
{ "type": "text", "text": "Hello " },
{
"type": "text",
"marks": [ { "type": "code" } ],
"text": "@curvenote/schema"
},
{ "type": "text", "text": "!" }
]
}
]
}

// Assuming we are in node, just use document if in a browser!
const { document } = new JSDOM('').window;

// Now move the document back out to html
const html = toHTML(doc, schema, document);

console.log(html);
>> "

Hello @curvenote/schema!

"
`

$3

- Integrate other @curvenote/components` as nodes
- Improve equation and start to go to/from various MyST syntax for this
- Add figure properties (name, width, caption etc.)
- Provide citations, probably bring in a bibtex parser
- Introduce citation and reference component to curvenote/components or article
- Add overlaping roles/directives with MyST (e.g. see executablebooks/meta#70) for pointers
- Add the necessary pieces to curvenote/components that are not basic html (MyST uses sphinx for the heavy lifting, cross-refs etc.)
- Provide other sereializers from the document strucutre (e.g. latex or simple html without curvenote/components, possibly idyll)

See also:

- Idyll Lang has a different markdown-like serialization with very similar base components to curvenote - see curvenote/article#8 for a comparison.