Files

A Markdown File

Notes are written using Markdown files (GitHub Flavored Markdown is supported).

notes.md

# My Notebook

A file is a Markdown document structured using headings.

## Notes

### Note: Example

Only headings starting with a known prefix such as `Note:` or `Flashcard:` are
considered as notes and processed by _The NoteWriter_.

### Note: Another Example

Notes can use **Markdown syntax** such as code blocks, quotes, images, tables.

A YAML Front Matter can also present at the top of a file to declare common attributes:

review.md

---
draft: true
---

# Note: My Review

It's a book containing pages.

Many Markdown Files

You can organize your Markdown files using a tree structure. Check the directory examples/ to have a better idea of what a note repository could look like.

Ignore Markdown Files

You may want to exclude some files from being parsed by The NoteWriter. Two solutions exist:

• Use the special tag ignore:

ignore.md

---
tags: ignore
---

This file will be ignored when adding files using `nt add`.

• Exclude files by declaring glob patterns inside a file .ntignore present at the root of your repository:

/archives/**/*.md  # Any Markdown file under archives/
                   # will be ignored

Tip

• Use Markdown files as notebooks. Group your notes inside a file like you would group them in a physical notebook.
• Use standard Markdown headings to group similar notes under the same section.
• Use special Markdown headings to define the notes that will be parsed by The NoteWriter.
• Ignore files that must not be processed.

Working with Files

After editing your Markdown files, you will use the command nt add to add them to The NoteWriter. This command parses your files and extracts different objects, covered in the following pages, and make them accessible in the desktop application.

$ echo "# My Notes" > nodes.md
$ nt add .
# The file is now visible in the desktop application

When using remotes to push your notes (ex: to your phone), only committed objects will be pushed.

$ nt commit
# Objects can now be pushed
$ nt push phone # Expect a remote "phone" to have been declared

In practice, you will use the command nt along the command git and will add/commit your changes at the same time.

Under the hood

The NoteWriter design was inspired by Git internals. When adding files with Git, the command git add traverses the working directory to find updates to extract a diff that is stored in the directory .git/objects.

Running nt add also traverses the working directory to find updated Markdown files to parse. For every file, The Notewriter creates a new object:

$ echo "# My Notes" > nodes.md

$ git add .
$ tree .git/
.git
├── HEAD
├── config
├── index
├── objects
│   ├── fa
│   │   └── 47a5e460cc48457b1bfafacc2c78f533200e8d
│   ├── info
│   └── pack
└── refs
    ├── heads
    └── tags

$ nt add .
$ tree .nt/
.nt
├── config.jsonnet
├── database.db
├── index
├── nt.libsonnet
└── objects
    └── d2
        └── d2810d9388293838c8edac1654ecb2bb440f4237.pack

Both Git and The NoteWriter needs to determine if a file has been edited. Both use a file index to determine the last known object ID (OID) and a timestamp when the file was last updated.

Extracted objects are stored into the directory objects/:

$ cat .nt/objects/d2/d2810d9388293838c8edac1654ecb2bb440f4237.pack
oid: d2810d9388293838c8edac1654ecb2bb440f4237
file_relative_path: notes.md
file_mtime: 2026-01-01T14:46:46.176291231+01:00
file_size: 11
ctime: 2026-01-01T14:48:00.339699+01:00
kind: objects
objects:
    - oid: 76913e4a281449efa5eade3702a0cda25434f3b6
      kind: file
      ctime: 2025-12-24T14:46:46.176291231+01:00
      desc: file "notes.md" [76913e4a281449efa5eade3702a0cda25434f3b6]

The design of The NoteWriter was inspired by Git but not the implementation. Git has different requirements such as working with large mono-repositories with millions of files. Performance is not as important when processing hundreds of note files. For example, Git index is an optimized binary file when The NoteWriter index is a YAML human-redable file easier to debug:

$ cat .nt/index
entries:
    - relative_path: notes.md
      kind: objects
      staged: true
      staged_packfile_oid: d2810d9388293838c8edac1654ecb2bb440f4237
      staged_mtime: 2026-01-01T14:46:46.176291231+01:00
      staged_itime: 2026-01-01T14:48:00.34468+01:00
      staged_size: 11
objects:
    - oid: 76913e4a281449efa5eade3702a0cda25434f3b6
      kind: file
      packfile_oid: d2810d9388293838c8edac1654ecb2bb440f4237

The file index contains also the staging area.

Unlike Git, The NoteWriter stores objects into a second database, the SQLite file .nt/database.db, which is used extensively by The NoteWriter Desktop.

On this example, the file notes.md has been staged but still not committed:

$ nt commit
$ cat .nt/index
entries:
    - relative_path: notes.md
      kind: objects
      packfile_oid: d2810d9388293838c8edac1654ecb2bb440f4237
      mtime: 2026-01-01T14:46:46.176291231+01:00
      itime: 2026-01-01T14:48:00.34468+01:00
      size: 11
objects:
    - oid: 76913e4a281449efa5eade3702a0cda25434f3b6
      kind: file
      packfile_oid: d2810d9388293838c8edac1654ecb2bb440f4237

The index has been updated to mark all staged objects as committed and reasy to be pushed.

Useful Commands

• Use nt add <path> to add files or directories in the index. Notes inside these files will be processed and accessible in The NoteWriter Desktop.
• Use nt commit to commit staged files. Notes inside these files could then be pushed using nt push.