CanvasNative

CanvasNative is a method of representing Canvas documents in a linear fashion (e.g. not JSON) while including metadata about the document's contents.

This project comprises the specification and utilities for the CanvasNative format.

Development

A single command will build distribution code, and the README file:

npm run build

Make sure and run this before each commit!

While developing, it is useful to run npm run watch. This will run a foreground process that monitors all build- and test-dependent files, and run the build and test processes as needed.

To run the watch command, both watchman and pywatchman are required. On OS X with Homebrew and Python already installed, the installation looks like this:

brew install watchman
sudo pip install pywatchman

Then, in a new terminal window, npm run watch should work.

Documentation Note

CanvasNative uses an invisible character to separate parts of its lines. For readability, the documentation replaces that character with |.

Types

In a CanvasNative document, an individual line is one of several types. Typically, a line has the following format:

^(?<typeKey>[a-z])\|(?<metadata>{.*?})\|(?<content>.*)$

Or, more readably:

${typeKey}|${metadata}|${content}

In a line, the typeKey seen above is a typically two-character identifier for a specific line type. The metadata property is a JSON string containing information about the line.

So, a line of Ruby code might look like this:

co|{"language":"ruby"}|class MyClass extends OtherClass

Blockquote Line

A line of a quote pulled from an outside source.

Parameters

This type has no parameters.

Examples

Markdown

> Hello, world!

Native

bq|{}|Hello, world!

---

Checklist Item

A checklist item represents an item in a checklist. It can be nested, and may or may not be checked.

Parameters

Required

• level (number) - The level of nesting of this checklist item, from 1 to 6
• complete (boolean) - Whether this item is complete

Examples

Markdown

- [ ] Buy eggs

Native

cl|{"level":1,"complete":false}|Buy eggs

---

Code Line

A code line represents a line of code, typically in a block of other lines of code.

Parameters

Optional

• language (string) - The language the code line is written in

Examples

Markdown

``` ruby
puts "hi"
```

Native

co|{"language":"ruby"}|puts "hi"

---

Heading

A heading represents a line of heading text at a specific level, from one to six.

Parameters

Required

• level (number) - The level of heading this is, from 1 to 6

Examples

Markdown

# Section Title

Native

hd|{"level":1}|Section Title

---

Horizontal Rule

A horizontal rule represents a visual horizontal separator in a document.

Parameters

This type has no parameters.

Examples

Markdown

---

Native

hr|{}|

---

Image

An image represents a visual image embedded in a document.

Parameters

Optional

• url (string) - undefined
• width (number) - The width, in pixels, of the image
• height (number) - The height, in pixels, of the image
• alt (string) - The alt text to display on top of the image
• title (string) - The title of the image
• uploadCacheID (string) - A UUID identifying an image being uploaded

Examples

Markdown

![Alt text](https://example.com/image.png "Title")

Native

im|{"url":"https://example.com/image.png","width":800,"height":600,"alt":"foo","title":"foo","uploadCacheID":"foo"}|

---

Link Definition

A line that defines a link referred to elsewhere in the document.

Parameters

Required

• name (string) - The name of this link definition
• url (string) - The URL that this link points to

Examples

Markdown

[Google]: https://www.google.com

Native

ld|{"name":"foo","url":"foo"}|

---

Ordered List Item

An ordered list item represents an item in a list whose order is important.

Parameters

Required

• level (number) - The level of nesting of this list item, from 1 to 6

Examples

Markdown

1. Chapter One

Native

ol|{"level":1}|Chapter One

---

Paragraph

A plain paragraph of text.

Parameters

This type has no parameters.

Examples

Markdown

This is a paragraph.

Native

pg|{}|This is a paragraph.

---

Title

The title of a document, which comes from a level 1 header at the very beginning of parsed Markdown, if one is present.

Parameters

Required

• version (number) - The version of the CanvasNative format this document uses

Examples

Markdown

# Title

Native

ti|{"version":1}|Title

---

Unordered List Item

An unordered list item represents an item in an unordered list.

Parameters

Required

• level (number) - The level of nesting of this list item, from 1 to 6

Examples

Markdown

- Foo

Native

ul|{"level":1}|Foo

---