Skip to content

Projects#

FoldNotes has a lightweight, file-native project system. A project is a name (e.g. Marketing-Q4) that can be attached either to a whole note (via a body tag) or to individual tasks within any note (via inline task metadata). Both forms share one namespace — the same name Marketing-Q4 means the same thing whether it's a note tag or a task metadata field.

This page explains how projects work, where they live, and the tools for managing them.

Two Ways to Relate Notes to Projects#

Scope Syntax Use it when…
Whole note `#projects/<name>` — a hierarchical tag in the body The note is about a project (Project Hub, Status Update, Sprint Retro for a specific team, Kickoff).
Single task project:<name> — inline metadata on a task line One task in an unrelated note happens to belong to a project (a stray action item in a meeting note, a quick TODO in a daily log).

These are intentionally distinct. A meeting note can contain tasks for three different projects without itself being "about" any one of them:

# 1:1 with Alex
- [ ] Update marketing site project:Marketing-Q4
- [ ] Fix iOS crash project:Mobile-iOS
- [ ] Pick up groceries

The note has no `#projects/...` tag — it's just a meeting — but two tasks are queryable per project, and the third task stays free of project metadata. Conversely, a Marketing Q4 — Hub note tagged `#projects/Marketing-Q4` in the body declares the whole note's purpose.

Why not store the project in front matter?

A front matter field would force a 1:1 note-to-project model and create stale metadata when projects come and go. Body tags are part of the note's content, removable by editing, and queryable via the standard tag system. Front matter project: is deliberately not a thing — properties in FoldNotes describe whole-note facts that rarely change.

Creating a Project#

Four paths to bring a project into existence:

How Details
Type project:newName on a task line The lexer recognises it as task metadata. On save, FNProjectStore.ensureExists auto-registers the name. Ad-hoc — no UI confirmation.
/ → Project on a task line (Mac + iOS) Opens the project picker. "New Project…" is the first row; pick it, type a name, confirm. Deliberate — registers immediately in the registry.
Template with a Project parameter The user picks "New Project…" in the template's parameter form, and the new name is used for the substitution. Indirect registration via the resulting task line.
Type `#projects/<name>` in a note body Creates the body tag. The name appears in the tag helper autocomplete via the body-tag index. (For full registry behaviour — including showing it in pickers before any task uses it — pair this with one of the paths above, or use the Project Browser to confirm.)

Picking a Project#

When typing on a task line, press / and choose Project to open the picker. macOS shows a floating panel with arrow-key filtering; iOS shows an action sheet.

The picker autocompletes from the union of: - Stored registry (<collection>/.config/projects.json — explicit registrations) - Live task data (any task in the collection with project:<name> metadata)

Selecting an existing name inserts project:<name> at the cursor. The first row is always New Project… for adding a brand-new name without leaving the keyboard.

Tag helper autocomplete#

When typing `#projects/` in any body text, the standard tag helper autocompletes from every project FoldNotes knows about — including registered projects that haven't yet been used as a body tag anywhere. Useful for tagging a Project Hub note with a name you just registered via the picker, before any other body tag has used it.

Task Board — the Project Task Surface (macOS)#

The Task Board is the primary cross-note view for tasks. It's project-aware in three ways:

  • Group by Project — choose Project from the grouping control; the board becomes one column per project with cards for every task carrying that project: metadata. Empty-project tasks go into a "No Project" column.
  • Filter by Project — a project dropdown in the toolbar narrows the board to one project (or to all tasks with no project).
  • Drag between columns — when grouped by Project, dragging a card between columns updates the task's project: metadata in its source note.

This is where the dual model pays off — every task with project:<name> shows up here regardless of which note it lives in. The Task Board is currently macOS only; on iOS, use the Inspector ▸ Tasks tab per note or a saved query.

Project Browser (macOS)#

View ▸ Project Browser opens a window listing every registered project with its reference counts. Use it to see, rename, or remove projects.

Columns#

Column What it shows
Project Registry name
Notes How many notes carry `#projects/<name>` in their body
Tasks How many tasks (open + done) have project:<name> metadata
Status orphaned badge when both counts are zero

Orphans float to the top of the list so you can deal with them first.

  • All / Active / Orphaned / Archived segmented control narrows by reference count or archive state
  • Filter field narrows by name substring

Rename#

