# Terra

> A local library for your files, sheets, PDFs, books and web pages, using Markdown as data.

Terra is a local-first Mac app. A Library is a folder of Markdown files you own; Terra indexes it and adds databases, boards, a reader, canvases, tasks and an assistant on top. Each guide link below is the plain Markdown of one docs page. Quick answers are short how-tos from the in-app help; their links are web pages, and their text is in llms-full.txt.

## Get started

- [Get started with Terra](https://terramd.io/docs/quickstart.md): Install Terra, open a Library, then write, format, link, tag and find your first notes. About fifteen minutes from download to a working Library.
- [Find your way around](https://terramd.io/docs/find-your-way-around.md): A map of the Terra window, from the toolbar, sidebar and note list to tabs, split panes, peeks, drawers, the shelf, Zen mode and the terminal.
- [Bring in your notes from another app](https://terramd.io/docs/bring-in-your-notes.md): Move your notes into Terra from Obsidian, Notion, Bear, Evernote, Roam, a Markdown folder or a reference manager, or open an existing folder as it is.
- [Sync and back up your Library](https://terramd.io/docs/sync-and-back-up.md): Your notes are ordinary files, so any backup or sync tool works. Use Time Machine, a cloud folder or Terra's Versions, and know what each covers.

## Files and folders

- [Libraries](https://terramd.io/docs/libraries.md): A Library is a folder on your Mac that Terra treats as one workspace. Open, create and switch Libraries, and see what each one keeps.
- [Files and folders](https://terramd.io/docs/files-and-folders.md): Every note is a Markdown file and every folder is a real folder in your Library. Create, rename, move, duplicate, delete and restore them.
- [Accepted file formats](https://terramd.io/docs/file-formats.md): Which files Terra opens and how: Markdown notes, PDFs, EPUB books, images, spreadsheets, web pages, and anything else as an attachment.
- [How Terra stores your notes](https://terramd.io/docs/how-terra-stores-your-notes.md): Every note is a plain Markdown file with a short YAML header. See what Terra writes, where attachments and sidecars go, and what's safe to edit elsewhere.

## Writing and formatting

- [Basic formatting syntax](https://terramd.io/docs/formatting-syntax.md): The Markdown you type in Terra for headings, bold and italic, highlights, links, images, quotes, lists, to-dos and code, with the shortcut for each.
- [Advanced formatting](https://terramd.io/docs/advanced-formatting.md): Tables that add themselves up, math, code you can run, Mermaid diagrams, embeds, columns, tabs, toggles, comments and dates, plus everything in the slash menu.
- [Sprouts](https://terramd.io/docs/sprouts.md): Coloured blocks that hold other blocks, like tips, warnings and decisions, with their own properties, and every one in your Library on a single board.
- [Links and backlinks](https://terramd.io/docs/links-and-backlinks.md): Link notes with wiki-links, point at one paragraph with a block link, add web links, and see every note that links back to the one you're in.
- [Properties](https://terramd.io/docs/properties.md): Structured fields at the top of a note, like a status or a start date, saved as YAML frontmatter that databases can sort, filter and group.
- [Tags](https://terramd.io/docs/tags.md): Label notes with #tags in the text or in the tags property, nest and colour them, and find every note that carries one.
- [Templates](https://terramd.io/docs/templates.md): Start notes with your headings, tags and properties already in place, fill in placeholders like the date, and make templates of your own.

## Databases

- [Databases](https://terramd.io/docs/databases.md): A database is a live collection of the notes that match its conditions. Each note is a row, its properties are the columns, and nothing is copied.
- [Views and layouts](https://terramd.io/docs/views-and-layouts.md): A view is a saved way to look at a database, with its own layout, filters, sort, grouping and visible properties. Terra has twelve layouts.
- [Filter, sort and group](https://terramd.io/docs/filter-sort-and-group.md): Narrow a view to the notes you need, put them in order, and group them into sections or board columns. Every filter test, by property type.
- [Formulas, threads and gathers](https://terramd.io/docs/formulas-threads-and-gathers.md): Computed properties for your databases. Formulas calculate a value for each note, threads link notes to other notes, and gathers roll values up across a thread.
- [Queries](https://terramd.io/docs/queries.md): Ask your Library questions in SQL. Write a read-only SELECT over Terra's public views, see the answer as a table, a sheet or a chart, and save it.

## Tasks and calendar

- [Tasks](https://terramd.io/docs/tasks.md): A task is a checkbox line in any note. Terra gathers every task into Tasks, a board where you set due dates, change status and track progress.
- [Calendar](https://terramd.io/docs/calendar.md): The Calendar lays your Library out by date. Meetings appear by their start time and tasks by their due date, and dragging one reschedules it.

## Reading and research

- [Read comfortably in the e-reader](https://terramd.io/docs/read-in-the-e-reader.md): Add EPUBs, PDFs and images to your Library, then read with your own theme, font and layout. Terra remembers your place in every book.
- [Highlight, annotate and keep every mark](https://terramd.io/docs/annotate-in-the-sidecar.md): Highlight books in six colours, add notes and tags, find any passage again in seconds and export it all to a note. Your annotations live in a plain file beside the book.
- [Build a research library](https://terramd.io/docs/research-library.md): Gather papers, books, PDFs and web pages as notes, cite them as you write with a reference list that builds itself, and see who cites what.

## Capture and AI

- [Capture anything, and let Terra sort it for you](https://terramd.io/docs/capture-and-classify.md): Grab thoughts, links and messages from any app with Quick capture, then let enrichment tidy them into a template and the Jev classifier fill in your own categories.
- [Get answers from your own notes](https://terramd.io/docs/ask-your-library.md): Ask questions in plain language and get answers that cite your notes. Let the assistant write for you, with every edit reviewable.

## Workspace

- [Find anything in your Library](https://terramd.io/docs/power-search.md): Track down a decision, a phrase or a whole quarter's notes. Learn the three ways to look, build precise searches and get answers from ⌘K.
- [Think visually with canvas and mind maps](https://terramd.io/docs/canvas-and-mind-maps.md): Brainstorm on an endless canvas with sticky notes, shapes, arrows and mind maps beside your real notes, then turn the best ideas into notes.
- [Make Terra yours](https://terramd.io/docs/make-terra-yours.md): Choose light or dark, a theme and fonts, put your own buttons on the toolbar and your own keys on commands, tidy the sidebar, and give one note its own page.

## Guides

- [Run a project with boards, timelines and burndowns](https://terramd.io/docs/project-suite.md): Track a project's work as notes, then see it as a kanban board, a Gantt-style timeline, progress charts and a dashboard — plus an honest recipe for a burndown.
- [Run your week with tasks and the calendar](https://terramd.io/docs/run-your-week-with-tasks.md): A weekly routine in Terra: capture tasks in your notes, triage them on one board, plan the week on the Calendar and close it out on Friday.
- [Take meeting notes that turn into tasks](https://terramd.io/docs/meeting-notes.md): Start meetings from the Meeting template, write action items with owners and dates, and follow them up on the Tasks board and the Calendar.
- [Build a dashboard for anything](https://terramd.io/docs/dashboards.md): Put live views of your databases on one page: big numbers with a trend, charts, boards and tables for a project, a reading list or a habit.

## Reference

- [Keyboard shortcuts](https://terramd.io/docs/keyboard-shortcuts.md): Every default shortcut in Terra, grouped the way Settings › Hotkeys groups them, and how to change, reset or remove one.
- [Search syntax](https://terramd.io/docs/search-syntax.md): Every operator and filter the search window understands, with an example of each, plus the rules for dates, patterns and the errors you might see.
- [Task syntax](https://terramd.io/docs/task-syntax.md): Exactly what Terra reads as a task: list markers, status characters, the ::: property list, dates, priorities and repeat rules, with examples.
- [Glossary](https://terramd.io/docs/glossary.md): The words Terra uses, from Agent to Zen mode, each explained in a sentence or two with a link to the page that covers it.

## Quick answers: Get started

- [What's new in Terra](https://terramd.io/docs/answers/get-started/whats-new): This is Terra 0.1.0, the first release, so there's nothing earlier to compare it with yet.
- [Open or switch libraries](https://terramd.io/docs/answers/get-started/open-or-switch-libraries): Choose File › Open Library… and pick the library's folder.

## Quick answers: Workspace basics

- [Run a command](https://terramd.io/docs/answers/workspace/run-a-command): Press ⌘K, type what you want to do, and press Return.
- [Split a pane](https://terramd.io/docs/answers/workspace/split-a-pane): Click Split in the toolbar. A second pane opens to the right of the one you're in.
- [Move between panes](https://terramd.io/docs/answers/workspace/move-between-panes): Click a pane, or press ⌃⌥→ and ⌃⌥← to move to the next or previous one.
- [Open a note in a new tab](https://terramd.io/docs/answers/workspace/open-a-note-in-a-new-tab): Click the note in the note list. It opens as a new tab in the pane you're working in.
- [Go back or forward](https://terramd.io/docs/answers/workspace/go-back-or-forward): Click Back or Forward in the toolbar, or press ⌘[ and ⌘].
- [Use a preset layout](https://terramd.io/docs/answers/workspace/use-a-preset-layout): With two or more panes open, click a layout in the toolbar, or press ⌃⌥ and a number.
- [Hide the sidebar or use Zen mode](https://terramd.io/docs/answers/workspace/hide-the-sidebar): Click Sidebar in the toolbar to hide the sidebar, or Zen mode to hide every drawer at once.
- [Modify the toolbar](https://terramd.io/docs/answers/workspace/modify-the-toolbar): Right-click any toolbar button and choose Customize toolbar….
- [Open the terminal](https://terramd.io/docs/answers/workspace/open-the-terminal): Click Terminal in the toolbar, or press ⌘J, then click Open a terminal.
- [Search my library](https://terramd.io/docs/answers/workspace/search-your-library): Press ⇧⌘F, type a few words, and press Return to open the top result.

## Quick answers: Write and format

- [Create a note](https://terramd.io/docs/answers/write/create-a-note): Choose File › New Note, or press ⌘N.
- [Insert a block with the slash menu](https://terramd.io/docs/answers/write/insert-a-block): Type / in a note and pick a block from the menu.
- [Add headings, lists, to-dos, quotes or code blocks](https://terramd.io/docs/answers/write/add-headings-and-lists): Type / and pick the block, or type its Markdown at the start of a line.
- [Insert a table](https://terramd.io/docs/answers/write/insert-a-table): Type /table and pick a size from the grid.
- [Insert and resize an image](https://terramd.io/docs/answers/write/insert-an-image): Type /image and choose where the image comes from. Drag its corner to resize it.
- [Write math](https://terramd.io/docs/answers/write/write-math): Type /math, choose Math block or Math (inline), then click it to enter LaTeX.
- [Add a callout](https://terramd.io/docs/answers/write/add-a-sprout): Type / and choose Sprout. A Sprout is Terra's callout.
- [Add tabs inside a note](https://terramd.io/docs/answers/write/add-tabs): Type /tabs. Terra adds a group with two tabs.
- [Add or change a cover](https://terramd.io/docs/answers/write/change-the-cover): Click Banner image in the note's properties, then upload or link an image.
- [Switch between reading and editing](https://terramd.io/docs/answers/write/switch-read-and-edit): Press ⌘E, or choose View › Toggle Read / Edit.
- [Find text in a note](https://terramd.io/docs/answers/write/find-text-in-a-note): Click in the note and choose Edit › Find…, or press ⌘F.
- [Duplicate a note](https://terramd.io/docs/answers/write/duplicate-a-note): Open the note and choose File › Duplicate, or press ⌘D.
- [Comment on a note](https://terramd.io/docs/answers/write/comment-on-a-note): Click Comments in the toolbar and write in Add comment….
- [Check my notes for problems](https://terramd.io/docs/answers/write/check-notes-for-problems): Choose Tools › Lint All. Terra checks every note and reports what it finds.

## Quick answers: Link and cite

- [Link to another note](https://terramd.io/docs/answers/link-and-cite/link-to-a-note): Type @, then pick the note from the list.
- [Tag a note](https://terramd.io/docs/answers/link-and-cite/tag-a-note): Click Tag in the note's toolbar and pick or create a tag.
- [Cite a source](https://terramd.io/docs/answers/link-and-cite/cite-a-source): Type / and choose Citation, then pick the source.
- [Add a reference by DOI or ISBN](https://terramd.io/docs/answers/link-and-cite/add-a-reference): Click New… in the toolbar, choose Add reference, then enter the DOI or ISBN and click Look up.
- [Embed a database view in a note](https://terramd.io/docs/answers/link-and-cite/embed-a-database-view): Type /database, then pick the database to show.

## Quick answers: Templates and code

- [Create or edit templates](https://terramd.io/docs/answers/templates-and-code/create-a-template): Open Templates in the sidebar and click Create template.
- [Start a note from a template](https://terramd.io/docs/answers/templates-and-code/new-note-from-template): Choose File › New from Template…, or press ⇧⌘N, and pick a template.
- [Run code in a note](https://terramd.io/docs/answers/templates-and-code/run-code): Set a code block to Python · runnable or R · runnable, then click Run cell.

## Quick answers: Organize your library

- [Make folders and move notes](https://terramd.io/docs/answers/organize/make-folders-and-move-notes): Click New… in the toolbar and choose New folder. To move notes, select them and use Move to.
- [Add files from Finder](https://terramd.io/docs/answers/organize/add-files-from-finder): Drag files from Finder onto a folder in the sidebar.
- [Browse my files as a tree](https://terramd.io/docs/answers/organize/browse-files-as-a-tree): Use the Folders section of the sidebar. Click a folder to open it and show the folders inside.
- [Edit a note's properties](https://terramd.io/docs/answers/organize/edit-note-properties): Click a value under the note's title to change it. Click Add property to add one.
- [Manage properties and types](https://terramd.io/docs/answers/organize/manage-properties-and-types): Choose Tools › Property Manager… and select a property to edit it.
- [Rename an option everywhere](https://terramd.io/docs/answers/organize/rename-an-option-everywhere): Open the option's picker on any note, click ⋯ beside the option and choose Rename option....
- [Rename, recolor or merge tags](https://terramd.io/docs/answers/organize/manage-tags): Choose Tools › Tag Manager…, then click ⋯ beside the tag.
- [Change a note's or folder's icon](https://terramd.io/docs/answers/organize/change-an-icon): Right-click the note's title or the folder's row and choose Change icon.
- [Find my favorites](https://terramd.io/docs/answers/organize/find-your-favorites): Click Favorites in the sidebar's Databases section.
- [Restore or permanently delete trashed notes](https://terramd.io/docs/answers/organize/restore-trashed-notes): Open Trash in the sidebar, right-click the note and choose Put Back.

## Quick answers: Build databases

- [Create a database](https://terramd.io/docs/answers/databases/create-a-database): Click + beside Databases in the sidebar, give it a name and what it collects, then click Create.
- [Add a note to a database](https://terramd.io/docs/answers/databases/add-a-note-to-a-database): Right-click the database in the sidebar and choose New note.
- [Create a new view](https://terramd.io/docs/answers/databases/create-a-view): Open the view menu in the database header and choose Add view.
- [Switch a view's layout](https://terramd.io/docs/answers/databases/switch-a-view-layout): Open View preferences, pick a new Layout on the Layout tab, and click Save view.
- [Filter, sort and group rows](https://terramd.io/docs/answers/databases/filter-sort-and-group): Use Filters, Sort by and Group by in the database header.
- [Preview a row without leaving the view](https://terramd.io/docs/answers/databases/peek-at-a-row): Click the row. The note opens in a peek beside the view, and the list stays where it was.
- [Add a child database](https://terramd.io/docs/answers/databases/add-a-child-database): Right-click a built-in such as Links in the sidebar and choose New link database.
- [Save a view as a Markdown note](https://terramd.io/docs/answers/databases/save-a-view-as-a-note): Open View preferences and click Save as Markdown note.
- [Write a query](https://terramd.io/docs/answers/databases/write-a-query): Choose File › New Query, write a SELECT statement, and press ⌘↩ to run it.

## Quick answers: Tasks and calendar

- [Manage tasks, subtasks and repeats](https://terramd.io/docs/answers/tasks/manage-tasks): Click Tasks in the sidebar, add tasks with Add task, and click a card to edit it.
- [Pull tasks out of note text](https://terramd.io/docs/answers/tasks/pull-tasks-from-notes): Write each task as a checkbox line in a note. Terra lists it in Tasks without any extra step.
- [See tasks and events by date](https://terramd.io/docs/answers/tasks/see-tasks-by-date): Click Calendar in the sidebar.

## Quick answers: Read and capture

- [Read PDFs, books and images](https://terramd.io/docs/answers/read-and-capture/read-pdfs-books-and-images): Drag the file from Finder into the Terra window. Terra adds it to your library and opens it.
- [Open a webpage](https://terramd.io/docs/answers/read-and-capture/open-a-webpage): Click a link in any note. It opens in Terra's browser, next to your notes.
- [Save a webpage to my library](https://terramd.io/docs/answers/read-and-capture/save-a-webpage): Open the page in Terra, then choose Page options › Save to Terra.
- [Capture a quick thought or link](https://terramd.io/docs/answers/read-and-capture/capture-a-quick-thought): Press ⌃⌥⌘N from any app, or choose File › Quick Capture…, then type and press ⌘↵.

## Quick answers: Canvas and sheets

- [Add a spreadsheet](https://terramd.io/docs/answers/canvas-and-sheets/add-a-spreadsheet): In a note, type /sheet and choose Sheet.
- [Make a canvas](https://terramd.io/docs/answers/canvas-and-sheets/make-a-canvas): Click New… in the toolbar and choose New canvas.
- [See a note's connections](https://terramd.io/docs/answers/canvas-and-sheets/see-a-notes-connections): Right-click the note in the note list and choose Graph of this note.

## Quick answers: AI

- [Connect an AI provider](https://terramd.io/docs/answers/ai/connect-an-ai-provider): Open Settings › AI, add your provider under Add provider, then click Connect on its row.
- [Chat with AI about my notes](https://terramd.io/docs/answers/ai/chat-about-your-notes): Click AI conversations in the toolbar, type in Ask anything, and press Return.
- [Control what the agent can change](https://terramd.io/docs/answers/ai/control-what-the-agent-can-change): Pick a mode from the chat's message box: Ask for approval, Approve for me or Full access.

## Quick answers: Connectors and import

- [Bring in meeting notes](https://terramd.io/docs/answers/connect-and-import/bring-in-meeting-notes): Open Settings › Integrations and click Configure beside Granola.
- [Import notes from another app](https://terramd.io/docs/answers/connect-and-import/import-notes): Open Settings › Import, pick the app your notes come from, choose its export, then click Start import.

## Quick answers: Settings, sync and versions

- [Change the theme or accent color](https://terramd.io/docs/answers/settings/change-the-theme): Open Settings › Appearance and click a theme.
- [Change fonts and text size](https://terramd.io/docs/answers/settings/change-fonts-and-text-size): Open Settings › Appearance and scroll to Fonts and Display.
- [Change keyboard shortcuts](https://terramd.io/docs/answers/settings/change-keyboard-shortcuts): Open Settings › Hotkeys, click a shortcut and press the new keys.
- [Back up or sync my library with git](https://terramd.io/docs/answers/settings/sync-with-git): Click Versions in the sidebar, then Initialize version control.
- [Restore an earlier version of a note](https://terramd.io/docs/answers/settings/restore-a-version): Click Versions in the toolbar, then choose Restore version on a save.

## Optional

- [Everything in one file](https://terramd.io/llms-full.txt): all of the guides and quick answers above, concatenated