refactor: simplify getting-started-vault (3 types: Note/Topic/Person, no prefixes in filenames, Welcome as home)

This commit is contained in:
Test
2026-04-04 14:30:37 +02:00
parent f384b6fad3
commit aaa46f8d20
27 changed files with 311 additions and 370 deletions

View File

@@ -1,16 +1,3 @@
# Laputa app files (machine-specific, never commit)
.laputa/settings.json
# macOS
.DS_Store
.AppleDouble
.LSOverride
# Thumbnails
._*
# Editors
.vscode/
.idea/
*.swp
*.swo

View File

@@ -0,0 +1,89 @@
# CLAUDE.md — Laputa Vault Guide
This file explains how Laputa vaults work so you can create and edit notes correctly.
## Note structure
Every note is a markdown file with YAML frontmatter:
```yaml
---
title: My Note Title # required — do NOT use H1 in the body
is_a: TypeName # the note's type (must match a type file in the vault)
status: Active # example property
url: https://example.com # example property
belongs_to: "[[Other Note]]" # relationship via wikilink
related_to:
- "[[Note A]]"
- "[[Note B]]"
---
Body content in markdown. No H1 — the title is in the frontmatter.
```
**Key rules:**
- `title` is the note's display name — never use `# H1` in the body
- `is_a` must match the `title` of an existing type file
- Properties are any YAML key-value pairs in the frontmatter
- System properties are prefixed with `_` (e.g. `_pinned`, `_organized`, `_icon`) — don't show these to users
## Types
A type is a note with `is_a: Type` in the frontmatter. It lives in the vault root:
```yaml
---
title: Book
is_a: Type
_icon: BookOpen # Phosphor icon name
_color: "#8b5cf6" # hex color for sidebar
---
Description of the type.
```
To create a new type: create a markdown file with `is_a: Type`.
## Relationships
Relationships are frontmatter properties whose values are wikilinks:
```yaml
belongs_to: "[[Project Name]]"
related_to:
- "[[Note A]]"
- "[[Note B]]"
has:
- "[[Child Note]]"
```
Standard names: `belongs_to`, `related_to`, `has`. Custom names are allowed.
## Wikilinks
Syntax: `[[Note Title]]` or `[[filename]]`. Used for relationships and inline references.
## Views
Saved filters stored as `.view.json` in the `views/` folder:
```json
{
"title": "Active Notes",
"filters": [
{"property": "is_a", "operator": "equals", "value": "Note"},
{"property": "status", "operator": "equals", "value": "Active"}
],
"sort": {"property": "title", "direction": "asc"}
}
```
## What you can do on this vault
- Create/edit notes with correct frontmatter
- Create new type files
- Add or modify relationships between notes
- Create/edit views in `views/`
- Change `_icon` and `_color` on type files
- Edit `CLAUDE.md` (this file)
**Do not** modify app configuration files — those are local to each installation.

View File