Click the pencil icon (or double-click a row). Type a new name and confirm. FoldNotes then:

  1. Walks every .md file in the collection
  2. Replaces `#projects/OldName` → `#projects/NewName` in body text (boundary-safe — won't match longer names like `#projects/OldNameButLonger`)
  3. Replaces project:OldName → project:NewName on task lines (same boundary safety)
  4. Renames the entry in the registry (projects.json)
  5. Shows a summary alert with the count of files modified and replacements made

Renames are atomic per file via NSFileCoordinator, so iCloud Drive sees them as normal note edits. Any open editor on a modified note should be closed before renaming (or, after rename, just reload the note) — the editor doesn't currently re-read from disk on a background change.

Renaming an archived project

Archived projects can be renamed, but FoldNotes shows a confirmation warning first. Renaming rewrites references throughout your collection — usually unnecessary for a project you've already archived. Consider unarchiving first if you genuinely want to revive the name.

Archive#

Archiving hides a project from the active picker without losing any history. Use it for projects that are finished or paused but whose notes and tasks you want to keep intact.

Click Archive in the toolbar (or Unarchive on a currently archived row) to toggle the state. Archived projects:

  • Are dimmed in the browser list with an archived badge in the Status column
  • Do not appear in the / → Project picker on task lines
  • Do not appear in the `#projects/` tag helper autocomplete
  • Still match existing tags and task metadata — notes already tagged with an archived project remain queryable
  • Are stored in the registry with an archived: true flag (in projects.json)

Use the Archived filter segment to see only archived projects, or All to see them mixed with active ones (archived rows sort to the bottom).

Delete#

The trash icon is enabled only when both reference counts are zero. This protects against stranded references — a project with notes or tasks pointing at it can't be deleted directly. To delete a project that still has references:

  1. Either remove the references manually, or rename the project first to consolidate
  2. Once counts hit zero, delete is enabled

Delete is registry-only — no file edits are needed since there are no references. The confirmation dialog explicitly notes when you're deleting an archived orphan, so you can be sure you're not throwing away a name you might still want.

Templates with Projects#

See Templates for the full reference. Summary:

  • Add a parameter of type Project to your template. The user picks a project from the dropdown when instantiating the template (autocompleting from the same source as the picker).
  • Task-level pattern — on individual task lines in the body, write project:{{paramName}}. Only those tasks get the project metadata; other tasks stay clean. Best for general templates (Meeting Notes, 1:1, Daily Standup) where tasks span projects.
  • Note-level pattern — turn on the Auto-tag checkbox on the parameter row. FoldNotes appends `#projects/<name>` to the body once at creation. Best for templates that are entirely about one project (Project Status, Sprint Retro for a named team, Kickoff).

The two patterns can be used independently or together.

iOS Differences#

Capability macOS iOS
Type project:name on a task — parsed by lexer
/ → Project picker on a task line floating panel action sheet
Autocomplete from registry + live task data
`#projects/` tag helper autocomplete
Use templates with Project parameters
Authoring templates with Project parameters
Task Board grouped/filtered by project (no Task Board on iOS)
Project Browser (manage registry, rename, delete)
Archive / unarchive a project
Archived projects hidden from picker + tag helper
Receive project renames via iCloud sync

iOS has full parity for using projects (typing, picking, viewing). Authoring (templates) and management (Project Browser) are macOS only by design. Rename operations performed on Mac propagate to iOS via iCloud sync of the modified note files and projects.json.

Tips#

Use hierarchical project names when scope matters

Projects can be deeper than one level — `#projects/Marketing/Q4` is a valid hierarchical tag, queryable via tag:projects/Marketing (matches everything under Marketing) or tag:projects/Marketing/Q4 (just Q4). The task metadata side stays flat: project:Marketing-Q4 — use a hyphen to avoid the path separator. The two conventions co-exist; pick whichever is more useful for your queries.

Project Hub note pattern

For projects with a lot of activity, create a single hub note tagged `#projects/<name>` with [[wiki-links]] to related notes. The Inspector ▸ References tab on the hub becomes a live, chronological index of every note that mentions or links to the hub.

Cleanup workflow

Every few weeks, open the Project Browser. Archive projects that are finished but whose history you want to preserve — they vanish from the picker and tag helper without losing their references. Delete only the true orphans (typos, abandoned codenames) where there's nothing left to keep.

Renaming safely

Save and close any open notes before renaming a project — FoldNotes' editor doesn't currently reload notes that are modified externally during editing. After rename, reopen any affected notes to see the updates.