chore(docs): clean up and add new content (#15003)

* wip: Install

* wip: sharing

* wip: features

* wip: features

* wip: tags and folder view

* update links

* fix: broken reference to page sections

* pr feedback

* Update docs/docs/overview/comparison.md

Co-authored-by: Daniel Dietzler <36593685+danieldietzler@users.noreply.github.com>

* webp

* webp is glory

* webp is glory

---------

Co-authored-by: Daniel Dietzler <36593685+danieldietzler@users.noreply.github.com>

docs/docs/install/docker-compose.mdx

@@ -30,27 +30,11 @@ wget -O .env https://github.com/immich-app/immich/releases/latest/download/examp
 
 You can alternatively download these two files from your browser and move them to the directory that you created, in which case ensure that you rename `example.env` to `.env`.
 
-:::info Optional Features
-If you intend to use hardware acceleration for transcoding or machine learning (ML), you can download now the config files you'll need, in the same way:
-
-```bash title="(Optional) Get hwaccel.transcoding.yml file"
-wget -O hwaccel.transcoding.yml https://github.com/immich-app/immich/releases/latest/download/hwaccel.transcoding.yml
-```
-
-```bash title="(Optional) Get hwaccel.ml.yml file"
-wget -O hwaccel.ml.yml https://github.com/immich-app/immich/releases/latest/download/hwaccel.ml.yml
-```
-
-:::
-
 ## Step 2 - Populate the .env file with custom values
 
-<details>
-  <summary>
-    Example <code>.env</code> content
-  </summary>
-  <CodeBlock language="bash">{ExampleEnv}</CodeBlock>
-</details>
+<CodeBlock language="bash" title="Default environmental variable content">
+  {ExampleEnv}
+</CodeBlock>
 
 - Populate `UPLOAD_LOCATION` with your preferred location for storing backup assets. It should be a new directory on the server with enough free space.
 - Consider changing `DB_PASSWORD` to a custom value. Postgres is not publically exposed, so this password is only used for local authentication.
@@ -58,20 +42,14 @@ wget -O hwaccel.ml.yml https://github.com/immich-app/immich/releases/latest/down
 - Set your timezone by uncommenting the `TZ=` line.
 - Populate custom database information if necessary.
 
-:::info Optional Features
-You can edit `docker-compose.yml` to add external libraries or enable hardware acceleration now by following [their guides](#setting-up-optional-features).
-:::
-
 ## Step 3 - Start the containers
 
-From the directory you created in Step 1 (which should now contain your customized `docker-compose.yml` and `.env` files), run this command:
+From the directory you created in Step 1 (which should now contain your customized `docker-compose.yml` and `.env` files), run the following command to start Immich as a background service:
 
-```bash title="Start the containers using docker compose command"
+```bash title="Start the containers"
 docker compose up -d
 ```
 
-This starts immich as a background service (per the `-d` flag), ensuring it restarts after system reboots or crashes (per the `restart` fields in `docker-compose.yml`).
-
 :::info Docker version
 If you get an error such as `unknown shorthand flag: 'd' in -d` or `open <location of your .env file>: permission denied`, you are probably running the wrong Docker version. (This happens, for example, with the docker.io package in Ubuntu 22.04.3 LTS.) You can correct the problem by following the complete [Docker Engine install](https://docs.docker.com/engine/install/) procedure for your distribution, crucially the "Uninstall old versions" and "Install using the apt/rpm repository" sections. These replace the distro's Docker packages with Docker's official ones.
 
@@ -89,28 +67,22 @@ See the previous paragraph about installing from the official Docker repository.
 If you get an error `can't set healthcheck.start_interval as feature require Docker Engine v25 or later`, it helps to comment out the line for `start_interval` in the `database` section of the `docker-compose.yml` file.
 :::
 
-:::tip
-For more information on how to use the application, please refer to the [Post Installation](/docs/install/post-install.mdx) guide.
-:::
-
-:::note GitHub Authentication
-Downloading container images might require you to authenticate to the GitHub Container Registry ([steps here][container-auth]).
-:::
-
 ## Next Steps
 
-### Setting Up Optional Features
+Read the [Post Installation](/docs/install/post-install.mdx) steps or setup optional features below.
 
-You can set up the following now:
+### Setting up optional features
 
-- [External Libraries](/docs/features/libraries.md)
-- [Hardware Transcoding](/docs/features/hardware-transcoding.md)
-- [Hardware-Accelerated Machine Learning](/docs/features/ml-hardware-acceleration.md)
+- [External Libraries](/docs/features/libraries.md): Adding your existing photo library to Immich
+- [Hardware Transcoding](/docs/features/hardware-transcoding.md): Speeding up video transcoding
+- [Hardware-Accelerated Machine Learning](/docs/features/ml-hardware-acceleration.md): Speeding up various machine learning tasks in Immich
 
 ### Upgrading
 
-:::danger Breaking Changes
-It is important to follow breaking updates to avoid problems. You can see versions that had breaking changes [here][breaking].
+:::danger Read the release notes
+Immich is currently under heavy development, which means you can expect [breaking changes][breaking] and bugs. Therefore, we recommend reading the release notes prior to updating and to take special care when using automated tools like [Watchtower][watchtower].
+
+You can see versions that had breaking changes [here][breaking].
 :::
 
 If `IMMICH_VERSION` is set, it will need to be updated to the latest or desired version.
@@ -123,14 +95,10 @@ docker compose pull && docker compose up -d
 
 To clean up disk space, the old version's obsolete container images can be deleted with the following command:
 
-```bash title="Delete all obsolete container images"
+```bash title="Clean up unused Docker images"
 docker image prune
 ```
 
-:::caution Automatic Updates
-Immich is currently under heavy development, which means you can expect [breaking changes][breaking] and bugs. Therefore, we recommend reading the release notes prior to updating and to take special care when using automated tools like [Watchtower][watchtower].
-:::
-
 [compose-file]: https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml
 [env-file]: https://github.com/immich-app/immich/releases/latest/download/example.env
 [watchtower]: https://containrrr.dev/watchtower/

docs/docs/install/portainer.md

@@ -13,7 +13,7 @@ Install Immich using Portainer's Stack feature.
 5. Replace `.env` with `stack.env` for all containers that need to use environment variables in the web editor.
 
 <img
-src={require('./img/dot-env.png').default}
+src={require('./img/dot-env.webp').default}
 width="50%"
 style={{border: '1px solid #ddd'}}
 alt="Dot Env Example"
@@ -22,7 +22,7 @@ alt="Dot Env Example"
 8. Click on "**Advanced Mode**" in the **Environment Variables** section.
 
 <img
-src={require('./img/env-1.png').default}
+src={require('./img/env-1.webp').default}
 width="50%"
 style={{border: '1px solid #ddd'}}
 alt="Dot Env Example"
@@ -32,7 +32,7 @@ alt="Dot Env Example"
 10. Switch back to "**Simple Mode**".
 
 <img
-src={require('./img/env-2.png').default}
+src={require('./img/env-2.webp').default}
 width="50%"
 style={{border: '1px solid #ddd'}}
 alt="Dot Env Example"

docs/docs/install/post-install.mdx

@@ -10,19 +10,19 @@ import MobileAppLogin from '/docs/partials/_mobile-app-login.md';
 import MobileAppBackup from '/docs/partials/_mobile-app-backup.md';
 import ServerBackup from '/docs/partials/_server-backup.md';
 
-# Post Install Steps
+# Post installation steps
 
 A list of common steps to take after installing Immich include:
 
-## Step 1 - Register the Admin User
+## Step 1 - Register the admin user
 
 <RegisterAdminUser />
 
-## Step 2 - Create a New User (optional)
+## Step 2 - Create a new user (optional)
 
 <UserCreate />
 
-## Step 3 - Update the Storage Template
+## Step 3 - Update the storage template
 
 <StorageTemplate />
 

docs/docs/install/script.md

@@ -2,15 +2,19 @@
 sidebar_position: 20
 ---
 
-# Install Script [Experimental]
+# Install script [Experimental]
 
 :::caution
 This method is experimental and not currently recommended for production use. For production, please refer to installing with [Docker Compose](/docs/install/docker-compose.mdx).
 :::
 
-:::note
+## Requirements
+
+Follow the [requirements page](/docs/install/requirements) to get started.
+
 The install script only supports Linux operating systems and requires Docker to be already installed on the system.
-:::
+
+## Steps
 
 In the shell, from a directory of your choice, run the following command:
 

docs/docs/install/truenas.md

@@ -32,7 +32,7 @@ Immich requires seven datasets: `library`, `upload`, `thumbs`, `profile`, `video
 You can organize these as one parent with seven child datasets, for example `/mnt/tank/immich/library`, `/mnt/tank/immich/upload`, and so on.
 
 <img
-src={require('./img/truenas12.png').default}
+src={require('./img/truenas12.webp').default}
 width="30%"
 alt="Immich App Widget"
 className="border rounded-xl"
@@ -49,7 +49,7 @@ If the **library** dataset uses ACL it must have [ACL mode](https://www.truenas.
 To install the **Immich** application, go to **Apps**, click **Discover Apps**, either begin typing Immich into the search field or scroll down to locate the **Immich** application widget.
 
 <img
-src={require('./img/truenas01.png').default}
+src={require('./img/truenas01.webp').default}
 width="50%"
 alt="Immich App Widget"
 className="border rounded-xl"
@@ -60,7 +60,7 @@ Click on the widget to open the **Immich** application details screen.
 <br/><br/>
 
 <img
-src={require('./img/truenas02.png').default}
+src={require('./img/truenas02.webp').default}
 width="100%"
 alt="Immich App Details Screen"
 className="border rounded-xl"
@@ -76,7 +76,7 @@ To find specific fields click in the **Search Input Fields** search field, scrol
 ### Application Name and Version
 
 <img
-src={require('./img/truenas03.png').default}
+src={require('./img/truenas03.webp').default}
 width="100%"
 alt="Install Immich Screen"
 className="border rounded-xl"
@@ -92,7 +92,7 @@ The **Installed Applications** screen shows the option to update applications.
 ### Immich Configuration
 
 <img
-src={require('./img/truenas05.png').default}
+src={require('./img/truenas05.webp').default}
 width="40%"
 alt="Configuration Settings"
 className="border rounded-xl"
@@ -118,7 +118,7 @@ Leave **Additional Environment Variables** blank or see [Environment Variables](
 ### Network Configuration
 
 <img
-src={require('./img/truenas06.png').default}
+src={require('./img/truenas06.webp').default}
 width="40%"
 alt="Networking Settings"
 className="border rounded-xl"
@@ -136,7 +136,7 @@ Regardless of version, to avoid port conflicts, don't use [ports on this list](h
 Immich requires seven storage datasets.
 
 <img
-src={require('./img/truenas07.png').default}
+src={require('./img/truenas07.webp').default}
 width="20%"
 alt="Configure Storage ixVolumes"
 className="border rounded-xl"
@@ -149,7 +149,7 @@ The default setting for datasets is **ixVolume (dataset created automatically by
 For each Storage option select **Host Path (Path that already exists on the system)** and then select the matching dataset [created before installing the app](#setting-up-storage-datasets): **Immich Library Storage**: `library`, **Immich Uploads Storage**: `upload`, **Immich Thumbs Storage**: `thumbs`, **Immich Profile Storage**: `profile`, **Immich Video Storage**: `video`, **Immich Backups Storage**: `backups`, **Postgres Data Storage**: `pgData`.
 
 <img
-src={require('./img/truenas08.png').default}
+src={require('./img/truenas08.webp').default}
 width="40%"
 alt="Configure Storage Host Paths"
 className="border rounded-xl"
@@ -161,7 +161,7 @@ The image above has example values.
 ### Additional Storage [(External Libraries)](/docs/features/libraries)
 
 <img
-src={require('./img/truenas10.png').default}
+src={require('./img/truenas10.webp').default}
 width="40%"
 alt="Configure Storage Host Paths"
 className="border rounded-xl"
@@ -176,7 +176,7 @@ The **Host Path** is the location on the TrueNAS SCALE server where your externa
 ### Resources Configuration
 
 <img
-src={require('./img/truenas09.png').default}
+src={require('./img/truenas09.webp').default}
 width="40%"
 alt="Resource Limits"
 className="border rounded-xl"
@@ -203,7 +203,7 @@ The system opens the **Installed Applications** screen with the Immich app in th
 When the installation completes it changes to **Running**.
 
 <img
-src={require('./img/truenas04.png').default}
+src={require('./img/truenas04.webp').default}
 width="100%"
 alt="Immich Installed"
 className="border rounded-xl"
@@ -229,7 +229,7 @@ For more information on how to use the application once installed, please refer
 You can set [Environment Variables](/docs/install/environment-variables) by clicking **Add** on the **Additional Environment Variables** option and filling in the **Name** and **Value**.
 
 <img
-src={require('./img/truenas11.png').default}
+src={require('./img/truenas11.webp').default}
 width="40%"
 alt="Environment Variables"
 className="border rounded-xl"

docs/docs/install/unraid.md

@@ -53,19 +53,19 @@ alt="Select Plugins > Compose.Manager > Add New Stack > Label it Immich"
         <ul>
             <li>Comment out the database service</li>
             <img
-                src={require('./img/unraid02.png').default}
+                src={require('./img/unraid02.webp').default}
                 width="50%"
                 alt="Comment out database service in the compose file"
             />
             <li>Comment out the database dependency for <b>each service</b> <i>(example in screenshot below only shows 2 of the services - ensure you do this for all services)</i></li>
             <img
-                src={require('./img/unraid03.png').default}
+                src={require('./img/unraid03.webp').default}
                 width="50%"
                 alt="Comment out every reference to the database service in the compose file"
             />
             <li>Comment out the volumes</li>
             <img
-                src={require('./img/unraid04.png').default}
+                src={require('./img/unraid04.webp').default}
                 width="20%"
                 alt="Comment out database volume"
             />
@@ -111,7 +111,7 @@ alt="Go to Docker Tab and visit the address listed next to immich-web"
 
 <details >
     <summary>Using the FolderView plugin for organizing your Docker containers? Click me! Otherwise you're complete!</summary>
-    <p>If you are using the FolderView plugin go the Docker tab and select "<b>New Folder</b>".<br />Label it <i>"Immich"</i> and use this URL as the logo: https://raw.githubusercontent.com/immich-app/immich/main/design/immich-logo.png<br/>Then simply select all the Immich related containers before clicking "<b>Submit</b>"</p>
+    <p>If you are using the FolderView plugin go the Docker tab and select "<b>New Folder</b>".<br />Label it <i>"Immich"</i> and use this URL as the logo: https://raw.githubusercontent.com/immich-app/immich/main/design/immich-logo.webp<br/>Then simply select all the Immich related containers before clicking "<b>Submit</b>"</p>
     <img
         src={require('./img/unraid07.webp').default}
         width="80%"
@@ -134,14 +134,14 @@ For more information on how to use the application once installed, please refer
 Updating is extremely easy however it's important to be aware that containers managed via the Docker Compose Manager plugin do not integrate with Unraid's native dockerman UI, the label "_update ready_" will always be present on containers installed via the Docker Compose Manager.
 
 <img
-src={require('./img/unraid09.png').default}
+src={require('./img/unraid09.webp').default}
 width="50%"
 alt="Docker Compose containers always say update ready, ignore it"
 />
 
 You should ignore the "_update ready_" on the Unraid WebUI and update when you receive the notification within the Immich WebUI.
 <img
-src={require('./img/unraid10.png').default}
+src={require('./img/unraid10.webp').default}
 width="50%"
 alt="Immich update notification"
 />
@@ -151,13 +151,13 @@ alt="Immich update notification"
    > Note: **Do not** select Compose Down first, it is unnecessary.
 3. Once complete you will see a "_Connection Closed_" message, select "**Done**".
    <img
-   src={require('./img/unraid11.png').default}
+   src={require('./img/unraid11.webp').default}
    width="50%"
    alt="Wait for Connection Closed and click Done"
    />
 4. Return back to the Immich WebUI and you will see the version has been updated to the latest
    <img
-   src={require('./img/unraid12.png').default}
+   src={require('./img/unraid12.webp').default}
    width="70%"
    alt="Wait for Connection Closed and click Done"
    />