docs: migrate docs to writerside

.goreleaser.yaml

@@ -6,9 +6,9 @@ before:
     - rm -rf out/man
     - mkdir -p out/man
     - mkdir -p out/html
-    - asciidoctor -a reproducible -b manpage -o out/man/git-age.1 docs/git-age.adoc
+    - asciidoctor -a reproducible -b manpage -o out/man/git-age.1 docs/man/git-age.adoc
     - gzip out/man/git-age.1
-    - asciidoctor -a reproducible -b html5 -o out/html/git-age.html docs/git-age.adoc
+    - asciidoctor -a reproducible -b html5 -o out/html/git-age.html docs/man/git-age.adoc
 
 builds:
   - id: unix
@@ -137,7 +137,6 @@ scoops:
           name: scoop-the-prancing-package
           branch: main
 
-
 winget:
   - name: git-age
     publisher: prskr

docs/web/.gitignore

@@ -0,0 +1 @@
+export

docs/web/c.list

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE categories
+        SYSTEM "https://resources.jetbrains.com/writerside/1.0/categories.dtd">
+<categories>
+    <category id="wrs" name="Writerside documentation" order="1"/>
+</categories>

docs/web/cfg/buildprofiles.xml

@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<buildprofiles xsi:noNamespaceSchemaLocation="https://resources.jetbrains.com/writerside/1.0/build-profiles.xsd"
+               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+
+    <variables>
+        <include-in-head>fragments/analytics.html</include-in-head>
+    </variables>
+    <build-profile instance="g">
+        <variables>
+            <noindex-content>true</noindex-content>
+        </variables>
+    </build-profile>
+
+</buildprofiles>

docs/web/cfg/fragments/analytics.html

@@ -0,0 +1 @@
+<script defer src="https://analytics.icb4dc0.de/script.js" data-website-id="d06d2c33-1b55-4a80-be46-52983ff7d5ff"></script>

docs/web/g.tree

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE instance-profile
+        SYSTEM "https://resources.jetbrains.com/writerside/1.0/product-profile.dtd">
+
+<instance-profile id="g"
+                 name="git-age"
+                 start-page="getting-started.md">
+
+    <toc-element topic="getting-started.md"/>
+    <toc-element topic="install.md"/>
+    <toc-element topic="tips-tricks.md"/>
+    <toc-element topic="configuration.md"/>
+    <toc-element topic="alternatives.md"/>
+    <toc-element topic="internals.md">
+        <toc-element topic="identities-agent.md"/>
+        <toc-element topic="development.md"/>
+    </toc-element>
+</instance-profile>

docs/web/topics/alternatives.md

