TOML is a configuration format that can be easily read and understood by humans and machines alike.
To learn more about TOML, you can visit its website at https://toml.io.
To see the TOML declaration that translates into the rendered graph you are reading right now, visit the "TOML Graph" link on the top navigation bar.
""" summary = "TOML is a configuration format that can be easily read and understood by humans and machines alike." title = "TOML" links = [] redirect = "" hidden = false [nodes.TOML.connections] [nodes.TOML.stats] outgoing = 0 incoming = 0 [nodes.Acknowledgments] id = "Acknowledgments" text = """en is only possible thanks to a number of projects and people:
An overview on building from source is available in the Documentation page. This page contains a more detailed and considered approach for those interested.
Source builds are tested on both Debian and Alpine, meaning en should compile and run on both glibc and musl systems.
A Rust toolchain is required to build en itself and can be installed through rustup.
For compiling en dependencies, you will also need a C toolchain: a compiler and a libc (e.g. gcc + glibc or clang + musl), which may already be installed on your system.
For the two tested systems, all you need are the following packages:
| Distribution | Needed packages |
|---|---|
| Debian | gcc libc6-dev |
| Alpine | clang |
You may also need curl, git and ca-certificates depending on how you will fetch the source code.
Aside from the cargo install approach described in Documentation, you can alternatively fetch the code yourself using Git, which allows you to inspect and change it before compiling:
git clone -b v0.4.0-alpha --single-branch https://codeberg.org/jutty/en cd en cargo build --locked --release
In this case, the en binary will be in target/release/en.
You can find the exact commands used to test installation on both systems in the containers directory of the en source repository.
The backslash (\\) works by immediately adding the following character as a literal and skipping any further interpretation of it.
For example, if you want to write inline unformatted text containing a backtick, you will need to escape it, so that to render println!("`") as unformatted inline text, you'd write `println!("\\`")`, otherwise the second backtick would close the code tag midway through it.
If you want to render a literal backslash, you can escape the backslash itself by using two backslashes: \\\\.
Notice that TOML itself also handles escape codes, so to pass a backslash you will need to escape it as a double backslash inside strings delimited by double quotes or triple double quotes. You can use a single backslash inside a string delimited by single quotes:
[node.Double] text = "You need double slashes to escape an asterisk here: \\\\*" [node.TripleDouble] text = ""\" Just like here: \\\\* ""\" [node.Single] text = 'Here you need just one: \\*" [node.TripleSingle] text = ''' Here too: \\* '''
This has nothing to do with en's markup syntax per se, it's just a consequence of how backslashes are also special in TOML syntax. For more details, see the TOML documentation on Strings.
en will happily accept HTML code and pass it along to the browser, so you can use any feature from it as a sort of superset.
If you want to prevent a particular part of your text from being interpreted as HTML, you can escape it as you normally would.
The fact you are using HTML does not exclude en syntax from being interpreted, although this may change in the future. Presently, you need to escape en markup syntax if you want it printed literally even inside HTML tags. This matters because en uses its syntax to create connections between your graph's nodes and makes several decisions based on these relations.
""" summary = 'The backslash (\) works by immediately adding the following character as a literal and skipping any further interpretation of it.' title = "Escaping" links = [] redirect = "" hidden = false [nodes.Escaping.connections.TOML] to = "TOML" from = "Escaping" detached = false [nodes.Escaping.stats] outgoing = 0 incoming = 0 [nodes.Documentation] id = "Documentation" text = '''The easiest way to get started is by downloading a pre-built binary.
x64 Linux binaries are available from the git.jutty.dev package registry:
| Platform | Download |
|---|---|
| x64 Linux GNU | en-x64-linux-gnu |
| x64 Linux musl | en-x64-linux-musl |
If in doubt, it is likely your system uses the GNU libc. Regardless, the musl binary is statically compiled and should run on mostly any x64 Linux system.
Other platforms may be supported in the future depending on CI resources.
If you are on another platform or simply paranoid, you can also build en yourself.
You will need:
gcc)Given the above is satisfied, you can build directly through Cargo:
cargo install --git https://codeberg.org/jutty/en --tag v0.4.0-alpha
And you should now have the en command available on your shell.
The cargo install example shown above will build en from the last tagged release, which should be more stable. You can remove the --tag v0.4.0-alpha part if you'd like to build the most recent development sources.
For more details on building from source, see SourceBuild.
Once you have installed en, run it and point it to your graph:
en --graph my-graph.toml
See CLI for defaults and details on the available options.
The graph is a TOML file. You can create nodes by adding text such as:
[nodes.Computer] text = "A computer is a machine capable of executing arbitrary instructions."
If you need longer text, it's more convenient to use triple quotes:
[nodes.Computer] text = """ A computer is a machine capable of executing arbitrary instructions. The main electronic component of a computer is its |motherboard|. """
Some special syntax is allowed inside the node text. See Syntax for supported features.
A node can have several other attributes. See Node for details on all of them.
Nodes can have connections between each other. Each node page lists its outgoing and incoming connections.
The simplest kind of connection is achieved by creating an anchor to another node in the node text itself:
[nodes.Quark] text = "Quarks are subatomic particles that form |hadron|s".
Here, a connection is created from the node with ID Quark to the node with ID Hadron. See AnchorSyntax for the various ways you can link to other nodes from within the node text itself.
Even if a node is not mentioned in the node text, you can still add connections to it. For simple connections without any associated properties, you can simply add links:
[nodes.Quark] text = "A subatomic particle that forms hadrons." links = [ "Particle", "Hadron" ]
This will create two outgoing connections from Quark: to Particle and to Hadron.
For metadata-rich connections, which allow you to add properties to the connection, you can use the full connection syntax:
[[nodes.Realism.connections]] to = "Surrealism" kind = "contrast"
This will create a connection from the node with ID Realism to a node with ID Surrealism and add the "contrast" kind to the connection. See Connections for the existing kinds and how they affect your graph.
A graph is a data structure composed of connected (and disconnected) nodes.
A familiar example is that of a social network. Each account can be thought of as a node and the "follow" and "follower" relationships can be thought of as edges (connections). A node may have many or few connections, and the nodes it is connected to are meaningful to understand how it fits into the whole.
en uses this concept to create a writing tool, allowing you to map out complex thoughts as a web of connected texts.
""" summary = "A graph is a data structure composed of connected (and disconnected) nodes." title = "Graph" links = [] redirect = "" hidden = false [nodes.Graph.connections] [nodes.Graph.stats] outgoing = 0 incoming = 0 [nodes.CLI] id = "CLI" text = """You can set the hostname, port and graph file path using CLI options:
For the hostname, use -h or --hostname:
en -h localhost en --hostname 10.120.0.5
If unspecified, the default is 0.0.0.0.
For the port, use -p or --port:
en -p 3003 en --port 3000
If unspecified, the default is to use a random available port assigned by the operating system.
For the graph path, use -g or --graph:
en -g graph.toml en --g ./static/my-graph.toml
If unspecified, the default is ./static/graph.toml.
You can combine these options as you wish:
en -h localhost -p 3000 en -p 3003 --host localhost --graph ./graph.toml en --g ./graph.toml -p 1312
If an option is specified more than once, the last use will override any previous ones.
""" summary = "You can set the hostname, port and graph file path using CLI options:" title = "CLI Options" links = [] redirect = "" hidden = false [nodes.CLI.connections] [nodes.CLI.stats] outgoing = 0 incoming = 0 [nodes.Node] id = "Node" text = """A node is defined in your graph file starting with a table header of the form:
[nodes.ID]
Where ID is an identifier of your choice.
While the TOML specification is quite flexible regarding what characters can make up this identifier, it's recommended that you keep it simple and use only letters and numbers. See AnchorSyntax for more details on why.
Nodes can have several optional fields that alter how en interprets and displays them.
title: The main heading shown at the top of the page and tab titletext: The textual content that is shown when the node is accessedredirect: Where to redirect any attempt to access the nodelinks: An array of identifiers for other nodes to which this node is connectedhidden: Whether this node should be listed in the index and tree pages. This won't prevent the node from being found or linked to directly through its ID[nodes.Citrus] title = "Citrus Trees" hidden = false text = "Citrus is a |genus| of trees known mainly for its fruits." redirect = "Citric" links = [ "Orange", "Lemon", "Lime", "Grapefruit", ] [[nodes.Citrus.connections]] from = "Citrus" to = "Citric acid"
The example above has all fields in it for completeness, but all fields have default values and are therefore optional. This means that explicitly writing hidden = false is the same as not setting it at all.
The default values for unset fields are:
title: Same as the identifiertext: An empty string (i.e. text = "")redirect: An empty stringlinks: An empty array (i.e. links = [])hidden: falseen's anchor syntax can be very flexible, but some situations lead to ambiguity.
In short, following these two rules should keep you out of trouble:
|text|destination| syntax to make your anchors fully unambiguousConsider this example:
|gem|PreciousStone |PreciousStone|,
Both point to the node with ID PreciousStone, as they indeed seem to. But if we didn't treat punctuation differently, we'd have:
|a|b |a|b
For this reason, some symbols are treated specially at the trailing boundary of anchors.
Punctuation won't be considered as a possible destination, so you can write the previous example and have it behave as expected.
This is one of the reasons special symbols in your node IDs can lead to trouble.
These are the punctuation symbols that are treated specially:
, . : ; ? ! ( ) ' " ` | _ *
Something similar applies to the lowercase letter s:
We found three |boat|s at the marina.
This conveniently lets you write plural words as anchors to their singular form without having to write:
We found three boats|boat at the marina.
Which is annoyting to write and also makes the text a lot noisier.
Unlike with punctuation, this doesn't mean you can't have a node with the ID s. You can, but you'll have to write your anchors to it always with a trailing pipe:
The |letter s|s| is important so we dedicated a whole page to it: |s|!
Like punctuation, node IDs shouldn't have spaces. If you write a node anchor with spaces, it will be collapsed:
This |Node Anchor| will work as if it were |Node Anchor|NodeAnchor|.
As long as you don't have a page with the ID NodeanchoR and another with the ID NodeAnchor, this shouldn't be a problem.
Because node ID resolution redirects to a lowercase match as a fallback to an exact match, you can write:
The next |precious stone| was stolen in 1973.
And the visible text will be preserved as "precious stone" but be able to point to an ID such as PreciousStone.
en must differentiate node anchors from outgoing URLs:
|sample|Example| |sample|https://example.com| |Example| |https://example.com|
It does this by looking at the destination and checking if it contains a :. That's one more reason to avoid this character in your node IDs.
Some fields of your en graph, namely the Node text field, have support for special syntax that allows you to apply formatting and create connections between your graph's nodes.
If you are familiar with Markdown, you'll find some features familiar, with some notable differences too.
Anchors are the most important and powerful syntactic element you will work with because they can create connections between nodes when you use them. They have the following basic syntax:
anchor|destination
For example:
particles|ParticlePhysics
This example will render as the word "particles" pointing to a node with ID ParticlePhysics because the destination is not an external URL.
An external anchor looks like this:
docs|https://en.jutty.dev/node/Documentation
External anchors are identified by the presence of either a : or a / character in the destination. This works for special handlers, such as mailto:user@domain.com, and destinations relative to the website root like /about.
If the left side contains spaces, you need a leading | character:
|en docs|https://en.jutty.dev/node/Documentation
To make a plain address clickable, wrap it in two | characters:
|https://en.jutty.dev|
For internal anchors, most punctuation is automatically separated from the anchor destination so you can simply write:
This gem|PreciousStone, though green, was not an emerald.
This gem, though green, was not an emerald.
However, for external anchors, you want to add a third | to explicitly set the end because external URLs can have all sorts of arbitrary characters.
Because anchors between nodes are central to en, there is special syntax to make them as fluid as possible to create without cluttering the text too much.
A node ID wrapped in two | characters will become an anchor to that node:
|ParticlePhysics|
en can resolve IDs case insensitively (with priority to case-sensitive matches) and will also collapse spaces when trying to resolve an ID, so you can also write:
check out the |en documentation|
And if an anchor with the id enDocumentation or any other case-insensitive combination exists, it will land on it.
In summary, all of the anchors below are valid and lead to the same page:
|syntax|Syntax Syntax|syntax Syntax|syn tax| |Syntax| |syntax| |syn tax|
While flexible, this can sometimes be ambiguous. See AnchorSyntax for some caveats regarding anchors.
Supported formatting syntax includes:
* for bold_ for italics__ for underline~~ for strikethroughTo apply these, you can wrap a word in the formatting operators, so for instance *this* will be rendered as this and ~~this~~ as this.
You can use [ ] and [x] to render checkboxes:
- [ ] not done - [x] done
A block is any group of lines separated by empty lines:
block A still block A block A's last line block B starts here block B ends here this is block C
By default, a block not starting with any special syntax is a paragraph, such as this very line you are reading.
Some blocks will join the lines together, meaning even if you write:
a b c
You still get "a b c" as a result. This is the case for paragraphs, but not for lists, verse blocks, tables and preformatted text. Blockquotes support both modes.
This is useful when editing your text, allowing you to break some thoughts and special syntax without losing control over where your paragraph ends, particularly when handling huge paragraphs.
If you want to force lines to break, you can use a < character at the end of a line:
a < b < c <
Which renders as:
a
b
c
While useful to break a few lines on demand, if you have a large block of lines you want to break this can become cumbersome. That's where verse blocks are useful.
Verse blocks are delimited by a & character at their first and last line and are useful to avoid precisely this line-joining behavior of paragraphs. They will break all lines without need for a trailing < character:
&
these lines
break just fine
once they are over
&
these lines
break just fine
once they are over
A block of lines starting with a > character will render as a quote:
> Who'll change old lamps for new ones?
Who'll change old lamps for new ones?
Quote blocks have two forms. If you prepend all blocks with a >, line breaks will be preserved, not collapsing the whole quote into a single line:
> When I was alive > I was dust which was, > But now I am dust in dust > I am dust which never was.
When I was alive
I was dust which was,
But now I am dust in dust
I am dust which never was.
If you would like the quote to be collapsed into a single line instead, you can leave just the first > and continue until the next empty line:
> And should I feel kindness towards my enemies? No: from that moment I declared everlasting war against the species, and more than all, against him who had formed me and sent me forth to this insupportable misery.
And should I feel kindness towards my enemies? No: from that moment I declared everlasting war against the species, and more than all, against him who had formed me and sent me forth to this insupportable misery.
You can still use < characters to force line breaks in this case.
To add a citation to your quote block, start a line with two - characters:
> with no more communion > to down as morning pick-me-ups > to sweeten afternoon naps > to soothe nightmares -- Assotto Saint, The Language of Dust
with no more communion
to down as morning pick-me-ups
to sweeten afternoon naps
to soothe nightmares
Assotto Saint, The Language of Dust
If you have a more complex citation, you can use multiple lines starting with --. All such lines will be joined together in the citation. If you need to break lines, use the < character at the end of a line:
> Dois grandes mitos dominam a história oficial do Brasil: o mito da índole pacífica do brasileiro e o da "democracia racial". -- Benedita da Silva, -- |Speech on the Federal Senate|https://www25.senado.leg.br/web/atividade/pronunciamentos/-/p/pronunciamento/165765|, -- March 3rd, 1995, < -- International Day for the Elimination of Racial Discrimination
Dois grandes mitos dominam a história oficial do Brasil: o mito da índole pacífica do brasileiro e o da "democracia racial".
Benedita da Silva, Speech on the Federal Senate, March 3rd, 1995,
International Day for the Elimination of Racial Discrimination
The first URL found in your citation will be used as the blockquote element's cite value.
A block of lines starting with a - character will be rendered as an unordered list:
- cyan - amber - crimson
Lines starting with a + character will create numbered lists instead:
+ ichi + ni + san
Tables are blocks delimited by a sole % on its own line:
%
Country ! Capital
Colombia | Bogotá
Belgium | Brussels
Palestine | Jerusalem
Zambia | Lusaka
%
| Country | Capital |
|---|---|
| Colombia | Bogotá |
| Belgium | Brussels |
| Palestine | Jerusalem |
| Zambia | Lusaka |
Table cells are delimited by either a ! for headers or | for common cells. These delimiters must be surrounded by at least one space to each side and are optional at the first and last position of each line.
This means you can use any of the following formats:
%
middle | only
tail | only |
| lead | only
| fully | wrapped |
%
| middle | only |
| tail | only |
| lead | only |
| fully | wrapped |
Because at least one space is required around each delimiter, you must indent the table inside the surrounding % markers by at least one space.
The backtick character ` can be used to render unformatted blocks and inline text:
The asterisk `*` is special in en markup syntax.
The asterisk * is special in en markup syntax.
Using the syntax above, the asterisk won't be interpreted as the start of bold formatting and instead will be shown like this: *.
This is useful for code but also for rendering characters with special meaning you wish to mention literally.
Backticks on their own line will start and close a block of unformatted text such as the ones being used throughout this documentation to show code:
` everything in here will be rendered without formatting `
Finally, you can precede any character with a \ to fully escape that character from being interpreted. Because TOML also treats backslashes specially, you'll likely need to use double slashes, as in \\, unless you wrap your TOML strings in single quotes. See Escaping for more details and examples.
If you need some more advanced feature that is not supported directly by en's markup snytax, you can always just write plain HTML and it will be passed along. For example, you could render a form:
<form style="text-align: center;">
<label for="name"> *__Name__* </label>
<input type="text" id="name"/>
<input type="submit"/>
</form>
Notice that, as shown in this example, you can mix en syntax and HTML. You might want to add a space between your HTML tags and en special syntax so the boundary is clearer, but otherwise they don't tend to overlap since the symbols most used in HTML are not special in en with the exception of <, which is interpreted specially only at the end of lines.
If you want to avoid either one of these syntaxes from being interpreted specially, you should escape the relevant characters as explained in the previous section.
''' summary = "Some fields of your en graph, namely the Node text field, have support for special syntax that allows you to apply formatting and create connections between your graph's nodes." title = "Syntax" links = [] redirect = "" hidden = false [nodes.Syntax.connections.AnchorSyntax] to = "AnchorSyntax" from = "Syntax" detached = false [nodes.Syntax.connections.TOML] to = "TOML" from = "Syntax" detached = false [nodes.Syntax.connections.Escaping] to = "Escaping" from = "Syntax" detached = false [nodes.Syntax.connections.PreciousStone] to = "PreciousStone" from = "Syntax" detached = true [nodes.Syntax.connections.Node] to = "Node" from = "Syntax" detached = false [nodes.Syntax.stats] outgoing = 0 incoming = 0 [nodes.docs] id = "docs" text = "" summary = "" title = "docs" links = [] redirect = "Documentation" hidden = true [nodes.docs.connections] [nodes.docs.stats] outgoing = 0 incoming = 0 [nodes.en] id = "en" text = """en is a tool to write non-linear, connected pieces of text and have their references mapped out as a graph of connected information.
It works by ingesting a TOML file containing your node specification and serving it as a website that allows nodes to be browsed, searched and listed in relation to each other or as a shallow tree of nodes.
en was created out of the desire to write complex, long-form descriptions of a personal worldview without being constrained or getting stuck trying to mimic the linearity of a typical philosophy book.
It's described as a "writing instrument" because it's not so much about the presentation or even the web format. While that's the medium for this particular implementation, you can notice en serves its raw data in both TOML and JSON. It's first and foremost about mapping out and structuring written thoughts.
Because en is defined in simple configuration files, you can add new pages easily from a few lines and start connecting them. Instead of having to create a dedicated file or resource for each new entry you find deserving of observation, with its own beginning and end, its own "I'm empty, fill me to completion" demeanor, you can stay in the flow of your sprawling thoughts. This is meant to fit the specific wiring of minds whose thoughts spread and fork quickly and often, whether to great depth or across wide expanses.
""" summary = "en is a tool to write non-linear, connected pieces of text and have their references mapped out as a graph of connected information." title = "en" links = [] redirect = "" hidden = false [nodes.en.connections.Graph] to = "Graph" from = "en" detached = false [nodes.en.connections.TOML] to = "TOML" from = "en" detached = false [nodes.en.stats] outgoing = 0 incoming = 0 [nodes.Roadmap] id = "Roadmap" text = """Inline codehas_definition)related)has_example)has_references)|node|s -> node)|will|ed -> will)|red fox| -> redfox -> RedFox)# syntax for header ID anchorsDEBUG is unset