aengus 0.5.3

A tui writing app

Aengus - A TUI Writing App

Aengus is a simple editor for the terminal tailored towards novel writing, especially fantasy and science fiction. It offers nice highlighting features for characters, places, artifacts or more. It can be easily configured to your workflow and comes with some built in statistics. It uses simple markdown files as the base layer so your work can be easily imported from other apps.

Installation

Install with pip install aengus.

Then create a project with aengus new <PROJECT_NAME> and open with aengus open <PROJECT_NAME>.

Or get help with aengus -h.

Documentation

To see all Keyboard Shortcuts press ctrl+p to open the command palette where you can see all shortcuts for the app and editor with a small explanation. The keybindings have been tested on Windows for Powershell using the Terminal App. If you are on a different OS or just want to change the keybindings you can do so in your aengus.toml.

[keybindings]
# all the app keybindings
quit = "ctrl+q"
toggle_command_palette = "ctrl+p"
enter_zen_mode = "f5"
statistics = "ctrl+l"
set_sprint_wc_goal = "ctrl+d"
new_file = "ctrl+n"
save = "ctrl+s"
close = "ctrl+t"
open_finder = "ctrl+o"
back_one_file = "ctrl+b"
delete_file = "ctrl+k"
rename_file = "ctrl+r"
close_overlay = "escape"
find_replace = "ctrl+f"
focus_left = "alt+left"
focus_right = "alt+right"
resize_editor = "ctrl+j"
# all the editor keybindings that can be changed for now
open_mention = "ctrl+g"
word_left = "ctrl+left"
word_right = "ctrl+right"

Aengus can interpret every folder as a project with an aengus.toml file at its root. When creating a new project with aengus new <PROJECT_NAME> it will create a new folder with the following structure:

 - [characters]  <--- put all your character sheets in here
   - ..
 - [places]  <--- put all your place sheets in here
   - ..
 - [notes]  <--- for notes that will not be used for wordcount or highlighting
   - ..
 - [novel]  <--- put all your chapters in here
   - ..
 - aengus_stats.csv
 - aengus.toml

To highlight anything in your novel you define a Mention, which is simply a markdown file in a specific folder. By default Aengus creates a folder for characters and places.

To create a new character inside the editor press ctrl+n and put a new markdown file into the characters folder. To further customize the highlighting Aengus uses frontmatter like syntax, so you can preface the markdown file with the following:

---
name: Sima --> the main name of this character (omit and the filename will be used)
aliases:
  - Little Mouse --> a list of aliases to highlight the character (optional)
color: #e44e0e --> this color will be used to highlight this character, omit for default
---

The same works for places or all the other mention folders you defined in your project toml under

[mentions]
folders = ["characters", "places"] # <---- here

# add this section to customize the mention colors yourself, delete to use the theme colors
[mention_colors]
fallback = "#dda0dd" # <---- used when a folder has no specific mention color yet
characters = "#ffd700" # <---- change this for the fallback color of all characters

Mentions work with nested folders as well. So if you want to structure your characters into families for example, you can do that and define a color for every family. Aengus will try and walk all folders recursively until it finds a color. For example:

[mention_colors]
characters = "#ff0000"
Stark = "#00ff00"

If you have a Stark folder within the characters folder it will highlight all mentions green and all other characters (plus all the subdirectories) in red.

To get a short summary of your chapter inside the file picker you can add a frontmatter to the start of your chapter and it will show the first few lines of that summary when going through the files in the file picker.

---
Sima meets the Collector and agrees to work for him.
---
```

To change the theme of the app you can select a theme in your `aengus.toml`.

```toml
[theme]
name = "aengus" # or for a warmer version use aengus-autumn
```

If you want more control over the highlighting you can override any color of the theme 
directly in your `aengus.toml`. Here is a selection of all the colors that can be changed.
All colors you omit will be filled by the selected theme, so by default from `aengus` theme.

```toml
[theme]
primary = "#2ec4b6"
secondary = "#15534e"
accent = "#ffb454"
foreground = "#fcfdfa"
background = "#00061D"
cursor = "#ffb454"
text = "#eaecea"
dialogue = "#f2e0bd"
italic = "#89f2fe"
gutter = "#6272a4"
selection = "#264f78"
```

Aengus records simple analytics in the `aengus_stats.csv` file and displays it under the 
**Statistics** tab (open with **ctrl+l**).

To build your book into a nice, standalone HTML file run `aengus build <PROJECT_ROOT>`. By default 
your chapters will be ordered alphabetically how they appear in your `novel` folder. If you want 
to change the order of your chapter add this to your `aengus.toml`:

```toml
[book]
chapter_order = [
    "First Chapter.md",
    "Second Chapter.md",
    ...
]
```

To customize the width of the editor in **Zen Mode** or to change spell check 
you can add a field to your `[project]`. Disable spell check with `"None"`.

```toml
[project]
zen_mode_width = 98
locale = "en_GB" # available: de_DE, en_GB, en_US, es_ES, fr_FR, None
```

There is a simple version control in Aengus, that should be used at your own risk. It is currently 
not stable, so backup your work before using it (yes I get the irony.)

You can create a snapshot of your project with `aengus snapshot <SNAPSHOT_NAME>` and list all 
your snapshots with `aengus checkout`. To checkout a specific snapshout run 
`aengus checkout <SNAPSHOT_NAME>`.

### Setup Environment

This repository uses uv. Run `uv sync` to create the virtual environment.

Install with `pip install -e .` to get instant feedback while editing.

On windows add the `Scripts` folder to `PATH` if you have not already.

### Planned Features

 - writing personas based on writing activity (Night Owl for writing at night, 
 Overthinker for spending only little time per seession actually writing)