README.md

Browse notes by tag

This example reads notes from a host folder and presents another view of them under mount/Notes. A note mentioning #work appears in Tags/work; notes without tags appear in Untagged. A note can appear under several tags without being copied or moved on disk.

1. Start the example

Use Node.js 22 or newer, pnpm 12.4 or newer within version 12, Rust, GNU Make, and a working Podman runtime. See the host requirements. Run these commands from the repository root in a macOS or Linux shell:

pnpm install --frozen-lockfile
make example EXAMPLE=notes

The command builds ScriptFS and mounts the example, building the runtime image on first use. Leave it running and open a second terminal at the repository root.

2. Explore the generated folders

cat examples/notes/mount/Notes/index.md
ls examples/notes/mount/Notes/Tags
ls examples/notes/mount/Notes/Tags/work
cat 'examples/notes/mount/Notes/Tags/work/projects - plan.md'
cat examples/notes/mount/Notes/Untagged/journal.md

The sample notes produce the tags errands, home, ideas, and work. projects/plan.md appears as projects - plan.md in a tag directory: the module flattens subfolder names so you can browse all notes for a tag in one place. journal.md has no tags and appears under Untagged.

Compare a generated note with its original in sample-notes. Both contain the same text. The index and tag directories are generated by the module; they do not exist in the notes folder.

3. Add a note on the host

The mounted view and the bound notes folder are read-only inside the container. Make changes in the host folder:

printf '# Reading list\n\nRead about filesystems. #learning #work\n' \
  > examples/notes/sample-notes/reading-list.md

The module caches its scan for two seconds. After that cache expires, browse the new tag and read the note:

cat examples/notes/mount/Notes/Tags/learning/reading-list.md
cat examples/notes/mount/Notes/index.md

The same note is also available under Tags/work. Remove the tutorial note from sample-notes when you are done:

rm examples/notes/sample-notes/reading-list.md

Its generated entries disappear after the next scan.

4. Use your own notes folder

In config.json, change modules.notes.paths.notes from "./sample-notes" to your notes directory and restart ScriptFS. Relative paths are resolved from this example directory. Removing the binding uses the manifest's default ~/Notes. To show your originals at the mount's root too, also change filesystems[0].source to that folder.

By default, the module includes .md and .txt files. To include only Markdown, merge this settings object into modules.notes:

{
  "settings": { "extensions": [".md"] }
}

The manifest declares a read-only notes host path at /notes in the container. module/index.mjs uses this.path("notes") to scan it, then builds the view with TreeModule. The Notes/** rule is opaque, so that subtree comes from the module. source: "./sample-notes" also exposes the original notes at the mount's root, alongside the generated Notes view.

5. Stop and test

Press Ctrl+C in the ScriptFS terminal to unmount. From the repository root:

make test-examples

The notes tests supply temporary notes and check tag grouping, subfolder names, read-only behavior, and changes picked up after the scan cache expires.