aengus 0.5.0

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"
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:

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

To change the theme of the app you can select a theme in your aengus.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.

[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:

[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