Miscellaneous doc fixups (#561)

* Miscellaneous doc fixups

* Format TOML

Cargo.toml

@@ -96,6 +96,7 @@ fred = { version = "9.0.3", features = [
     "full-tracing",
     "i-scripts",
     "sha-1",
+    "unix-sockets",
 ] }
 garde = { version = "0.20.0", features = [
     "derive",

web/src/content/docs/configuration/database.mdx

@@ -3,11 +3,16 @@ title: Database
 description: Configure the database used by Kitsune
 ---
 
+import { Aside } from "@astrojs/starlight/components";
+
 Kitsune requires a PostgreSQL installation that it can connect to since we make usage of Postgres-specific features, such as their full-text search.
 
 You can find instructions on creating a database (along with password-protected user) [here](https://medium.com/coding-blocks/creating-user-database-and-adding-access-on-postgresql-8bfcd2f4a91e).
 
-> We supported SQLite in the past (before v0.0.1-pre.1), but the support has been dropped due to a high maintenance burden and rather little expected usage.
+<Aside>
+  We supported SQLite in the past (before v0.0.1-pre.1) but the support has been
+  dropped due to a high maintenance burden and rather little expected usage.
+</Aside>
 
 ## Database URL structure
 

web/src/content/docs/configuration/instance.mdx

@@ -3,6 +3,8 @@ title: Instance
 description: Configure miscellaneous aspects of your instance
 ---
 
+import { Aside } from "@astrojs/starlight/components";
+
 Kitsune has a number of configurations that change how your instance works.
 
 ```toml
@@ -32,7 +34,11 @@ For example, getting the username `äumeträ` would automatically reserve these
 
 and so on..
 
-> **Note**: This doesn't allow you to sign up with emoji, such as 🎈. It will still require your name to be alphanumeric, just in any alphabet that unicode supports!
+<Aside>
+  This doesn't allow you to sign up with emoji, such as 🎈. It will still
+  require your name to be alphanumeric, just in any alphabet that unicode
+  supports!
+</Aside>
 
 This is opt-in, since we aren't quite sure yet how other fediverse software, such as Mastodon, handles non-ASCII usernames.
 
@@ -42,9 +48,9 @@ This changes the name of the instance displayed on the landing page and returned
 
 ## `description`
 
-Similar to `name`, this setting adjusts the description on the landing page and the one returned via the metadata endpoints.
+<Aside type="tip">This field is interpreted as raw HTML</Aside>
 
-> **Note**: This field is interpreted as raw HTML
+Similar to `name`, this setting adjusts the description on the landing page and the one returned via the metadata endpoints.
 
 ## `character-limit`
 

web/src/content/docs/configuration/job-scheduler.mdx

@@ -3,6 +3,8 @@ title: Job Scheduler
 description: Configure the Job Scheduler of Kitsune
 ---
 
+import { Aside } from "@astrojs/starlight/components";
+
 Kitsune uses the database to store and retrieve jobs that have to be run.
 There are options to tune the job scheduler to your specific needs.
 
@@ -20,9 +22,12 @@ We utilize Redis streams and transactional Lua scripting to ensure no jobs are l
 
 ## `job-workers`
 
+<Aside type="caution">
+  Each activity delivery is a job, and each of the delivery jobs run multiple
+  connections concurrently. Raising this job worker limit too high without also
+  increasing the maximum file descriptors might lead to weird issues.
+</Aside>
+
 This option configures how many jobs are run concurrently at the same time.
 
 Each job is a lightweight task inside Kitsune's async runtime, so you can raise this well above what you'd raise a thread limit to.
-
-> **Caution**: Each activity delivery is a job, and each of the delivery jobs run multiple connections concurrently.
-> Raising this job worker limit too high without also increasing the maximum file descriptors might lead to weird issues.

web/src/content/docs/configuration/language-detection.mdx

@@ -3,6 +3,8 @@ title: Language detection
 description: Configure the language detection of Kitsune
 ---
 
+import { Aside } from "@astrojs/starlight/components";
+
 In order to classify posts better, Kitsune attempts to automatically guess the language a post is written in to improve the search experience by using language-specific tokenization.
 
 It can do that through a number of language detection backends.  
@@ -12,14 +14,15 @@ The currently supported backends are:
 - `whatlang`: Use the [whatlang](https://github.com/greyblake/whatlang-rs) library (recommended)
 - `whichlang`: Use the [whichlang](https://github.com/quickwit-oss/whichlang) library
 
-### Note on the backends
+<Aside>
+    In general you should prefer the `whatlang` backend as it offers reliability calculations and covers a wide range of languages.
 
-In general you should prefer the `whatlang` backend as it offers reliability calculations and covers a wide range of languages.
+    `whichlang` is generally _faster_ than `whatlang` but has less supported languages and doesn't offer any reliability calculations, meaning the classifications might be _way off_
+    and won't ever fall back on the default language.
 
-`whichlang` is generally _faster_ than `whatlang` but has less supported languages and doesn't offer any reliability calculations, meaning the classifications might be _way off_
-and won't ever fall back on the default language.
+    You probably don't want to use the `none` backend unless you are 100% confident that the language detection is too resource intensive for your installation (which is extremely unlikely!)
 
-You probably don't want to use the `none` backend unless you are 100% confident that the language detection is too resource intensive for your installation (which is extremely unlikely!)
+</Aside>
 
 ## Configuration
 

web/src/content/docs/configuration/messaging.mdx

@@ -3,7 +3,11 @@ title: Messaging
 description: Configure the internal messaging channels used by Kitsune
 ---
 
-> Note that this is currently unused configuration but required nonetheless!
+import { Aside } from "@astrojs/starlight/components";
+
+<Aside type="caution">
+  This is currently unused configuration but required nonetheless!
+</Aside>
 
 Kitsune uses messaging services to exchange events for cache invalidation, notification delivery, etc.  
 To offer flexibility and to make self-hosting as easy as possible, we have multiple such backends.

web/src/content/docs/configuration/oidc.mdx

@@ -3,7 +3,12 @@ title: OIDC (OpenID Connect)
 description: Configure the OpenID Connect support of Kitsune
 ---
 
-> This feature is gated behind the `oidc` compile-time feature (enabled by default)
+import { Aside } from "@astrojs/starlight/components";
+
+<Aside type="tip">
+  This feature is gated behind the `oidc` compile-time feature (enabled by
+  default)
+</Aside>
 
 OpenID Connect (OIDC) is a technology to provide Single Sign-On (SSO) that it shared across multiple services.
 This is useful if you, for example, want to run Kitsune together with a bunch of other services and don't want to maintain multiple logins.

web/src/content/docs/configuration/storage.mdx

@@ -3,11 +3,16 @@ title: Storage
 description: Configure the storage used by Kitsune
 ---
 
+import { Aside } from "@astrojs/starlight/components";
+
 As a microblogging platform, Kitsune also offers users the ability to attach images, videos, and audio to their posts.
 We offer multiple different storage backends to store the attachments to.
 
-> **Note**: You might want to increase the upload limit by tweaking the `max-upload-size` parameter in your configuration; the number is the upload limit in bytes.
-> The default set by the example configuration is 5MiB.
+<Aside type="tip">
+  You might want to increase the upload limit by tweaking the `max-upload-size`
+  parameter in your configuration. The default set by the example configuration
+  is 5MiB.
+</Aside>
 
 ## File System
 
@@ -63,11 +68,13 @@ These keys are given to you when creating your bucket. Make sure you keep these
 
 ### Notes on "get_object" requests
 
+<Aside type="caution">
+  This is not final, we might change how S3 uploads are handled
+</Aside>
+
 Currently Kitsune proxies all the S3 accesses, meaning each media access results in a "get object" request.  
 For example, Cloudflare R2 has a "no egress fee policy" which, due to this implementation detail, doesn't apply to Kitsune.
 
-> This is not final, we might change how S3 uploads are handled
-
 ### Migrating from file-system storage to S3
 
 The migration is pretty simple. Upload all the files from your upload directory into the S3 bucket (while preserving the same file hierarchy) and change the configuration.  

web/src/content/docs/index.mdx

@@ -14,6 +14,10 @@ hero:
     - text: Check out the code
       link: https://github.com/kitsune-soc/kitsune
       icon: external
+    - text: Configuration reference
+      link: /configuration/cache
+      icon: setting
+      variant: secondary
 ---
 
 import { Card, CardGrid } from "@astrojs/starlight/components";

web/src/content/docs/running/installation.mdx

@@ -3,6 +3,8 @@ title: Installation
 description: Install Kitsune on your own server
 ---
 
+import { Aside } from "@astrojs/starlight/components";
+
 At the moment, the only way to install Kitsune is to compile it from source.  
 Don't worry, that sounds way more scary than it actually is. In this guide we will step you through it.
 
@@ -35,15 +37,18 @@ The name of the package(s) containing these tools might differ between distribut
 
 First, grab yourself a copy of the source code. You can either download the [main branch ZIP archive](https://github.com/kitsune-soc/kitsune/archive/refs/heads/main.zip) or clone it via Git. Both ways will work just fine.
 
-> The recommended way to download the source is via Git since it makes updating and doing a rollback way easier.
+<Aside type="tip">
+  The recommended way to download the source is via Git since it makes updating
+  and doing a rollback way easier.
+</Aside>
 
 To download a Git repository, just run the following command (this assumes you have [Git](https://git-scm.com/) installed):
 
 ```bash
 git clone https://github.com/kitsune-soc/kitsune.git
 ```
 
-> If you downloaded the ZIP, just unzip the archive
+<Aside>If you downloaded the ZIP, just unzip the archive</Aside>
 
 Next, move into the newly created directory and then into the `kitsune-fe` directory and build the frontend.
 To do this run:

web/src/content/docs/spec/http-signatures.mdx

@@ -3,6 +3,8 @@ title: HTTP signatures
 description: Basic description of HTTP signatures as used by Kitsune
 ---
 
+import { Aside } from "@astrojs/starlight/components";
+
 HTTP signatures are used by Kitsune to validate that the Activity/Object actually originates from the user it claims to.  
 We implement a subset of [`draft-cavage-http-signatures-12`](https://datatracker.ietf.org/doc/html/draft-cavage-http-signatures-12) to do this.
 
@@ -16,7 +18,11 @@ The signature scheme used is inferred by the OID embedded in the public key mate
 
 At the moment, Kitsune uses RSA keys but has support for implementations that use Ed25519 for signatures.
 
-> We use RSA because Mastodon doesn't support anything else. So if you want compatibility with Mastodon, you have to use RSA.  
-> As soon as a mainline Mastodon release gets support for Ed25519 signatures, we will release an update that allows to rekey all the users.
+<Aside>
+  We use RSA because Mastodon doesn't support anything else. So if you want
+  compatibility with Mastodon, you have to use RSA. As soon as a mainline
+  Mastodon release gets support for Ed25519 signatures, we will release an
+  update that allows to rekey all the users.
+</Aside>
 
 But if you are happy to just federate with Kitsune users, you can use Ed25519!