Sync

astro.config.mjs

@@ -1,10 +1,29 @@
 import { defineConfig } from 'astro/config';
 import starlightLinksValidator from 'starlight-links-validator'
 import starlight from '@astrojs/starlight';
+import rehypeSlug from 'rehype-slug';
+import rehypeAutolinkHeadings from 'rehype-autolink-headings';
 
 // https://astro.build/config
 export default defineConfig({
   site: "https://docs.atuin.sh",
+  markdown: {
+    rehypePlugins: [
+      rehypeSlug,
+      [
+        rehypeAutolinkHeadings,
+        {
+          behavior: 'wrap',
+          headingProperties: {
+            className: ['anchor'],
+          },
+          properties: {
+            className: ['anchor-link'],
+          },
+        }
+      ]
+    ]
+  },
   integrations: [
     starlight({
       plugins: [starlightLinksValidator()],
@@ -48,6 +67,7 @@ export default defineConfig({
             { label: 'Import existing history', link: '/guide/import' },
             { label: 'Basic usage', link: '/guide/basic-usage' },
             { label: 'Syncing dotfiles', link: '/guide/dotfiles' },
+            { label: 'Theming', link: '/guide/theming' },
           ],
         },
         {

package.json

@@ -13,6 +13,8 @@
     "@astrojs/check": "^0.5.6",
     "@astrojs/starlight": "^0.20.1",
     "astro": "^4.4.6",
+    "rehype-autolink-headings": "^7.1.0",
+    "rehype-slug": "^6.0.0",
     "sharp": "^0.33.2",
     "starlight-links-validator": "^0.5.3",
     "typescript": "^5.3.3"

src/content/docs/configuration/config.mdx

@@ -334,6 +334,9 @@ This matches history against a set of default regex, and will not save it if we
 5. Stripe live/test keys
 6. Atuin login command
 7. Cloud environment variable patterns (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AZURE_STORAGE_CLASS_KEY`, `GOOGLE_SERVICE_ACCOUNT_KEY`)
+8. Netlify authentication tokens
+9. Npm pat
+10. Pulumi pat
 
 ### macOS <kbd>Ctrl-n</kbd> key shortcuts
 Default: `true`
@@ -569,6 +572,7 @@ Which preview strategy is used to calculate the preview height. It respects `max
 |----------------|-----------------------------------------------------|
 | auto (default) | selected command                                    |
 | static         | longest command in the current result set           |
+| fixed          | use `max_preview_height` as fixed value             |
 
 By using `auto` a preview is shown, iff the command is longer than the width of the terminal.
 
@@ -620,3 +624,48 @@ The port to use for client -> daemon communication. Only used on non-unix system
 ```toml
 tcp_port = 8889
 ```
+
+## theme
+Atuin version: >= 18.4
+
+The theme to use for showing the terminal interface.
+
+```toml
+[theme]
+name = ""
+debug = false
+max_depth = 10
+```
+
+### `name`
+Default: `""`
+
+A theme name that must be present as a built-in (an empty string for the default,
+`autumn` or `marine`), or found in the themes directory, with the suffix `.toml`.
+By default this is `~/.config/atuin/themes/` but can be overridden with the
+`ATUIN_THEME_DIR` environment variable.
+
+```toml
+name = "my-theme"
+```
+
+### `debug`
+Default: `false`
+
+Output information about why a theme will not load. Independent from other log
+levels as it can cause data from the theme file to be printed unfiltered to the
+terminal.
+
+```toml
+debug = false
+```
+
+### `max_depth`
+Default: 10
+
+Number of levels of "parenthood" that will be traversed for a theme. This should not
+need to be added in or changed in normal usage.
+
+```toml
+max_depth = 10
+```

src/content/docs/faq.mdx

@@ -24,11 +24,13 @@ You can make `enter` edit a command by putting `enter_accept = false` into your
 
 ## How do I delete my account?
 
+**Attention:** This command does not prompt for confirmation.
+
 ```
 atuin account delete
 ```
 
-This will delete your account, and all history. 
+This will delete your account, and all history from the remote server. It will not delete your local data.
 
 ## I've forgotten my password! How can I reset it?
 

src/content/docs/guide/installation.mdx

@@ -87,6 +87,19 @@ If you don't wish to use the installer, the manual installation steps are as fol
         pkg install atuin
         ```
     </TabItem>
+    <TabItem label="zinit">
+        Atuin is installable from github-releases directly:
+
+        ```shell
+        # line 1: `atuin` binary as command, from github release, only look at .tar.gz files, use the `atuin` file from the extracted archive
+        # line 2: setup at clone(create init.zsh, completion)
+        # line 3: pull behavior same as clone, source init.zsh
+        zinit ice as"command" from"gh-r" bpick"atuin-*.tar.gz" mv"atuin*/atuin -> atuin" \
+            atclone"./atuin init zsh > init.zsh; ./atuin gen-completions --shell zsh > _atuin" \
+            atpull"%atclone" src"init.zsh"
+        zinit light atuinsh/atuin
+        ```
+    </TabItem>
     <TabItem label="Source">
         Atuin builds on the latest stable version of Rust, and we make no
         promises regarding older versions. We recommend using [rustup](https://rustup.rs/).
@@ -121,6 +134,7 @@ After installing, remember to restart your shell.
         <Tabs>
             <TabItem label="zinit">
                 ```shell
+                # if you _only_ want to install the shell-plugin, do this; otherwise look above for a "everything via zinit" solution
                 zinit load atuinsh/atuin
                 ```
             </TabItem>
@@ -136,7 +150,7 @@ After installing, remember to restart your shell.
             <TabItem label="ble.sh">
                 Atuin works best in bash when using [ble.sh](https://github.com/akinomyoga/ble.sh).
 
-                With ble.sh installed, just add atuin to your .bashrc
+                With ble.sh installed and loaded in `~/.bashrc`, just add atuin to your `~/.bashrc`
 
                 ```shell
                 echo 'eval "$(atuin init bash)"' >> ~/.bashrc
@@ -150,6 +164,14 @@ After installing, remember to restart your shell.
                     bash-preexec currently has an issue where it will stop honoring `ignorespace`.
                     While Atuin will ignore commands prefixed with whitespace, they may still end up in your bash history.
                     Please check your configuration! All other shells do not have this issue.
+
+                    To use Atuin in `bash < 4` with bash-preexec, the option `enter_accept` needs
+                    to be turned on (which is so by default).
+
+                    bash-preexec cannot properly invoke the `preexec` hook for subshell commands
+                    `(...)`, function definitions `func() { ...; }`, empty for-in-statements `for
+                    i in; do ...; done`, etc., so those commands and duration may not be recorded
+                    in the Atuin's history correctly.
                 </Aside>
 
                 To use bash-preexec, download and initialize it

src/content/docs/guide/theming.mdx

@@ -0,0 +1,113 @@
+---
+title: Theming
+---
+
+Available in Atuin >= 18.4
+
+For terminal interface customization, Atuin supports user and built-in color themes.
+
+Atuin ships with only a couple of built-in alternative themes, but more can be added via TOML files.
+
+# Required config
+
+The following is required in your config file (`~/.config/atuin/config.toml`)
+
+```
+[theme]
+name = "THEMENAME"
+```
+
+Where `THEMENAME` is a known theme. The following themes are available out-of-the-box:
+
+* default theme (can be explicitly referenced with an empty name `""`)
+* `autumn` theme
+* `marine` theme
+
+These are present to ensure users and developers can try out theming, but in general, you
+will need to download themes or make your own.
+
+If you are writing your own themes, you can add the following line to get additional output:
+
+```
+debug = true
+```
+
+to the same config block. This will print out any color names that cannot be parsed from
+the requested theme.
+
+A final optional setting is available:
+
+```
+max_depth: 10
+```
+
+which sets the maximum levels of theme parents to traverse. This should not need to be
+explicitly added in normal use.
+
+# Usage
+
+## Theme structure
+
+Themes are maps from *Meanings*, describing the developer's intentions,
+to (at present) colors. In future, this may be expanded to allow richer style support.
+
+*Meanings* are from an enum with the following values:
+
+* `AlertInfo`: alerting the user at an INFO level
+* `AlertWarn`: alerting the user at a WARN level
+* `AlertError`: alerting the user at an ERROR level
+* `Annotation`: less-critical, supporting text
+* `Base`: default foreground color
+* `Guidance`: instructing the user as help or context
+* `Important`: drawing the user's attention to information
+* `Title`: titling a section or view
+
+These may expand over time as they are added to Atuin's codebase, but Atuin
+should have fallbacks added for any new *Meanings* so that, whether themes limit to
+the present list or take advantage of new *Meanings* in future, they should
+keep working sensibly.
+
+**Note for Atuin contributors**: please do identify and, where appropriate during your own
+PRs, extend the Meanings enum if needed (along with a fallback Meaning!).
+
+## Theme creation
+
+When a theme name is read but not yet loaded, Atuin will look for it in the folder
+`~/.config/atuin/themes/` unless overridden by the `ATUIN_THEME_DIR` environment
+variable. It will attempt to open a file of name `THEMENAME.toml` and read it as a
+map from *Meanings* to colors.
+
+Colors may be specified either as names from the [palette](https://ogeon.github.io/docs/palette/master/palette/named/index.html)
+crate in lowercase, or as six-character hex codes, prefixed with `#`. For example,
+the following are valid color names:
+
+* `#ff0088`
+* `teal`
+* `powderblue`
+
+A theme file, say `my-theme.toml` can then be built up, such as:
+
+```toml
+[theme]
+name = "my-theme"
+parent = "autumn"
+
+[colors]
+AlertInto = "green"
+Guidance = "#888844"
+
+```
+
+where not all of the *Meanings* need to be explicitly defined. If they are absent,
+then the color will be chosen from the parent theme, if one is defined, or if that
+key is missing in the `theme` block, from the default theme.
+
+This theme file should be moved to `~/.config/atuin/themes/my-theme.toml` and the
+following added to `~/.config/atuin/config.toml`:
+
+```
+[theme]
+name = "my-theme"
+```
+
+When you next run Atuin, your theme should be applied.