@@ -0,0 +1,4 @@
+# Alternatives
+
+- [git-crypt](https://github.com/AGWA/git-crypt) - based on GPG
+- [git-private](https://github.com/erkkah/git-private) - not a Git clean/smudge filter but encrypts/decrypts on demand

docs/web/topics/configuration.md

@@ -0,0 +1,16 @@
+# Configuration
+
+For now _git-age_ is configured either via environment variables or CLI flags.
+The most interesting part is where it reads and writes the private keys from.
+This can be configured via the `GIT_AGE_KEYS` environment variable or the `--keys` flag.
+By default, _git-age_ will store the private keys in `$XDG_CONFIG_HOME/git-age/keys.txt`.
+
+| Platform | Config path                                                               |
+|----------|---------------------------------------------------------------------------|
+| Linux    | `$XDG_CONFIG_HOME/git-age/keys.txt` i.e. `$HOME/.config/git-age.keys.txt` |
+| macOS    | `$HOME/Library/Application Support/git-age/keys.txt`                      |
+| Windows  | `%\LOCALAPPDATA%\git-age\keys.txt`                                        |
+
+Additionally, _git-age_ can also look up identities with the help of an agent.
+To use an agent set the `GIT_AGE_AGENT_HOST` environment variable to the corresponding endpoint.
+The agent of your choice should tell you the value of this variable.

docs/web/topics/development.md

@@ -0,0 +1,21 @@
+# Development
+
+## Required Tools
+
+- [`golangci-lint`](https://golangci-lint.run/)
+- [`husky`](https://github.com/go-courier/husky)
+- `goimports`
+- `gofumpt`
+- `asciidoctor`
+- *optionally*: [`goreleaser`](https://goreleaser.com/)
+- *optionally*: [`dlv`](https://github.com/go-delve/delve)
+
+## Install husky
+
+Ensure `golangci-lint` and other checks are executed before commit.
+
+```bash
+go install github.com/go-courier/husky/cmd/husky@latest
+
+husky init
+```

docs/web/topics/getting-started.md

@@ -0,0 +1,56 @@
+# Getting started
+
+## Install hooks
+
+To install the necessary in your Git config run the following command:
+
+```Bash
+git age install
+```
+
+This will add the _git-age_ clean and smudge filters to your Git config.
+
+## Init a repository to share secret files
+
+```Bash
+git age init
+
+# or if you want to add some comment to the generated key
+git age init -c "My comment"
+```
+
+## Add another user to an already initialized repository
+
+**Remarks:** The repository has to be in a clean state i.e. no changes files.
+
+Alice wants to share the secrets stored in her Git repository with Bob:
+
+1. Bob installs _git-age_ on his machine and configures his global git config
+    ```Bash
+    git age install
+    ```
+2. Bob generates a new key pair
+    ```Bash
+    git age gen-key
+
+    # or if you want to add some comment to the generated key
+    git age gen-key -c "My comment"
+    ```
+   the generated private key will be stored automatically in your `keys.txt`
+3. Bob sends his public key to Alice
+4. Alice adds Bob's public key to her repository
+    ```Bash
+    git age add-recipient <public key>
+
+    # or if you want to add some comment to the added key
+
+    git age add-recipient -c "My comment" <public key>
+    ```
+
+`git age add-recipient` will:
+
+1. add the public key to the repository (`.agerecipients` file)
+2. re-encrypt all files with the new set of recipients
+3. commit the changes
+
+As soon as Alice pushed the changes to the remote repository, Bob can pull the changes and decrypt the files.

docs/web/topics/identities-agent.md

@@ -0,0 +1,67 @@
+# Identities agent
+
+_git-age_ normally reads identities from a `keys.txt` file e.g. in your home directory.
+Alternatively, it can also look up identities with the help of an agent either running locally or even remotely.
+If you would like to use an agent, you instruct _git-age_ where to find the endpoint of this agent with the help of the `GIT_AGE_AGENT_HOST` environment variable.
+
+## Workflow
+
+### Look up identities
+
+Whenever _git-age_ has to decrypt a file (i.e. Git invokes it as smudge filter) it will check whether an agent is configured and if so, it will send a `GetIdentitiesRequest` containing the repositories remotes to the agent.
+The agent can (optionally) use the remotes to filter for identities and reply with a set of identities _git-age_ will then try to use to decrypt the stanza:
+
+```mermaid
+sequenceDiagram
+    participant ga as git-age
+    participant a as agent
+    ga->>a: GetIdentitiesRequest
+    a-->>ga: GetIdentitiesResponse
+```
+
+### Generate new identity
+
+When generating new identities (i.e. when invoking `git age gen-key`), _git-age_ will:
+
+1. generate a new identity - typically a X25519 key pair
+2. ask the first identity store to store the key pair
+3. print the public key for further usage
+
+_git-age_ always checks at first whether there's an agent available and if so uses that one as first store.
+
+```mermaid
+sequenceDiagram
+    participant ga as git-age
+    participant a as agent
+    ga->>a: StoreIdentityRequest
+    a-->>ga: StoreIdentityResponse
+```
+
+A user may optionally specify:
+
+- a comment (`-c` \ `--comment`)
+- a remote (`-r` \ `--remote`)
+
+both will be shared with the agent, so it can filter all know identities based on the current repositories remotes.
+
+## Implement a new agent
+
+The agent protocol is gRPC based.
+The spec of the protocol can be found either in the _git-age_ repository or in the [buf registry](https://buf.build/git-age/agent/docs/main:agent.v1).
+Assuming you're going to use a programming language supported by buf, the recommended way is to use of the automatically provided SDKs from the buf registry.
+Alternatively you can always pull the necessary protobuf files and generate the code in your programming language of choice.
+
+Ideally, when starting your awesome agent, it should tell the user how to interact with it from _git-age_ perspective.
+
+An output like:
+```Bash
+export GIT_AGE_AGENT_HOST="unix:///var/run/user/1000/git-age-keyring-agent.sock"
+```
+tells the user how to set up his environment to use your agent.
+
+Apart from this, a _git-age_ agent is only a simple gRPC service that implements the `IdentitiesStoreService` spec.
+
+### Security
+
+Although gRPC supports/encourages the usage of TLS to secure the traffic between services, _git-age_ doesn't support TLS (yet).
+This will be tackled soon™️.

docs/web/topics/install.md

@@ -0,0 +1,92 @@
+# Installation
+
+## OS independent
+
+### `go install`
+
+If you have a current Go installation, you can install _git-age_ with:
+
+```Bash
+go install github.com/prskr/git-age@latest
+```
+
+### GitHub releases
+
+See the [releases page](https://github.com/prskr/git-age/blob/main/prskr/git-age/releases/latest) for the latest release.
+You can download the binary for your platform from there.
+
+## MacOS
+
+## Homebrew
+
+There's a tap for _git-age_ available at [prskr/the-prancing-package](https://github.com/prskr/the-prancing-package).
+
+```Bash
+brew install prskr/the-prancing-package/git-age
+```
+
+or
+
+```Bash
+brew tap prskr/the-prancing-package
+
+brew install git-age
+```
+
+## Linux
+
+### RPM - Fedora, CentOS, RHEL, SuSE, ...
+
+#### DNF
+
+```Bash
+# Import the GPG key
+curl https://api.github.com/users/prskr/gpg_keys | jq -r '.[] | select (.key_id=="1A80DDB584AF7DA7") | .raw_key' > /tmp/prskr.gpg
+sudo rpm --import /tmp/prskr.gpg
+
+dnf config-manager --add-repo https://code.icb4dc0.de/api/packages/prskr/rpm.repo
+
+dnf install git-age
+```
+
+#### Zypper
+
+```
+zypper addrepo https://code.icb4dc0.de/api/packages/prskr/rpm.repo
+
+zypper install git-age
+```
+
+### DEB - Debian, Ubuntu, Mint, PopOS!, ...
+
+```Bash
+sudo curl https://code.icb4dc0.de/api/packages/prskr/debian/repository.key -o /etc/apt/trusted.gpg.d/forgejo-prskr.asc
+
+# distribution is currently only bookworm - but should work for other debian based distributions as well
+echo "deb https://code.icb4dc0.de/api/packages/prskr/debian bookworm main" | sudo tee -a /etc/apt/sources.list.d/forgejo.list
+sudo curl https://code.icb4dc0.de/api/packages/prskr/debian/repository.key -o /etc/apt/trusted.gpg.d/forgejo-prskr.asc
+
+sudo apt update
+
+sudo apt install git-age
+```
+
+## Windows
+
+To install _git-age_ on Windows, you can use [winget](https://learn.microsoft.com/en-us/windows/package-manager/winget/) or [scoop](https://scoop.sh/).
+
+### Winget
+
+```Bash
+winget install --id=prskr.git-age
+```
+
+### Scoop
+
+I maintain a bucket for _git-age_ at [prskr/scoop-the-prancing-package](https://github.com/prskr/scoop-the-prancing-package).
+To add the bucket and install _git-age_, run the following commands:
+
+```Bash
+scoop bucket add the-prancing-package https://github.com/prskr/scoop-the-prancing-package
+scoop install git-age
+```

docs/web/topics/internals.md

@@ -0,0 +1 @@
+# Internals

docs/web/topics/tips-tricks.md

@@ -0,0 +1,9 @@
+# Tips & tricks
+
+## Diff of text files
+
+Set the `diff.age.textconv` Git config to `cat` to see plain text diffs of encrypted files:
+
+```Bash
+git config --global diff.age.textconv cat
+```

docs/web/v.list

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE vars SYSTEM "https://resources.jetbrains.com/writerside/1.0/vars.dtd">
+<vars>
+    <var name="product" value="Writerside"/>
+</vars>

docs/web/writerside.cfg

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE ihp SYSTEM "https://resources.jetbrains.com/writerside/1.0/ihp.dtd">
+
+<ihp version="2.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+     xsi:noNamespaceSchemaLocation="https://resources.jetbrains.com/writerside/1.0/writerside-cfg.xsd">
+    <topics dir="topics"/>
+    <images dir="images" web-path="images"/>
+    <categories src="c.list"/>
+    <vars src="v.list"/>
+    <instance src="g.tree"/>
+</ihp>