@@ -0,0 +1,27 @@
---
title: AI and Git
is_a: Note
belongs_to: "[[Getting Started]]"
---
## Claude Code
Laputa integrates with [Claude Code](https://docs.anthropic.com/claude-code) — Anthropic's CLI agent. If you have `claude` installed, you can ask it to operate directly on your vault:
```
claude "Create a note for the book Zero to One by Peter Thiel, with a rating and a topic"
```
Claude understands Laputa's format (frontmatter, types, wikilinks, relationships) and creates or edits files accordingly. Your vault's `CLAUDE.md` file gives it full context.
## Git sync
Your vault is a Git repository. Every save in Laputa is tracked as a file change. Use the **Changes** view in the sidebar to see what's modified, commit with a message, and push to a remote.
```bash
# From inside your vault folder
git remote add origin https://github.com/you/my-vault.git
git push -u origin main
```
After that, Laputa can push and pull directly from the app.

View File

@@ -1,61 +1,6 @@
---
title: "Getting Started"
type: Note
Related to:
- "[[What is Laputa]]"
- "[[Keyboard Shortcuts]]"
- "[[Laputa Onboarding]]"
title: Getting Started
is_a: Topic
---
Welcome to your Laputa vault! This note walks you through the key features so you can start building your personal knowledge graph.
## Editor
Laputa uses a rich markdown editor. Write in plain markdown with headings, lists, checkboxes, code blocks, and blockquotes. Every note has YAML frontmatter at the top (between `---` delimiters) that stores metadata like type, status, and relationships.
Wiki-links connect notes together: type `[[` in the editor to search and link to any note in your vault.
## Types
Types define the kind of entity a note represents — Note, Project, Person, Topic, Task, or any custom type you create. Each type gets its own icon, color, and sidebar section. To create a new type, add a markdown file with `type: Type` in the frontmatter.
## Sidebar
The left sidebar organizes your vault by type. Each type gets its own collapsible section. Special sections include:
- **Inbox** — notes without a type
- **All Notes** — every note in the vault
- **Archive** — archived notes
- **Trash** — deleted notes (recoverable for 30 days)
## Properties
Open the **Inspector** panel (right side) to view and edit a note's properties. Click any value to change it. Use the **+ Add property** button to add custom fields. Properties containing `[[wiki-links]]` become navigable relationships.
## Relationships
Connect notes through frontmatter fields like `Belongs to`, `Related to`, and `Has`. These appear as clickable pills in the Inspector. Backlinks are computed automatically — linking A to B makes B show a backlink to A.
## Views
Views are saved filters that show a subset of your notes. Create a view to see, for example, all active projects or all tasks belonging to a specific project. Views live in the `views/` folder as YAML files. This vault includes an "Active Projects" view that filters for projects with status Active.
## Favorites
Pin frequently used notes to the Favorites section at the top of the sidebar. Toggle a note's favorite status from the Inspector or the command palette.
## Search
Press **Cmd+P** to quick-open any note by title. Use the search bar in the sidebar for full-text search across all notes.
## Command palette
Press **Cmd+K** to open the command palette. From here you can create notes, switch types, toggle views, and access every action in the app.
## AI
Laputa integrates with Claude Code. When Claude Code is running in your vault directory, the status bar shows a green badge. You can use AI to help organize, summarize, and connect your notes.
## Git sync
Your vault is a standard git repository. Use the **Changes** view in the sidebar to see modified files, commit changes, and push to a remote. This means your vault works with any git hosting service for backup and sync across devices.
This topic groups all the onboarding notes for Laputa. Start with [[Welcome to Laputa]] for an overview, then explore each note at your own pace.

View File

@@ -1,37 +0,0 @@
---
title: "Keyboard Shortcuts"
type: Note
Related to: "[[Getting Started]]"
---
Essential shortcuts for navigating Laputa.
## Navigation
| Shortcut | Action |
|----------|--------|
| **Cmd+P** | Quick-open a note by title |
| **Cmd+K** | Open the command palette |
| **Cmd+N** | Create a new note |
| **Cmd+,** | Open settings |
| **Cmd+\\** | Toggle sidebar |
## Editor
| Shortcut | Action |
|----------|--------|
| **Cmd+S** | Save the current note |
| **Cmd+B** | Bold |
| **Cmd+I** | Italic |
| **Cmd+Shift+K** | Insert a code block |
| **Cmd+Shift+8** | Toggle bullet list |
| **Cmd+Shift+7** | Toggle numbered list |
## Wiki-links
Type `[[` in the editor to open the link picker. Start typing to search for a note, then press Enter to insert the link. Links are bidirectional — the linked note will show a backlink to the current note.
## Tips
- Use **Cmd+K** when you are not sure where to find something — the command palette lists every available action.
- **Cmd+P** is the fastest way to navigate between notes — it searches by title and aliases.

View File

@@ -0,0 +1,12 @@
---
title: Luca Rossi
is_a: Person
role: Founder
website: https://refactoring.fm
twitter: https://twitter.com/lucaronin
related_to: "[[Getting Started]]"
---
Creator of Laputa and founder of [Refactoring](https://refactoring.fm), a newsletter about engineering leadership and software craft.
Luca built Laputa to organize his own knowledge — projects, people, and ideas — in a way that stays grounded in plain files and version control.

View File

@@ -1,9 +1,8 @@
---
title: "Note"
type: Type
icon: note
color: blue
order: 1
title: Note
is_a: Type
_icon: FileText
_color: "#6366f1"
---
A Note is a general-purpose document — research notes, meeting notes, ideas, drafts, or anything that doesn't fit a more specific type.
A Note is a general-purpose document — ideas, references, meeting notes, or anything that doesn't fit a more specific type.

View File

@@ -1,12 +0,0 @@
---
title: "Luca Rossi"
type: Person
Role: Founder
Website: https://refactoring.fm
Twitter: https://twitter.com/lucaronin
Related to:
- "[[Laputa Onboarding]]"
- "[[Topic: Personal Knowledge Management]]"
---
Creator of Laputa and founder of [Refactoring](https://refactoring.fm), a newsletter about engineering leadership and software craft. Luca built Laputa to organize his own knowledge — projects, people, ideas, and goals — in a way that stays grounded in plain files and version control.

View File

@@ -1,9 +1,8 @@
---
title: "Person"
type: Type
icon: user
color: green
order: 3
title: Person
is_a: Type
_icon: UserCircle
_color: "#f59e0b"
---
A Person represents someone you interact with — a colleague, collaborator, mentor, or friend. People can own projects, attend events, and appear in relationships across your vault.
A Person is someone you interact with — colleagues, collaborators, mentors, or friends.

View File

@@ -0,0 +1,8 @@
---
title: Personal Knowledge Management
is_a: Topic
---
Personal Knowledge Management (PKM) is the practice of collecting, organizing, and connecting the information you encounter — notes, ideas, references, and people — so it becomes a durable personal asset.
Laputa is designed as a PKM tool. Unlike traditional note-taking apps, it treats your notes as a graph of interconnected entities. Types give structure, wikilinks create connections, and views let you slice through the graph from different angles.

View File

@@ -1,27 +0,0 @@
---
title: "Laputa Onboarding"
type: Project
Status: Active
Owner: "[[Luca Rossi]]"
Has:
- "[[Task: Explore the Editor]]"
- "[[Task: Create Your First Type]]"
- "[[Task: Set Up Git Sync]]"
- "[[Task: Try the Command Palette]]"
- "[[Task: Create a Custom View]]"
Related to: "[[Topic: Getting Started]]"
---
A hands-on project to help you discover Laputa's key features. Work through the tasks below at your own pace — each one introduces a different part of the app.
## Tasks
- [ ] [[Task: Explore the Editor]] — Get comfortable with the markdown editor and wiki-links
- [ ] [[Task: Create Your First Type]] — Define a custom type with icon and color
- [ ] [[Task: Set Up Git Sync]] — Connect your vault to a git remote for backup
- [ ] [[Task: Try the Command Palette]] — Discover actions with Cmd+K
- [ ] [[Task: Create a Custom View]] — Build a filtered view of your notes
## When you are done
Once you have completed these tasks, you will have a solid understanding of how Laputa works. From here, start creating your own types, notes, and views to build a knowledge graph that fits your workflow.

View File

@@ -1,9 +0,0 @@
---
title: "Project"
type: Type
icon: rocket-launch
color: purple
order: 4
---
A Project is a time-bounded effort with a clear goal and an eventual completion date. Projects can contain tasks, belong to areas, and link to people and topics.

View File

@@ -0,0 +1,22 @@
---
title: Sidebar and Navigation
is_a: Note
belongs_to: "[[Getting Started]]"
---
## Main sections
- **Inbox** — notes you haven't organized yet. Once you've added relationships or toggled "organized", they leave the Inbox.
- **All Notes** — every note in your vault
- **Archive** — notes you've finished with but want to keep
- **Trash** — deleted notes, recoverable for 30 days
## Types section
Below the main sections, the sidebar lists your custom types (Note, Topic, Person, and any you create). Click a type to see all notes of that type.
Use the sliders icon next to **TYPES** to show or hide types from the sidebar. Use the **+** to create a new type.
## Favorites
Star any note to pin it to the top of the sidebar. Click the ⭐ icon in the breadcrumb bar at the top of the editor, or use **Cmd+K → Favorite**.

View File

@@ -1,39 +0,0 @@
---
title: "Task: Create a Custom View"
type: Task
Status: Open
Belongs to: "[[Laputa Onboarding]]"
Related to: "[[Laputa Onboarding]]"
---
Views are saved filters that show a subset of your notes. This vault includes an example view — "Active Projects" — that shows all projects with status Active.
## What to try
1. Open the command palette (Cmd+K) and look for a "New View" action, or create a `.yml` file in the `views/` folder
2. Define filters — for example, show all tasks with status Open
3. Set a name, icon, and color for the view
4. Save — the view appears in the sidebar under Views
## View format
Views are YAML files in `views/`. Here is an example:
```yaml
name: Open Tasks
icon: check-square
color: orange
sort: "modified:desc"
filters:
all:
- field: type
op: equals
value: Task
- field: Status
op: equals
value: Open
```
## Tip
Views update automatically as you add or change notes. They are a powerful way to create dashboards for your projects, areas, or any slice of your vault.

View File

@@ -1,30 +0,0 @@
---
title: "Task: Create Your First Type"
type: Task
Status: Open
Belongs to: "[[Laputa Onboarding]]"
---
Types give structure to your vault. Every note has a type — Project, Person, Topic, or any custom type you define.
## What to try
1. Create a new markdown file (Cmd+N)
2. In the frontmatter, set `type: Type`
3. Add an `icon:` field — use any [Phosphor icon](https://phosphoricons.com) name in kebab-case (e.g. `book-open`, `lightning`, `house`)
4. Add a `color:` field — available colors: red, purple, blue, green, yellow, orange
5. Give it a title with a `# Heading` and a short description in the body
6. Save the file — your new type appears in the sidebar
## Example
```yaml
---
type: Type
icon: book-open
color: red
order: 6
---
```
The `order` field controls position in the sidebar (lower = higher).

View File

@@ -1,21 +0,0 @@
---
title: "Task: Explore the Editor"
type: Task
Status: Open
Belongs to: "[[Laputa Onboarding]]"
---
Get comfortable with Laputa's markdown editor.
## What to try
1. **Headings** — Type `#`, `##`, or `###` followed by a space to create headings
2. **Lists** — Use `-` for bullet lists and `1.` for numbered lists
3. **Checkboxes** — Type `- [ ]` for a checkbox, click to toggle it
4. **Formatting** — Try **bold** (Cmd+B), *italic* (Cmd+I), and `inline code`
5. **Wiki-links** — Type `[[` and start typing a note name to insert a link. Try linking to [[Getting Started]]
6. **Code blocks** — Use triple backticks or Cmd+Shift+K
## Tip
The editor saves automatically. You can also press **Cmd+S** to save explicitly.

View File

@@ -1,27 +0,0 @@
---
title: "Task: Set Up Git Sync"
type: Task
Status: Open
Belongs to: "[[Laputa Onboarding]]"
---
Your vault is a git repository. Connecting it to a remote lets you back up your notes and sync across devices.
## What to try
1. Create a new repository on GitHub, GitLab, or any git host
2. Open a terminal in your vault directory
3. Add the remote: `git remote add origin <your-repo-url>`
4. Push your vault: `git push -u origin main`
## Using the Changes view
Laputa has a built-in Changes view in the sidebar that shows modified files. From there you can:
- See which files have changed since the last commit
- Commit changes with a message
- Push to the remote
## Tip
Git sync means you can edit your vault from any device — even a plain text editor on a computer that does not have Laputa installed. The next time you open Laputa, pull the latest changes and everything updates.

View File

@@ -1,26 +0,0 @@
---
title: "Task: Try the Command Palette"
type: Task
Status: Open
Belongs to: "[[Laputa Onboarding]]"
---
The command palette is the fastest way to do anything in Laputa.
## What to try
1. Press **Cmd+K** to open the command palette
2. Type to filter the list of available actions
3. Try these commands:
- **New Note** — create a note
- **Toggle Sidebar** — show or hide the sidebar
- **Open Settings** — jump to app settings
4. Press **Escape** to close the palette
## Quick open
**Cmd+P** opens a separate quick-open dialog that searches notes by title and aliases. Use it when you know which note you want to reach.
## Tip
If you forget a shortcut, Cmd+K shows it. The command palette lists keyboard shortcuts next to each action.

View File

@@ -1,9 +0,0 @@
---
title: "Task"
type: Type
icon: check-square
color: orange
order: 5
---
A Task is a discrete, actionable item that can be completed. Tasks belong to projects and represent the smallest unit of work in your vault.

View File

@@ -1,10 +0,0 @@
---
title: "Topic: Getting Started"
type: Topic
Related to:
- "[[Getting Started]]"
- "[[What is Laputa]]"
- "[[Keyboard Shortcuts]]"
---
This topic groups all notes related to learning Laputa. Start with [[Getting Started]] for a full overview, then explore [[What is Laputa]] for the philosophy behind the app and [[Keyboard Shortcuts]] for quick navigation.

View File

@@ -1,16 +0,0 @@
---
title: "Topic: Personal Knowledge Management"
type: Topic
Related to: "[[What is Laputa]]"
---
Personal Knowledge Management (PKM) is the practice of collecting, organizing, and connecting the information you encounter — notes, ideas, references, projects, and people — so it becomes a durable personal asset rather than a list of forgotten bookmarks.
Laputa is designed as a PKM tool. Unlike traditional note-taking apps, it treats your notes as a graph of interconnected entities. Types give structure, wiki-links create connections, and views let you slice through the graph from different angles.
## Core ideas
- **Write things down** — Capture ideas, meeting notes, and references as they happen. A note that exists is infinitely more useful than a thought you forgot.
- **Connect everything** — Use `[[wiki-links]]` to link related notes. Over time, these connections reveal patterns you did not plan.
- **Use types** — Give notes a type (Project, Person, Topic) to add structure without rigid hierarchies.
- **Review regularly** — Use views and favorites to surface what matters. A vault that is never revisited is just a graveyard of text files.

View File

@@ -1,9 +1,8 @@
---
title: "Topic"
type: Type
icon: tag
color: yellow
order: 2
title: Topic
is_a: Type
_icon: Hash
_color: "#10b981"
---
A Topic is a subject area or interest category. Topics group related notes, projects, and people by theme — use them to organize knowledge across your vault.
A Topic is a subject or area of interest that groups related notes together.

View File

@@ -0,0 +1,47 @@
---
title: Types, Properties and Relationships
is_a: Note
belongs_to: "[[Getting Started]]"
---
## Types
A **type** is a category for your notes — Person, Project, Topic, Book, or anything you invent. Each type gets its own icon, color, and section in the sidebar.
Create a type by adding a markdown file with `is_a: Type` in the frontmatter:
```yaml
---
title: Book
is_a: Type
_icon: BookOpen
_color: "#8b5cf6"
---
```
Then tag any note with `is_a: Book` to classify it as a book.
## Properties
Properties are any key-value pairs in the frontmatter:
```yaml
rating: 4
status: Active
url: https://example.com
```
They appear in the **Inspector** panel on the right. Click "+ Add property" to add one.
## Relationships
Relationships are properties whose values are wikilinks to other notes:
```yaml
belongs_to: "[[Some Project]]"
related_to:
- "[[Note A]]"
- "[[Note B]]"
```
Standard relationships: `belongs_to`, `related_to`, `has`. You can define your own.

View File

@@ -0,0 +1,38 @@
---
title: Using the Editor
is_a: Note
belongs_to: "[[Getting Started]]"
---
Laputa uses a rich markdown editor. Every note has two parts: **frontmatter** and **body**.
## Frontmatter
The YAML block at the top (between `---`) stores metadata:
```yaml
---
title: My Note
is_a: Note
status: Active
belongs_to: "[[Some Project]]"
---
```
- `title` — the note's display name (no H1 needed in the body)
- `is_a` — the type of the note
- Any other key becomes a property visible in the Inspector
## Body
Write in standard markdown: headings, lists, checkboxes, code blocks, bold, italic.
## Wikilinks
Type `[[` anywhere to search and link to another note:
```
See also [[What is Laputa]] for context.
```
Wikilinks create relationships between notes and power the graph view and backlinks panel.

View File

@@ -0,0 +1,23 @@
---
title: Views and Search
is_a: Note
belongs_to: "[[Getting Started]]"
---
## Search
Press **Cmd+P** to open the Quick Open palette and jump to any note by name.
Use the search bar in the sidebar to filter notes by text.
## Command Palette
Press **Cmd+K** to open the Command Palette — your shortcut to every action in Laputa: create a note, change a type, toggle a view, run a command.
## Views
Views are saved filters that show a subset of your vault. Create a view to answer questions like "all active projects" or "notes tagged design".
Click the **+** next to VIEWS in the sidebar to create a new view. Set filters by type, status, property value, or body content.
Views are saved as `.view.json` files in your vault's `views/` folder — they travel with your vault via Git.

View File

@@ -0,0 +1,19 @@
---
title: Welcome to Laputa
is_a: Note
belongs_to: "[[Getting Started]]"
_pinned: true
---
Welcome to Laputa — your personal knowledge base, stored as plain markdown files and versioned with Git.
Here's where to start:
- [[What is Laputa]] — the philosophy behind the app
- [[Using the Editor]] — markdown, wikilinks, and frontmatter
- [[Types, Properties and Relationships]] — how to structure your knowledge
- [[Views and Search]] — finding and filtering your notes
- [[Sidebar and Navigation]] — Inbox, All Notes, Favorites
- [[AI and Git]] — Claude Code integration and sync
**Luca Rossi** ([[Luca Rossi]]), the creator of Laputa, built it to organize his own knowledge — projects, people, and ideas — in a way that stays grounded in plain files you always own.

View File

@@ -1,25 +1,15 @@
---
title: "What is Laputa"
type: Note
Related to:
- "[[Getting Started]]"
- "[[Topic: Personal Knowledge Management]]"
title: What is Laputa
is_a: Note
belongs_to: "[[Getting Started]]"
---
Laputa is a local-first knowledge management app built on three principles:
Laputa is a personal knowledge base built on three principles:
## Your files, your data
**Plain files.** Every note is a markdown file on your filesystem. No proprietary database, no lock-in. You can open, edit, and search your notes with any text editor.
Every note is a plain markdown file on your filesystem. There is no proprietary database, no cloud lock-in, no import/export ceremony. Your vault is a folder — you can open it in any text editor, back it up however you want, and it will outlive any app.
**Git as sync.** Your vault is a Git repository. Version history, branching, and remote sync come for free. Use GitHub, GitLab, or any remote.
## The filesystem is the truth
**Structure without rigidity.** Notes have types, properties, and relationships — but they're just YAML frontmatter. The structure lives in the file, not in a schema.
Laputa reads your files and derives everything from them. Types, relationships, views, and sidebar sections are all computed from the frontmatter and folder structure. There is no hidden state. If you move a file in Finder, Laputa reflects the change. If you edit a file in VS Code, Laputa picks it up.
## Git for sync and history
Your vault is a git repository. Every change is a commit. Sync between devices by pushing and pulling to a remote. Resolve conflicts with standard git tools. Your entire edit history is preserved.
## How it fits together
A Laputa vault is a collection of markdown files with YAML frontmatter. The `type` field in the frontmatter determines what kind of entity the note represents. Wiki-links (`[[Note Title]]`) create a web of connections between notes. The app provides a visual interface on top of these files — a rich editor, sidebar navigation, inspector panel, and filtered views — but the files remain the source of truth.
Laputa is designed to grow with you. Start with a few notes, add types as patterns emerge, connect ideas with wikilinks. Over time, your vault becomes a map of how you think.