Metadata-Version: 2.4
Name: aengus
Version: 0.5.0
Summary: A tui writing app
Author-email: Tim Betz <tim.betz@protonmail.com>
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: markdown>=3.10.2
Requires-Dist: pyahocorasick>=2.3.1
Requires-Dist: python-frontmatter>=1.1.0
Requires-Dist: rich>=14.3.2
Requires-Dist: textual>=8.2.4
Dynamic: license-file

# Aengus - A TUI Writing App

<p align="center">
  <img src="assets/editor_view.png" width="80%" alt="Editor View">
  <br>
  <img src="assets/statistics_view.png" width="80%" alt="Statistics View">
</p>

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`.

```toml
[keybindings]
# all the app keybindings
quit = "ctrl+q"
toggle_command_palette = "ctrl+p"
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 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, so you can 
preface the markdown file with the following:

```yaml
---
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 

```toml
[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
```

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",
    ...
]
```

### 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)

 ### Bugs to investigate

 - when on the Statistics page and the user opens the Command Panel, closes it 
and switches back to Editor View, the left editor always gets focussed
