en/static/graph.toml

root_node = "Documentation"

[nodes.Documentation]
text = """
## Installation

For now, if you want to try en, you must build it yourself.

In an environment with a |Rust toolchain|https://rustup.rs/ and Git installed, run:

`
git clone https://codeberg.org/jutty/en
cd en
cargo build --release
`

The en binary will be in `target/release/en`.

You can start it and point it to an address, port and graph:

`
en --host localhost --port 3003 --graph ./graph.toml
`

See |CLI| for defaults and details on the CLI options.

## Graph Syntax

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.

## Connections

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.
"""

[nodes.Node] # foo
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.

## Fields

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 title
- `text`: The textual content that is shown when the node is accessed
- `redirect`: Where to redirect any attempt to access the node
- `links`: An array of identifiers for other nodes to which this node is connected
- `hidden`: 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

## Example

`
[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"
`

### Default values

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 identifier
- `text`: An empty string (i.e. `text = ""`)
- `redirect`: An empty string
- `links`: An empty array (i.e. `links = []`)
- `hidden`: `false`
"""

[nodes.CLI]
title = "CLI Options"
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.

"""

[nodes.Syntax]
text= """

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|https://en.wikipedia.org/wiki/Markdown|, you'll find that some features familiar, with some notable differences too.

## Anchors

Anchors have the following basic syntax:

`
anchor|destination
`

For example:

`
DRC|DemocraticRepublicOfTheCongo
docs|https://en.jutty.dev/node/Documentation
`

As shown above, anchors can point to external addresses. These are identified by the presence of a `:` character in the destination. Otherwise, the anchor will point to a node with an ID matching the destination.

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|
`

### Trailing characters in anchors

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.
`

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.

### Node anchors

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|
`

And two words separated by a single anchor allow you to set a display text and destination:

`
particles|ParticlePhysics
`

This example will render as "particles|ParticlePhysics": the word particles pointing to a node with id `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.

## Formatting

Supported formatting syntax includes:

- `*` for bold
- `_` for italics
- `__` for underline
- `~~` for strikethrough

To apply these, you can wrap a word in the formatting operators, so for instance `*this*` will be rendered as *this* and `~~this~~` as ~~this~~.

## Paragraphs

A block of lines not separated by an empty line is always joined together. This means if you write:

`
a
b
c
`

You still get "a b c" as a result.

The exception to this are lists, which are explained below and must have their lines grouped together.

## Lists

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
`

Inside lists, you can use `[ ]` and `[x]`  to render checkboxes:

`
- [ ] not done
- [x] done
`

## Rendering unformatted text

The backtick character `\\`` can be used to render unformatted blocks and inline text:

`
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.
"""

[nodes.Escaping]
text = """
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: `\\\\\\\\`.

## Interactions with TOML escaping

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 newlines are also special in |TOML| syntax. For more details, see the |TOML documentation on Strings|https://toml.io/en/v1.1.0#string|.
"""

[nodes.AnchorSyntax]
title = "Anchor Syntax"
text = """
en'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:

- *Avoid special characters in your node IDs*: |TOML| allows you to use a wide range of characters in identifiers, but when writing your graph it's better keep your IDs simple
- When needed, use full three-pipe `|text|destination|` syntax to make your anchors fully unambiguous

## Punctuation in destinations

Consider 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:

`
, . : ; ? ! ( ) ' " ` | _ * \\
`

## Plural node anchors

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|!
`

## Spaced node anchors

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`.

## URL detection

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.

"""

[nodes.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.

## Motivation

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.

"""

links = [ "Graph" ]

[[nodes.en.connections]]
to = "TOML"
anchor = "TOML"

[nodes.Graph]
text = """
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.
"""

[nodes.TOML]
text = """
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.
"""

[nodes.Acknowledgments]
text = """
en is only possible thanks to a number of projects and people:

- |The Rust Programing Language|https://rust-lang.org/
- Tokio|https://tokio.rs/
- Axum|https://github.com/tokio-rs/axum
- Tera|https://keats.github.io/tera/
- Serde|https://serde.rs/ and the |toml crate|https://github.com/toml-rs/toml
"""

[nodes.Roadmap]
text = """
- [x] Setup tests
    - [ ] Improve content syntax parser coverage
- [x] Redirects
- [ ] Strip/render some syntax in Tree text preview
- [x] Drop-down navigation
- [ ] Meta-awareness
    - [ ] Detached edges
    - [ ] Most linked to nodes
    - [ ] Most linked from nodes
    - [ ] Most linked to nonexistent nodes
    - [ ] Most linked
- [ ] Special sections
    - [ ] Definition (implies metadata `has_definition`)
    - [ ] See also (implies a kind of connection, e.g. `related`)
    - [ ] Not to be confused with (implies a kind of connection)
    - [ ] Contrast with (implies a kind of connection)
    - [ ] Example (implies metadata `has_example`)
    - [ ] References/influences (implies metadata `has_references`)
- [ ] Sorting of tree, index list and drop-down navigation
    - [ ] Alphabetic
    - [ ] By most linked to
    - [ ] By most linked
- [x] Anchors and connections
    - [ ] Render detached anchors differently
    - [ ] Suffix-aware anchors
        - [x] Plural anchors (`|node|s` -> `node`)
        - [x] Ignore trailing punctuation
        - [ ] Conjugation anchors (`|will|ed` -> `will`)
        - [ ] Configurable suffixes
    - [x] Spaced node anchor (`|red fox|` -> `redfox` -> `RedFox`)
    - [ ] Automatic connections from anchors
    - [ ] `#` syntax for header ID anchors
    - [ ] Connection kinds
        - [ ] Mutual
        - [ ] Category <-> Membership
        - [ ] Opposite <-> Equivalent
        - [ ] Contrast <-> Similar
        - [ ] Cognate <-> Unrelated
        - [ ] Specialization <-> Generalization
        - [ ] Custom connection kinds
    - [x] External anchors
- [ ] Richer text formatting
    - [ ] Nested formatting
    - [x] Headers
    - [x] Preformatted blocks
    - [x] Oblique,
    - [x] Underline
    - [x] Strikethrough
    - [x] Bold
    - [x] Inline code
    - [x] Lists
        - [ ] Nested lists
    - [x] Checkboxes
        - [ ] Move this roadmap to en
- [ ] Full-text search
- [ ] Begin centralizing state
- [ ] Reduce O(n) calls in the formats module
- [ ] Alternative rendering modes
    - [ ] Render to filesystem
    - [ ] Single-page rendering
- [ ] Input formats
    - [ ] Multi-file graphs
    - [ ] Multi-graph
- [ ] Themes
- [x] Array syntax for lightweight connections
- [x] Automatic IDs
- [x] Automatic titles
- [x] Mismatch between TOML ID and provided ID
"""

[meta.config]
content_language = "en"
footer_credits = false
error_poem = true
node_selector = true
navbar_search = true
footer_text = """
made by jutty|https://jutty.dev • acknowledgments|Acknowledgments • |source code|https://codeberg.org/jutty/en
"""