docs: update

public/docs.md

@@ -2,6 +2,7 @@
 title: mdzk documentation
 ---
 
+
 This document will go through how mdzk operates and how you can use it in your workflows. Currently, it is quite limited, as mdzk is still under heavy development. If you have any suggestions to things that should be added, [open an issue on our GitHub](https://github.com/mdzk-rs/mdzk/issues/new) describing it and mark it with the `documentation` label. Any contributions are of course welcome.
 
 ---
@@ -38,19 +39,24 @@ An mdzk binary for your system will now be available in `./target/release`.
 
 # Core concepts
 
-At it's core, mdzk operates on a *vault* with *notes* containing optional *internal links*. Let's unpack these terms:
+At it's core, mdzk creates a *vault* of *notes* containing *arcs*. Let's unpack these terms:
+
+- A **vault** is a [simple directed graph](https://en.wikipedia.org/wiki/Directed_graph).
+- **Notes** are the vertices in a vault.
+- An **arc** is a directed edge connecting two notes.
+
+## Vault
 
-- A **vault** is a [directed graph](https://en.wikipedia.org/wiki/Directed_graph).
-- **Notes** are the nodes in a vault.
-- **Internal links** create edges connecting each note.
+Mathematically we can define a vault as the tuple $V = (N, A)$, where
 
-In the filesystem, a vault is represented by directory, the notes being Markdown-files. mdzk takes a directory as input, recursively finds any Markdown-files in it and loads each of them as a node in the graph. It then parses every file and establishes edges between the nodes based on the links contained in it.
+- $N = \{n_i\}$ is a set of [notes](#note);
+- $A \subseteq \{(n_i, n_j)$ where $(n_i, n_j)\in N^2\}$ is a set of [arcs](#arc).[^arcs-def]
 
-The *vault* data structure is a very efficient and useful concept in dealing with notes and their relation together. mdzk models a vault as an [adjacency matrix](https://mathworld.wolfram.com/AdjacencyMatrix.html) and does custom hashing on each note to obtain unique note IDs. This means that we get incredibly fast lookups on note adjacencies.
+mdzk represents a vault in memory as an [adjacency matrix](https://mathworld.wolfram.com/AdjacencyMatrix.html). This gives us very fast lookup times on arcs, and simplifies finding inversed arcs (backlinks).
 
-## Vaults
+[^arcs-def]: Note that this definition allows loops, meaning notes can link to themselves. This does not provide any real practical benefits, but it simplifies how we model the vault and gives some flexibility in linkage.
 
-As a user, you can think of a vault simply as a directory with a bunch of Markdown-files. You may structure this directory however you want and include any other filetypes - mdzk does not care. The major difference to keep in mind, is that a vault does not include the notion of any hierarchy. You may bury a note in a subdirectory of a subdirectory of a subdirectory if you want, mdzk will still handle it the same way as a note placed in the root.
+In the filesystem, a vault is simply a directory with a bunch of Markdown files. You may structure this directory however you want and include any other filetypes - mdzk does not care. Something to keep in mind: mdzk does not have any notion of a directory hierarchy. You may bury a note in a subdirectory of a subdirectory of a subdirectory if you want, mdzk will still handle it the same way as a note placed in the root.
 
 Consider the vault with the following tree:
 
@@ -68,11 +74,15 @@ Producing a visualization of this vault, might look like this:
 <!-- Using http://bl.ocks.org/rkirsling/5001347 to produce illustrative graphs atm. -->
 ![](images/vaults_01.png){ width=50% }
 
-As you can see, the paths were totally ignored; *[internal links](#internal-links) are the only constructs that define the vault structure*. The filepaths are still stored as metadata, so custom workflows using directory hierarchies can still be made if one wants.
+As you can see, the paths were totally ignored; *[arcs](#arc) define the vault structure, not filepaths*. Paths are still stored as metadata, so custom workflows using directory hierarchies can still be made if one wants.
 
-## Notes
+## Note
 
-## Internal links
+A note is a single Markdown file. mdzk adheres to [CommonMark](https://commonmark.org/), so I strongly recommend you check out [this quick guide](https://commonmark.org/help/) to get the gist of the syntax. Additionally, there is support for [tables](https://github.github.com/gfm/#tables-extension-), [task lists](https://github.github.com/gfm/#task-list-items-extension-), [strikethrough](https://github.github.com/gfm/#strikethrough-extension-) and [footnotes](https://talk.commonmark.org/t/how-should-footnotes-behave/1106).
+
+## Arc
+
+An arc is created by writing a [wiki-style](https://www.mediawiki.org/wiki/Help:Links#Internal_links) link inside a note, namely by surrounding a note identifier by double square brackets like this: `[[link to a note]]`. The note identifier can be both the title of a note or it's filename.
 
 
 ---
@@ -106,16 +116,18 @@ As you can see, the paths were totally ignored; *[internal links](#internal-link
 
       // The content of the note. All internal links are
       // converted to CommonMark and the front matter
-      // is stripped.
+      // is stripped
       "content": string,
 
-      // A set of note IDs, each representing an
-      // outgoing internal link
-      "links": [string],
-
-      // A set of note IDs, each representing an
-      // incoming internal link
-      "backlinks": [string]
+      "arcs": {
+          // An array of note IDs that are the
+          // destination of an arc starting at the
+          // current note
+          "outgoing": [string],
+          // An array of note IDs where the current
+          // note is the destination
+          "incoming": [string]
+      },
     }
   ],
   // Not yet implemented: "tags": []