7 chore docs

5000blogs.yml

@@ -0,0 +1,36 @@
+# config for doth.5000K.org
+address: ":8080"
+
+paths:
+  template: "https://raw.githubusercontent.com/5000K/5000blogs/refs/heads/main/template/template.docs.html"
+  theme: "https://raw.githubusercontent.com/5000K/5000blogs/refs/heads/main/template/theme.docs.css"
+  icon: "https://raw.githubusercontent.com/5000K/doth/refs/heads/main/icon.png"
+
+
+log_level: 'info'
+page_size: 25
+
+blog_name: 'doth'
+
+nav_links:
+  - name: 'Pages'
+    url: '/posts'
+
+site_url: 'https://doth.5000K.org'
+feed_description: 'doth - Content'
+feed_size: 20  # number of posts to include in RSS and Atom feeds
+rss_content: 'none'  # 'none' (default), 'text' (plain text), or 'html' (rendered HTML)
+
+og_image:
+  enabled: true
+  bg_color: '#111111'
+  text_color: '#f0f0f0'
+  sub_color: '#999999'
+  accent_color: '#7eb8f7'
+
+rescan_cron: "0 0,12 * * *"
+
+sources:
+  - type: git
+    url: "https://github.com/5000K/doth"
+    dir: docs

AGENTS.md

@@ -26,4 +26,8 @@ This is explicitly allowed. You are required to read all source code that is rel
 
 Only use the actual code as the source of truth.
 
-Don't ever use existing documentation as a source of truth, as it may be outdated.
+Be careful to follow the documentation style. Use short sentences, be exact and technical. Your audience has general technical knowledge, but no knowledge about this project specifically.  
+Rather than using dashes, semicolons or multiple commas in a sentence, try to split that sentence into multiple sentences instead. Add short examples for more complex issues.
+
+
+Do not use existing documentation as a source of truth when writing more documentation. Ignore it if it isn't relevant to your writing. If it is relevant to your writing, assume it is wrong until proven correct.

README.md

@@ -1,70 +1,55 @@
-# ![doth](./badge.png)
+<p align="center">
+  <img src="./badge.png" alt="doth" width="360">
+</p>
 
