From aaa46f8d20a6c6efeccafe435992aafc7c2a9642 Mon Sep 17 00:00:00 2001 From: Test Date: Sat, 4 Apr 2026 14:30:37 +0200 Subject: [PATCH] refactor: simplify getting-started-vault (3 types: Note/Topic/Person, no prefixes in filenames, Welcome as home) --- getting-started-vault/.gitignore | 13 --- getting-started-vault/CLAUDE.md | 89 +++++++++++++++++++ getting-started-vault/ai-and-git.md | 27 ++++++ getting-started-vault/getting-started.md | 61 +------------ getting-started-vault/keyboard-shortcuts.md | 37 -------- getting-started-vault/luca-rossi.md | 12 +++ getting-started-vault/note.md | 11 ++- getting-started-vault/person-luca-rossi.md | 12 --- getting-started-vault/person.md | 11 ++- .../personal-knowledge-management.md | 8 ++ .../project-laputa-onboarding.md | 27 ------ getting-started-vault/project.md | 9 -- .../sidebar-and-navigation.md | 22 +++++ .../task-create-a-custom-view.md | 39 -------- .../task-create-your-first-type.md | 30 ------- .../task-explore-the-editor.md | 21 ----- getting-started-vault/task-set-up-git-sync.md | 27 ------ .../task-try-the-command-palette.md | 26 ------ getting-started-vault/task.md | 9 -- .../topic-getting-started.md | 10 --- .../topic-personal-knowledge-management.md | 16 ---- getting-started-vault/topic.md | 11 ++- .../types-properties-relationships.md | 47 ++++++++++ getting-started-vault/using-the-editor.md | 38 ++++++++ getting-started-vault/views-and-search.md | 23 +++++ getting-started-vault/welcome.md | 19 ++++ getting-started-vault/what-is-laputa.md | 26 ++---- 27 files changed, 311 insertions(+), 370 deletions(-) create mode 100644 getting-started-vault/CLAUDE.md create mode 100644 getting-started-vault/ai-and-git.md delete mode 100644 getting-started-vault/keyboard-shortcuts.md create mode 100644 getting-started-vault/luca-rossi.md delete mode 100644 getting-started-vault/person-luca-rossi.md create mode 100644 getting-started-vault/personal-knowledge-management.md delete mode 100644 getting-started-vault/project-laputa-onboarding.md delete mode 100644 getting-started-vault/project.md create mode 100644 getting-started-vault/sidebar-and-navigation.md delete mode 100644 getting-started-vault/task-create-a-custom-view.md delete mode 100644 getting-started-vault/task-create-your-first-type.md delete mode 100644 getting-started-vault/task-explore-the-editor.md delete mode 100644 getting-started-vault/task-set-up-git-sync.md delete mode 100644 getting-started-vault/task-try-the-command-palette.md delete mode 100644 getting-started-vault/task.md delete mode 100644 getting-started-vault/topic-getting-started.md delete mode 100644 getting-started-vault/topic-personal-knowledge-management.md create mode 100644 getting-started-vault/types-properties-relationships.md create mode 100644 getting-started-vault/using-the-editor.md create mode 100644 getting-started-vault/views-and-search.md create mode 100644 getting-started-vault/welcome.md diff --git a/getting-started-vault/.gitignore b/getting-started-vault/.gitignore index 4b8e0699..482e34b1 100644 --- a/getting-started-vault/.gitignore +++ b/getting-started-vault/.gitignore @@ -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 diff --git a/getting-started-vault/CLAUDE.md b/getting-started-vault/CLAUDE.md new file mode 100644 index 00000000..d55599de --- /dev/null +++ b/getting-started-vault/CLAUDE.md @@ -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. diff --git a/getting-started-vault/ai-and-git.md b/getting-started-vault/ai-and-git.md new file mode 100644 index 00000000..b6fc48a9 --- /dev/null +++ b/getting-started-vault/ai-and-git.md @@ -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. diff --git a/getting-started-vault/getting-started.md b/getting-started-vault/getting-started.md index 05d3602b..2a1debbb 100644 --- a/getting-started-vault/getting-started.md +++ b/getting-started-vault/getting-started.md @@ -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. diff --git a/getting-started-vault/keyboard-shortcuts.md b/getting-started-vault/keyboard-shortcuts.md deleted file mode 100644 index d2226e6b..00000000 --- a/getting-started-vault/keyboard-shortcuts.md +++ /dev/null @@ -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. diff --git a/getting-started-vault/luca-rossi.md b/getting-started-vault/luca-rossi.md new file mode 100644 index 00000000..ca456e03 --- /dev/null +++ b/getting-started-vault/luca-rossi.md @@ -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. diff --git a/getting-started-vault/note.md b/getting-started-vault/note.md index 5937602e..a7d9303f 100644 --- a/getting-started-vault/note.md +++ b/getting-started-vault/note.md @@ -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. diff --git a/getting-started-vault/person-luca-rossi.md b/getting-started-vault/person-luca-rossi.md deleted file mode 100644 index b9b38a0a..00000000 --- a/getting-started-vault/person-luca-rossi.md +++ /dev/null @@ -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. diff --git a/getting-started-vault/person.md b/getting-started-vault/person.md index 7f1eaa62..87ad702f 100644 --- a/getting-started-vault/person.md +++ b/getting-started-vault/person.md @@ -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. diff --git a/getting-started-vault/personal-knowledge-management.md b/getting-started-vault/personal-knowledge-management.md new file mode 100644 index 00000000..cb2258dc --- /dev/null +++ b/getting-started-vault/personal-knowledge-management.md @@ -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. diff --git a/getting-started-vault/project-laputa-onboarding.md b/getting-started-vault/project-laputa-onboarding.md deleted file mode 100644 index 65d4680b..00000000 --- a/getting-started-vault/project-laputa-onboarding.md +++ /dev/null @@ -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. diff --git a/getting-started-vault/project.md b/getting-started-vault/project.md deleted file mode 100644 index 70e47154..00000000 --- a/getting-started-vault/project.md +++ /dev/null @@ -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. diff --git a/getting-started-vault/sidebar-and-navigation.md b/getting-started-vault/sidebar-and-navigation.md new file mode 100644 index 00000000..0f98dba9 --- /dev/null +++ b/getting-started-vault/sidebar-and-navigation.md @@ -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**. diff --git a/getting-started-vault/task-create-a-custom-view.md b/getting-started-vault/task-create-a-custom-view.md deleted file mode 100644 index 04ad3876..00000000 --- a/getting-started-vault/task-create-a-custom-view.md +++ /dev/null @@ -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. diff --git a/getting-started-vault/task-create-your-first-type.md b/getting-started-vault/task-create-your-first-type.md deleted file mode 100644 index bee2bae1..00000000 --- a/getting-started-vault/task-create-your-first-type.md +++ /dev/null @@ -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). diff --git a/getting-started-vault/task-explore-the-editor.md b/getting-started-vault/task-explore-the-editor.md deleted file mode 100644 index 194faaf0..00000000 --- a/getting-started-vault/task-explore-the-editor.md +++ /dev/null @@ -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. diff --git a/getting-started-vault/task-set-up-git-sync.md b/getting-started-vault/task-set-up-git-sync.md deleted file mode 100644 index c51c4229..00000000 --- a/getting-started-vault/task-set-up-git-sync.md +++ /dev/null @@ -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 ` -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. diff --git a/getting-started-vault/task-try-the-command-palette.md b/getting-started-vault/task-try-the-command-palette.md deleted file mode 100644 index 1224dc82..00000000 --- a/getting-started-vault/task-try-the-command-palette.md +++ /dev/null @@ -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. diff --git a/getting-started-vault/task.md b/getting-started-vault/task.md deleted file mode 100644 index f5caad82..00000000 --- a/getting-started-vault/task.md +++ /dev/null @@ -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. diff --git a/getting-started-vault/topic-getting-started.md b/getting-started-vault/topic-getting-started.md deleted file mode 100644 index ff3e3dcf..00000000 --- a/getting-started-vault/topic-getting-started.md +++ /dev/null @@ -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. diff --git a/getting-started-vault/topic-personal-knowledge-management.md b/getting-started-vault/topic-personal-knowledge-management.md deleted file mode 100644 index e4a13895..00000000 --- a/getting-started-vault/topic-personal-knowledge-management.md +++ /dev/null @@ -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. diff --git a/getting-started-vault/topic.md b/getting-started-vault/topic.md index acc5c6ff..c455581f 100644 --- a/getting-started-vault/topic.md +++ b/getting-started-vault/topic.md @@ -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. diff --git a/getting-started-vault/types-properties-relationships.md b/getting-started-vault/types-properties-relationships.md new file mode 100644 index 00000000..1d40746f --- /dev/null +++ b/getting-started-vault/types-properties-relationships.md @@ -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. diff --git a/getting-started-vault/using-the-editor.md b/getting-started-vault/using-the-editor.md new file mode 100644 index 00000000..87a851c8 --- /dev/null +++ b/getting-started-vault/using-the-editor.md @@ -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. diff --git a/getting-started-vault/views-and-search.md b/getting-started-vault/views-and-search.md new file mode 100644 index 00000000..de2f1033 --- /dev/null +++ b/getting-started-vault/views-and-search.md @@ -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. diff --git a/getting-started-vault/welcome.md b/getting-started-vault/welcome.md new file mode 100644 index 00000000..263231d5 --- /dev/null +++ b/getting-started-vault/welcome.md @@ -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. diff --git a/getting-started-vault/what-is-laputa.md b/getting-started-vault/what-is-laputa.md index a1c765fe..803d4a9b 100644 --- a/getting-started-vault/what-is-laputa.md +++ b/getting-started-vault/what-is-laputa.md @@ -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.