Module notes 

Notes: a folder of Markdown files, read the way Obsidian reads a vault.

• Links between notes: [[wikilinks]] ([[note]], [[note#heading]], [[note|shown as]], found by name anywhere in the vault) and ordinary Markdown links ([text](../admin/letters.md#2), relative to the note).
• Links to everything else: mid: for a message (RFC 2392), sioul: for a task, an event, a contact, a draft (links), web addresses, files.
• Links that come back: every note that links to this one.
• Tags: #tag in the text, and tags: in the front matter.
• Front matter: the YAML block at the top, read for title, tags, aliases and links (task:, event:, mail: …).
• Checkboxes: - [ ] line, ready to become tasks.

The folder is yours (the notes folder, docs/notes-folder.md). Sioul reads it, and writes only the notes you write or make from it.

Structs

Checkbox

A checkbox line: - [ ] call the CAF.

Note

One note, as the index knows it.

NoteLink

A link found in a note.

Vault

Every note of a vault, with what links where.

Enums

NoteKind

What a file of the vault is: a Markdown note, or a picture, a PDF, a sound (an audio memo) kept beside the notes, read here and linked the same way.

Constants

FRONT_LINKS 🔒

Front matter keys whose values are links. case: housing, a project by its id alone, is how notes written before the name changed say it; a project: key is left alone, as many vaults use it for their own ends.

SKIPPED 🔒

Folders never read: tools’ own, and hidden ones.

Functions

add_front_link

The text with uri among its front matter’s links; the front matter is made when there is none. Everything else stays as written.

checkbox 🔒

- [ ] text, * [x] text, 1. [ ] text.

create

A new note in folder, its file named after name (free_path), holding text; the free name found and taken under the notes’ lock (with_lock): two writers making “Plan” at once make “Plan.md” and “Plan 2.md”, and neither is written over. Returns its path in the notes.

create_in

create, the lock in state.

decode

Percent-decoding, as links in Markdown write spaces (“my%20note.md”).

encode_path

Spaces and the few characters a URI cannot hold, percent-encoded; “/” and the letters of every language kept as they are (an IRI, RFC 3987), so that decode gives the same path back (“Santé/impôts.md”).

file_name

A file name for a new note from its title: the title itself, without what file systems refuse.

file_url

A file’s address for the window (a picture, a PDF): “file:///home/…”, and “file:///C:/Users/…” on Windows, with “/” between its parts and what an address cannot hold (“#”, “?”, “%”, spaces) percent-encoded.

folder_name 🔒

A folder’s name made safe on every system: no slash, nothing hidden.

free_path

A free path for a new note in folder: “Title.md”, else “Title 2.md”…

front_matter

The front matter: the lines between a first “—” and the next, read as simple YAML (key: value, key: [a, b], key: then - item lines). Returns it, and the line where the text starts.

image_size

A picture’s width and height from its first bytes: PNG, GIF, JPEG, WebP.

kind_of_file

The kind of a file by its extension; None for files the vault leaves out. Text notes are Markdown, whether named .md (Obsidian’s way) or .txt (Nextcloud Notes’ default, Markdown all the same).

links_in 🔒

Wikilinks and Markdown links in a line.

make_folder

A new folder in parent (“” for the top); returns its path.

new_text

A new note’s text: front matter with its links, a title, then the body.

normalize

“a/./b/../c.md” → “a/c.md”; None when it leaves the vault.

not_a_device 🔒

A name Windows keeps for a device (“CON”, “NUL”, “AUX”, “PRN”, “COM1”, “LPT1”…, whatever follows its first dot) taken out of its way with a “” before that dot: “Nul.md” would write to no file there, “aux.txt.md” too (“aux.txt.md” does not), and notes travel between systems.

path_of

The vault path of a note’s address, when it is one.

read

Reads one note’s text: its title, tags, links and checkboxes. Links are kept as written; Vault resolves those that point at notes.

relative 🔒

The path from a note’s folder to another note: “../admin/lease.md”.

remove_folder

An empty folder taken out; one holding anything stays, with why.

remove_front_link

The text without the front matter links same picks, and whether there were any. A link written in the text itself is left: it is the note’s words.

rename

A note renamed: its file gets name (its extension kept), in the same folder, and the notes that link to it follow: [[old]], ![[old.png]], Markdown links by path, sioul:note/ addresses. Returns its new path and the notes changed.

rename_folder

A folder renamed in place, its notes with it; the notes that name them by their path follow ([[folder/note]], Markdown links, sioul:note/ addresses). Returns its new path and each note moved, from and to.

tags_in 🔒

#tag and #nested/tag: after a space or at the start, not all digits, not a heading.

text_stem

A text note’s name without its extension: “letters.md” and “letters.txt” both give “letters”; any other name is given back as it is.

trash

Moves a note (or a picture, a PDF, a sound) into the vault’s .trash, as Obsidian does: out of sight, never lost. Returns where it went.

unquote 🔒

untrash

Puts back a note from the trash, where it was.

uri_of

A note’s address for links.

with_lock

One writer at a time among Sioul’s own writers of notes: the window and an agent (sioul mcp) each read a note again, change it and write it with this held, so that neither writes an older copy over the other’s change, and two new notes never take one name. An advisory lock (filelock) on one hidden file of Sioul’s state folder (.notes.lock), not one beside each note: the notes folder is yours, and a sync app or another editor would carry or show a lock file in each of its folders.

with_lock_in

with_lock, its lock in state (the tests’ own folder).

without_code 🔒

A line with its inline code blanked, so links and tags inside are not taken.

write

Writes a note next to its place, then moves it in.

yaml_value 🔒

A YAML scalar, quoted when it would not read back as written; on one line, as a line break would start another key of the front matter.