Metadata-Version: 2.4
Name: atlas-md
Version: 0.1.0
Summary: A command-line tool for managing and validating Markdown-based worldbuilding vaults.
Author-email: Ryan Mattson <ramattson5@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/ryanamatt/Atlas
Project-URL: Issues, https://github.com/ryanamatt/Atlas/issues
Keywords: worldbuilding,markdown,cli,vault
Classifier: Programming Language :: Python :: 3
Classifier: Environment :: Console
Classifier: Topic :: Text Processing :: Markup :: Markdown
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyyaml>=6.0
Dynamic: license-file

# Atlas

A command-line tool for managing Markdown worldbuilding vaults, built with Obsidian in mind.

Atlas creates, moves, deletes, lists, and searches notes in a vault of plain Markdown files. It keeps note ids and `[[wiki links]]` consistent when you reorganize, so renaming a note never leaves broken links behind.

## Features

- Create notes from templates, with frontmatter written for you
- Move or rename notes and automatically update every wiki link that points at them
- Safe deletes: notes go to a trash folder instead of being erased
- Tree view of your vault and title search
- Works on plain `.md` files, so your vault stays usable in Obsidian or any other editor

## Requirements

- Python 3.11 or newer

## Installation



## Quick start

```bash
cd ~/Documents/MyWorld
atlas init
atlas create "Nations/Republic of Valora" --type Nation
atlas list
```

`atlas init` marks a folder as an Atlas vault by creating a `.atlas` directory inside it. Every other command needs that directory to exist.

## Finding your vault

Atlas looks for a vault in this order:

1. The path given with `-v` / `--vault`
2. The current directory, then up to five parent directories, stopping at the first one that contains `.atlas`

So you can run commands from any subfolder of your vault without passing a path. Global options go before the command:

```bash
atlas --vault ~/Documents/MyWorld list
atlas --quiet create "Characters/Aria"
```

| Option | Description |
| --- | --- |
| `-v`, `--vault PATH` | Path to the vault. |
| `--quiet` | Silence messages from Atlas. |
| `--version` | Show the Atlas version. |

## Commands

Note names are paths relative to the vault root. The `.md` extension is optional.

### `atlas init`

Initializes the current directory (or `--vault`) as an Atlas vault. This creates `.atlas/` directory.

### `atlas create NAME [NAME ...]`

Creates one or more notes. Missing folders are created for you. Each new note gets an `id` in its frontmatter, generated from its path, and a heading with its title.

```bash
atlas create "Nations/Republic of Valora"
atlas create "Characters/Aria" "Characters/Bram" --type character
atlas create "Places/Old Harbor" --template location --open
```

| Option | Description |
| --- | --- |
| `--type TYPE` | Sets `type` in the note's frontmatter, lowercased. |
| `-t`, `--template NAME` | Starts the note from a template in `.atlas/templates`. |
| `--open` | Opens the last created note in `$EDITOR`. |

### `atlas list`

Prints a tree of every Markdown file in the vault. Hidden files and folders are skipped unless you pass `-a` / `--all`.

### `atlas search QUERY`

Prints the vault-relative path of every note whose title contains the query. The match is case-insensitive and only looks at titles, not folders or note contents. Use `-a` / `--all` to include hidden directories such as the trash.

```bash
atlas search valora
```

### `atlas move SOURCE [SOURCE ...] DESTINATION`

Moves or renames notes.

- With one source, the destination is the new path of the note.
- With several sources, the destination must be an existing folder.

```bash
atlas move "Nations/Valora" "Nations/Republic of Valora"
atlas move "Characters/Aria" "Characters/Bram" Archive
```

When a note moves, Atlas:

- Rewrites the note's frontmatter `id` to match its new path
- Updates wiki links in every note in the vault, including aliases (`[[Note|alias]]`), headings (`[[Note#Heading]]`), and embeds (`![[Note]]`)
- Leaves links inside code blocks and inline code untouched
- Leaves a bare-title link alone when several notes share that title, since it is unclear which one was meant

All moves are checked before anything changes, so a bad argument never leaves the vault half moved. Pass `--no-links` to skip the link updates.

### `atlas delete NAME [NAME ...]`

Moves notes to the vault's `.trash` folder instead of erasing them. A timestamp is added to the file name, so deleting a note with the same name twice never overwrites the earlier copy.

## Templates

Templates are Markdown files in `.atlas/templates`. Pass the name without the `.md` suffix:

```bash
atlas create "Places/Old Harbor" --template location
```

Templates can have frontmatter and a body, and `{{placeholders}}` are filled in when the note is created:

| Placeholder | Value |
| --- | --- |
| `{{title}}` | The note title (its file name without `.md`). |
| `{{id}}` | The generated note id. |
| `{{date}}` | Today's date as `YYYY-MM-DD`. |

Unknown placeholders are left as they are. Example `.atlas/templates/location.md`:

```markdown
---
type: location
created: "{{date}}"
tags: []
---

# {{title}}

## Description

## Notable people
```

The note `id` is always generated by Atlas, and a `--type` given on the command line overrides a `type` set in the template.

## Vault layout

```text
MyWorld/
├── .atlas/
│   ├── config.toml
│   └── templates/
├── .trash/
├── Nations/
│   └── Republic of Valora.md
└── Characters/
    └── Aria.md
```

## License

MIT
