Add label for links
This commit is contained in:
+165
@@ -0,0 +1,165 @@
|
||||
# Canvas Spec
|
||||
|
||||
<small>Based on JSON Canvas 1.0 — 2024-03-11</small>
|
||||
|
||||
The file format `jsoncanvas-desktop` reads and writes, in full.
|
||||
|
||||
It is [JSON Canvas 1.0](1.0.md) with a small number of additions. Everything the
|
||||
original defines is implemented, unchanged and under the same names, and the
|
||||
sections below follow its wording. Attributes and rules this editor adds are
|
||||
marked **(addition)** and are collected, with the reasoning behind them, in
|
||||
[extensions.md](extensions.md).
|
||||
|
||||
Files use the `.canvas` extension.
|
||||
|
||||
## Top level
|
||||
|
||||
The top level of JSON Canvas contains two arrays:
|
||||
|
||||
- `nodes` (optional, array of nodes)
|
||||
- `edges` (optional, array of edges)
|
||||
|
||||
## Nodes
|
||||
|
||||
Nodes are objects within the canvas. Nodes may be text, files, links, or groups.
|
||||
|
||||
Nodes are placed in the array in ascending order by z-index. The first node in
|
||||
the array should be displayed below all other nodes, and the last node in the
|
||||
array should be displayed on top of all other nodes.
|
||||
|
||||
### Generic node
|
||||
|
||||
All nodes include the following attributes:
|
||||
|
||||
- `id` (required, string) is a unique ID for the node.
|
||||
- `type` (required, string) is the node type.
|
||||
- `text`
|
||||
- `file`
|
||||
- `link`
|
||||
- `group`
|
||||
- `x` (required, integer) is the `x` position of the node in pixels.
|
||||
- `y` (required, integer) is the `y` position of the node in pixels.
|
||||
- `width` (required, integer) is the width of the node in pixels.
|
||||
- `height` (required, integer) is the height of the node in pixels.
|
||||
- `color` (optional, `canvasColor`) is the color of the node, see the Color section.
|
||||
|
||||
### Text type nodes
|
||||
|
||||
Text type nodes store text. Along with generic node attributes, text nodes
|
||||
include the following attribute:
|
||||
|
||||
- `text` (required, string) in plain text with Markdown syntax.
|
||||
|
||||
### File type nodes
|
||||
|
||||
File type nodes reference other files or attachments, such as images, videos,
|
||||
etc. Along with generic node attributes, file nodes include the following
|
||||
attributes:
|
||||
|
||||
- `file` (required, string) is the path to the file within the system.
|
||||
- `subpath` (optional, string) is a subpath that may link to a heading or a block. Always starts with a `#`.
|
||||
|
||||
### Link type nodes
|
||||
|
||||
Link type nodes reference a URL. Along with generic node attributes, link nodes
|
||||
include the following attributes:
|
||||
|
||||
- `url` (required, string)
|
||||
- `label` (optional, string) is the text displayed for the node in place of its
|
||||
URL. A label that is empty or only whitespace is treated as no label. **(addition)**
|
||||
|
||||
### Group type nodes
|
||||
|
||||
Group type nodes are used as a visual container for nodes within it. Along with
|
||||
generic node attributes, group nodes include the following attributes:
|
||||
|
||||
- `label` (optional, string) is a text label for the group.
|
||||
- `background` (optional, string) is the path to the background image.
|
||||
- `backgroundStyle` (optional, string) is the rendering style of the background image. Valid values:
|
||||
- `cover` fills the entire width and height of the node.
|
||||
- `ratio` maintains the aspect ratio of the background image.
|
||||
- `repeat` repeats the image as a pattern in both x/y directions.
|
||||
|
||||
## Edges
|
||||
|
||||
Edges are lines that connect one node to another.
|
||||
|
||||
- `id` (required, string) is a unique ID for the edge.
|
||||
- `fromNode` (required, string) is the node `id` where the connection starts.
|
||||
- `fromSide` (optional, string) is the side where this edge starts. Valid values:
|
||||
- `top`
|
||||
- `right`
|
||||
- `bottom`
|
||||
- `left`
|
||||
- `fromEnd` (optional, string) is the shape of the endpoint at the edge start. Defaults to `none` if not specified. Valid values:
|
||||
- `none`
|
||||
- `arrow`
|
||||
- `toNode` (required, string) is the node `id` where the connection ends.
|
||||
- `toSide` (optional, string) is the side where this edge ends. Valid values:
|
||||
- `top`
|
||||
- `right`
|
||||
- `bottom`
|
||||
- `left`
|
||||
- `toEnd` (optional, string) is the shape of the endpoint at the edge end. Defaults to `arrow` if not specified. Valid values:
|
||||
- `none`
|
||||
- `arrow`
|
||||
- `color` (optional, `canvasColor`) is the color of the line, see the Color section.
|
||||
- `label` (optional, string) is a text label for the edge.
|
||||
|
||||
## Color
|
||||
|
||||
The `canvasColor` type is used to encode color data for nodes and edges. Colors
|
||||
attributes expect a string. Colors can be specified in hex format e.g.
|
||||
`"#FF0000"`, or using one of the preset colors, e.g. `"1"` for red. Six preset
|
||||
colors exist, mapped to the following numbers:
|
||||
|
||||
- `"1"` red
|
||||
- `"2"` orange
|
||||
- `"3"` yellow
|
||||
- `"4"` green
|
||||
- `"5"` cyan
|
||||
- `"6"` purple
|
||||
|
||||
Specific values for the preset colors are intentionally not defined so that
|
||||
applications can tailor the presets to their specific brand colors or color
|
||||
scheme. This editor uses one set of six shades for both of its themes, and blends
|
||||
them into a node's fill with more of the shade in the dark theme than in the
|
||||
light one.
|
||||
|
||||
## Unrecognised data **(addition)**
|
||||
|
||||
Anything in the file this spec does not describe is kept as it was:
|
||||
|
||||
- unknown top-level keys,
|
||||
- unknown attributes on a node or an edge,
|
||||
- nodes whose `type` is none of the four above — the whole node is kept, and the
|
||||
canvas displays a placeholder in its place.
|
||||
|
||||
Unrecognised data is written back unchanged, after the attributes this spec
|
||||
defines. This makes a file written by another application survive a load and save
|
||||
untouched.
|
||||
|
||||
## Reading **(addition)**
|
||||
|
||||
A file that does not follow this spec exactly is still read, as far as it can be:
|
||||
|
||||
- a missing `x` or `y` is `0`; a missing `width` is `250` and a missing `height`
|
||||
is `60`; a size below `1` is raised to `1`,
|
||||
- a position or size given as a fractional number is rounded to an integer,
|
||||
- a missing `text`, `file` or `url` is the empty string,
|
||||
- a `canvasColor` given as a JSON number, e.g. `1`, is read as the preset of that
|
||||
number, and the three-digit hex form `"#f0a"` is accepted,
|
||||
- an attribute whose JSON type is not the one this spec asks for — including a
|
||||
`canvasColor` that is neither a preset nor a hex string — is left untouched as
|
||||
unrecognised data, and the attribute counts as absent,
|
||||
- an edge naming a `fromNode` or `toNode` that no node has is kept; the canvas
|
||||
reports how many there are and offers to remove them.
|
||||
|
||||
## Writing **(addition)**
|
||||
|
||||
- `nodes` and `edges` are always written, as arrays, even when empty.
|
||||
- Attributes are written in the order this spec lists them, so a save produces a
|
||||
small diff rather than a reshuffle.
|
||||
- Optional attributes that were absent stay absent.
|
||||
- Hex colors are written in lowercase.
|
||||
- The file is pretty-printed with two-space indentation and ends with a newline.
|
||||
Reference in New Issue
Block a user