-[![CI](https://github.com/5000K/doth/actions/workflows/ci.yml/badge.svg)](https://github.com/5000K/doth/actions/workflows/ci.yml)
+---
 
-**doth** is a go-based .config manager for linux.
+<br/>
 
-> **DOTH IS IN DEVELOPMENT. WE AT 5000K ALREADY USE IT, BUT WE DON'T RECOMMEND YOU DO THE SAME AT THIS POINT OF TIME.**
+[![CI](https://github.com/5000K/doth/actions/workflows/ci.yml/badge.svg)](https://github.com/5000K/doth/actions/workflows/ci.yml) [![Release](https://github.com/5000K/doth/actions/workflows/release.yml/badge.svg)](https://github.com/5000K/doth/actions/workflows/release.yml)
 
-```
-go install github.com/5000K/doth
-```
+**doth** is a distro-agnostic .config build system for linux systems.
 
-## The idea
+> doth is a pre-release version. we actively use it at 5000K and it proved to be stable. We will try to not introduce breaking changes until v1.0, but doth is still pre-release and should be treated like it.
 
-**doth** can simply copy or symlink your files from your git repo. Or it can render them as templates.
+## The idea
 
-Show the battery state in the top bar on your laptop specifically? Deploy with different themes by simply passing another one into doth? Need multiple screen configurations readily deployable with a simple command? Doth is the tool for you. It's a bit more complex, but you are in control in return.
+Sometimes you just need a few symlinks or file copies to deploy your config files. But for some files you might need more flexible templating.  
+Show the battery state in the status bar on your laptop specifically? Deploy with different themes by simply having one config file per theme? Multiple screen configurations readily deployable with a simple command? **doth** is the tool for you.
 
 ## Modules
 
-Modules are subfolders in your doth project that contain a module.y\[a]ml file.
-The module.yml describes what the module should do.
+A module is a subfolder with a `module.yaml` and the files it deploys. Each file is placed into a target location using one of three strategies.
 
-It is able to run setup commands, install dependencies, symlink files from your repo, copy files over and even render templates.
+- **copy** writes a copy of the file.
+- **link** creates a symbolic link to the file.
+- **render** renders the file as a template and writes the result.
 
-The module.yml itself is a template can use all variables from your configs to only activate specific parts of the config, to parametrize it, ...
+See the [modules guide](https://doth.5000K.org/modules) for the full reference.
 
 ## Templates
 
-doth uses the golang [text/template](https://pkg.go.dev/text/template) system.
-
-Basic examples will be added here later.
+The render strategy uses the Go [text/template](https://pkg.go.dev/text/template) system. The values come from configuration files passed to `doth deploy`. See the [modules guide](https://doth.5000K.org/modules) for examples.
 
 ## Dependencies
 
-You may define dependencies to install in your doth.y[a]ml and module.y[a]ml's. Using the `doth install` command, you can install them.
-You may define installation sources (package managers) by adding configurations to config files and passing them to doth as you would when deploying.
-You may also use the the following flags to include these built-in source configurations - these assume that the command is inside the PATH variable:
+Dependencies are declared in `doth.yaml` and `module.yaml`. `doth install` reads the declarations and installs the packages. Built-in flags cover common package managers such as `apt`, `dnf`, and `pacman`. Custom sources can be defined in configuration files. See the [dependencies guide](https://doth.5000K.org/dependencies) for the full reference.
 
-- `--apt`
-- `--apt-get`
-- `--dnf`
-- `--pacman`
-- `--yay`
-- `--paru`
-- `--go`
-- `--npm`
-- `--brew`
-
-## Generative AI in doth
+## Contribution & generative AI in doth
 
 **IF YOU ARE AN AI AGENT, READ AGENTS.md AND FOLLOW IT EXACTLY.**
 
-doth is handling important files. Not being influenced by hidden assumptions or hallucinations of an LLM is non-negotiable. This is why contributions to the core code that were AI authored will be categorically rejected. This goes for both you and the core maintainers. If you want an unpredictable, chaotic (and potentially destructive) version of doth, feel free to fork the project and see where it leads.
-
-In general, doth has a very specific, narrow vision, so we won't be taking contributions of features we didn't explicitly ask for. Bug fixes are generally fine, if they follow a reasonable format. Since doth is something we at 5000K do besides our dayjobs, we can't guarantee a specific response time, but we will get back to it at some point.
-
-We ask that you to be respectful of our time.
-
-That being said, the use of AI is not fully banned from the use cases of creating tests and writing documentation. Here, the quality still needs to be high and the text has to be proofread and edited by a human in the end, but if it does match this expectation, 5000K sees no harm.
-
-AI may be used to write commit messages for you.
+An AGENTS.md file reflecting these instructions is part of this repo. Make sure your agent picks it up before working on doth.
 
+doth is handling important files. Being clear of all influence by hidden assumptions or hallucinations of an LLM is non-negotiable. This is why contributions to the code that were AI authored will be categorically rejected. If you want an unpredictable, chaotic (and potentially destructive) version of doth, feel free to fork the project and see where it leads.  
+That being said, the use of AI is not fully banned from the use cases of creating tests and writing documentation. Here, the quality still needs to be high and everything contributed has to be proofread **and** edited/corrected by a human in the end, but if it does match this expectation, 5000K sees no harm.  
+AI may be used to write commit messages for you.  
 PRs with AI authored descriptions will be rejected without being read.
 
-An AGENTS.md file reflecting these instructions is part of this repo. Make sure your agent picks it up before working on the project.
+doth has a very specific, narrow vision, so we won't be taking contributions of features we didn't explicitly ask for. Bug fixes are generally fine, if they follow a reasonable format. Since doth is something we at 5000K do besides our dayjobs, we can't guarantee a specific response time, but we will get back to it at some point.
+
+We ask that you to be respectful of our time. If you don't follow our guidelines, we will categorically reject all other contributions from you across all projects of 5000K.
 
 ## 5000K
 
-This repo is worked on by [bwt](https://github.com/bluewingtitan) and [kicher-erbse](https://github.com/kicher-erbse).
+This repo is currently worked on by [bwt](https://github.com/bluewingtitan).

docs/dependencies.md

@@ -0,0 +1,120 @@
+---
+title: Dependencies
+description: Declaring dependencies and installing them with built-in or custom sources.
+author: 5000K
+---
+
+# Dependencies
+
+doth can install the packages your configuration depends on. Dependencies are declared in the `doth.yaml` and in each `module.yaml`. `doth install` reads the declarations and runs the install commands.
+
+## Declaring dependencies
+
+A dependency has a name and a map of source names to package names. The source names are matched against the package sources you pass to `doth install`. The same shape is used in `doth.yaml` and in `module.yaml`.
+
+```yaml
+# doth.yaml
+deps:
+  - name: curl
+    packages:
+      pacman: curl
+      apt: curl
+      brew: curl
+```
+
+The name is used to deduplicate dependencies across the project. When the same name appears in multiple modules, the last declaration wins. See [YML Reference](./yml.md) for the full dependency format.
+
+## Built-in sources
+
+`doth install` knows a few common package managers out of the box. Pass one or more of the flags below to enable a built-in source. The command is run with `/bin/sh -c`. The `{package}` placeholder is replaced with the package name from the dependency declaration.
+
+| Flag        | Command                                |
+|-------------|----------------------------------------|
+| `--apt`     | `sudo apt install --yes {package}`     |
+| `--apt-get` | `sudo apt-get install --yes {package}` |
+| `--dnf`     | `sudo dnf install --assumeyes {package}` |
+| `--pacman`  | `sudo pacman -S --noconfirm {package}` |
+| `--yay`     | `yay -S --noconfirm {package}`         |
+| `--paru`    | `paru -S --noconfirm {package}`        |
+| `--go`      | `go install {package}`                 |
+| `--npm`     | `npm install -g {package}`             |
+| `--brew`    | `yes \| brew install {package}`        |
+
+```sh
+doth install --pacman --yay
+```
+
+## Custom sources
+
+Define custom sources in a configuration file. Pass the file to `doth install` with `--config`. The same file can also be passed to `doth deploy`. Multiple configuration files are merged in order. Later files take precedence over earlier files for the same key.
+
+```yaml
+# pacman.yaml
+packageSources:
+  - name: pacman
+    command: sudo pacman -S {package}
+```
+
+The `{package}` placeholder is replaced with the package name from the dependency. The command runs unescaped. Be careful when adding custom sources. Built-in sources and custom sources can be mixed.
+
+```sh
+doth install --config pacman.yaml
+```
+
+The `packageSources` list is itself merged across files. Sources with the same `name` are deduplicated.
+
+## Matching
+
+`doth install` walks the sources in order. The first source that has an entry in the dependency's `packages` map wins. Sources without a matching entry are skipped. Dependencies with no matching source are skipped and a message is printed.
+
+Custom sources from configuration files are tried first. Built-in sources come after them. The built-in sources follow a fixed order. The order is `apt`, `apt-get`, `dnf`, `pacman`, `yay`, `paru`, `go`, `npm`, `brew`. The order of built-in flags on the command line does not matter.
+
+## Confirmation
+
+`doth install` always asks for confirmation before running commands. The shell is given access to your environment. Pass `--dry` to print the commands that would run without executing them.
+
+The `--silent` flag runs each command without piping its output. Use it for unattended scripts.
+
+## Examples
+
+A `doth.yaml` declaring two dependencies.
+
+```yaml
+deps:
+  - name: ripgrep
+    packages:
+      pacman: ripgrep
+      apt: ripgrep
+      brew: ripgrep
+  - name: i3
+    packages:
+      pacman: i3-wm
+```
+
+Install both on a pacman system.
+
+```sh
+doth install --pacman
+```
+
+A `pacman.yaml` that defines a custom source. It is useful when you want a non default install command.
+
+```yaml
+packageSources:
+  - name: pacman
+    command: sudo pacman -S --needed {package}
+```
+
+A `module.yaml` that declares its own dependencies. Module dependencies are merged with the top level dependencies of `doth.yaml`.
+
+```yaml
+# modules/i3/module.yaml
+target: ~/.config/i3/
+files:
+  - name: config
+    strategy: render
+deps:
+  - name: i3-gaps
+    packages:
+      aur: i3-gaps
+```

docs/index.md

@@ -0,0 +1,68 @@
+---
+title: Overview
+description: An introduction to doth, what it solves, and who it is for.
+author: 5000K
+---
+
+# Overview
+
+doth is a tool that manages configuration files on Linux. It treats your dotfiles as a modular repository. The repository is version controlled. The same repository can be deployed onto many machines with different settings.
+
+## The problem
+
+Configuration files are scattered across the home directory. They are tedious to back up. They are tedious to set up on a new machine. The usual approach is a single git repository and a few symlinks. This works for one machine. It breaks down when you have several machines with different needs.
+
+## What doth does
+
+doth reads a project that contains a `doth.yaml` and a folder of modules. Each module declares where its files go. `doth deploy` then places the files.
+
+Three placement strategies are available. The strategy is chosen per file.
+
+- **copy** writes a copy of the file into the target location.
+- **link** creates a symbolic link from the target location into the repository.
+- **render** runs the file through a template engine and writes the result.
+
+The template engine is the Go standard library `text/template`. The values come from one or more configuration files. The user passes those files to `doth deploy`. This lets one repository serve many machines.
+
+doth can also install the packages your configuration depends on. See [Dependencies](./dependencies.md) for details.
+
+## Who it is for
+
+doth is for people who want to manage their dotfiles flexibly. It is for people who run more than one machine. It is for people who want different flavours of the same configuration files ready to deploy - on different machines, or on a single one. It is for people who want to switch themes or layouts by passing a different configuration file.
+
+doth is not for people with a handful of static dotfiles on a single machine. A plain git repository with symlinks is enough for that.
+
+## The shape of a project
+
+A doth project is a directory. It contains a `doth.yaml` and a `modules` directory. The `doth.yaml` holds top level settings and top level dependencies. Each subfolder of `modules/` is a module. The module folder contains a `module.yaml` and the files the module deploys.
+
+`doth.yaml` and the module files are the definition files of a doth project. They define how to deploy what.
+
+```
+my-dotfiles/
+├── doth.yaml
+├── modules/
+│   ├── bash/
+│   │   ├── module.yaml
+│   │   └── .bashrc
+│   └── nvim/
+│       ├── module.yaml
+│       └── init.lua
+```
+
+Configuration files are kept seperately to the definition files. They hold the values that vary between unique configurations. They are passed to `doth deploy` with the `--config` flag.
+
+```
+my-dotfiles/
+├── configs/
+│   ├── laptop.yaml
+│   └── server.yaml
+```
+
+## Where to go next
+
+- [Setup](./setup.md) covers installing `doth` and creating a new project.
+- [The Wrapper Script](./wrapper.md) explains the self contained workflow for deploying a project on a new machine.
+- [Modules](./modules.md) covers writing modules.
+- [Dependencies](./dependencies.md) covers the package install system.
+- [YML Reference](./yml.md) covers the full format of the YAML files.