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.
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 pywatchmanThen, in a new terminal window, npm run watch should work.
CanvasNative uses an invisible character to separate parts of its lines. For
readability, the documentation replaces that character with |.
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
A line of a quote pulled from an outside source.
This type has no parameters.
> Hello, world!
bq|{}|Hello, world!
A checklist item represents an item in a checklist. It can be nested, and may or may not be checked.
level(number) - The level of nesting of this checklist item, from 1 to 6complete(boolean) - Whether this item is complete
- [ ] Buy eggs
cl|{"level":1,"complete":false}|Buy eggs
A code line represents a line of code, typically in a block of other lines of code.
language(string) - The language the code line is written in
``` ruby
puts "hi"
```
co|{"language":"ruby"}|puts "hi"
A heading represents a line of heading text at a specific level, from one to six.
level(number) - The level of heading this is, from 1 to 6
# Section Title
hd|{"level":1}|Section Title
A horizontal rule represents a visual horizontal separator in a document.
This type has no parameters.
---
hr|{}|
An image represents a visual image embedded in a document.
url(string) - undefinedwidth(number) - The width, in pixels, of the imageheight(number) - The height, in pixels, of the imagealt(string) - The alt text to display on top of the imagetitle(string) - The title of the imageuploadCacheID(string) - A UUID identifying an image being uploaded
im|{"url":"https://example.com/image.png","width":800,"height":600,"alt":"foo","title":"foo","uploadCacheID":"foo"}|
A line that defines a link referred to elsewhere in the document.
name(string) - The name of this link definitionurl(string) - The URL that this link points to
[Google]: https://www.google.com
ld|{"name":"foo","url":"foo"}|
An ordered list item represents an item in a list whose order is important.
level(number) - The level of nesting of this list item, from 1 to 6
1. Chapter One
ol|{"level":1}|Chapter One
A plain paragraph of text.
This type has no parameters.
This is a paragraph.
pg|{}|This is a paragraph.
The title of a document, which comes from a level 1 header at the very beginning of parsed Markdown, if one is present.
version(number) - The version of the CanvasNative format this document uses
# Title
ti|{"version":1}|Title
An unordered list item represents an item in an unordered list.
level(number) - The level of nesting of this list item, from 1 to 6
- Foo
ul|{"level":1}|Foo