Revert "Fix: subdirectory deployment (#2205)"

This revers commit b8eda91005

.devcontainer/devcontainer.json

@@ -3,7 +3,7 @@
 	"build": {
 		"dockerfile": "Dockerfile",
 		"args": {
-			"VARIANT": "18-buster"
+			"VARIANT": "18-bullseye"
 		}
 	},
 	"customizations": {

.github/DISCUSSION_TEMPLATE/feature-requests.yml

@@ -1,5 +1,3 @@
-name: Feature request
-description: Suggest an idea for this project
 title: "[Feature Request] "
 labels: ["enhancement"]
 body:

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -1,18 +1,23 @@
 name: Bug report
 description: Create a report to help us improve
-title: "[Bug] "
-labels: ["bug"]
+title: "[Bug] Concise description of the issue"
+labels: ["bug, unconfirmed"]
 body:
   - type: markdown
     attributes:
       value: |
-        Have a question? 👉 [Start a new discussion](https://github.com/benphelps/homepage/discussions/new) or [ask in chat](https://discord.gg/SaPGSzrEZC).
+        ## ⚠️ Please remember: issues are for *bugs*
+        That is, something you believe affects every single homepage user, not just you. Otherwise, start with one of the other options below.
+  - type: markdown
+    attributes:
+      value: |
+        Have a question? 👉 [Start a new discussion](https://github.com/gethomepage/homepage/discussions/new) or [ask in chat](https://discord.gg/SaPGSzrEZC).
 
         Before opening an issue, please double check:
 
-        - [The troubleshooting guide](https://gethomepage.dev/en/more/troubleshooting/).
+        - [The troubleshooting guide](https://gethomepage.dev/latest/more/troubleshooting/).
         - [The homepage documentation](https://gethomepage.dev/)
-        - [Existing issues](https://github.com/benphelps/homepage/search?q=&type=issues) and [discussions](https://github.com/benphelps/homepage/search?q=&type=discussions).
+        - [Existing issues](https://github.com/gethomepage/homepage/search?q=&type=issues) and [discussions](https://github.com/gethomepage/homepage/search?q=&type=discussions).
   - type: textarea
     id: description
     attributes:
@@ -69,11 +74,18 @@ body:
     attributes:
       label: Browser Logs
       description: Please review and provide any logs from the browser, if relevant
+  - type: textarea
+    id: troubleshooting
+    attributes:
+      label: Troubleshooting
+      description: Please include output from your [troubleshooting tests](https://gethomepage.dev/latest/more/troubleshooting/#service-widget-errors). If this is a service widget issue and you do not include any information here your issue will be closed. If it is not, indicate e.g. 'n/a'
+    validations:
+      required: true
   - type: textarea
     id: other
     attributes:
       label: Other
-      description: Please include output from your troubleshooting tests, if relevant. Include any other relevant details. E.g. service version or API version, docker version, etc.
+      description: Include any other relevant details. E.g. service version or API version, docker version, etc.
   - type: checkboxes
     id: pre-flight
     attributes:
@@ -81,7 +93,7 @@ body:
       options:
         - label: Check [the documentation](https://gethomepage.dev/)
           required: true
-        - label: Follow [the troubleshooting guide](https://gethomepage.dev/en/more/troubleshooting/) (please include output above if applicable).
+        - label: Follow [the troubleshooting guide](https://gethomepage.dev/latest/more/troubleshooting/) (please include output above if applicable).
           required: true
-        - label: Search [existing issues](https://github.com/benphelps/homepage/search?q=&type=issues) and [discussions](https://github.com/benphelps/homepage/search?q=&type=discussions).
+        - label: Search [existing issues](https://github.com/gethomepage/homepage/search?q=&type=issues) and [discussions](https://github.com/gethomepage/homepage/search?q=&type=discussions).
           required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,11 @@
+blank_issues_enabled: false
+contact_links:
+  - name: 🤔 Questions and Help
+    url: https://github.com/gethomepage/homepage/discussions
+    about: This issue tracker is for bugs only, not general support questions. Please refer to our Discussions.
+  - name: 💬 Chat
+    url: https://discord.gg/k4ruYNrudu
+    about: Want to discuss homepage with others? Check out our chat.
+  - name: 🚀 Feature Request
+    url: https://github.com/gethomepage/homepage/discussions/new?category=feature-requests
+    about: Remember to search for existing feature requests and "up-vote" any you like

.github/PULL_REQUEST_TEMPLATE.md

@@ -3,7 +3,10 @@
 <!--
 Please include a summary of the change. Screenshots and / or videos can also be helpful if appropriate.
 
-New service widgets should include example(s) of relevant relevant API output as well as a PR to the docs for the new widget. See the development guidelines for new widgets: https://gethomepage.dev/en/more/development/#service-widget-guidelines
+*** Please see the development guidelines for new widgets: https://gethomepage.dev/latest/more/development/#service-widget-guidelines
+*** If you do not follow these guidelines your PR will likely be closed without review.
+
+New service widgets should include example(s) of relevant relevant API output as well updates to the docs for the new widget.
 -->
 
 Closes # (issue)
@@ -17,10 +20,12 @@ What type of change does your PR introduce to Homepage?
 - [ ] New service widget
 - [ ] Bug fix (non-breaking change which fixes an issue)
 - [ ] New feature (non-breaking change which adds functionality)
+- [ ] Documentation only
 - [ ] Other (please explain)
 
 ## Checklist:
 
-- [ ] If adding a service widget or a change that requires it, I have added a corresponding PR to the [documentation](https://github.com/benphelps/homepage-docs) here: 
-- [ ] If applicable, I have checked that all tests pass with e.g. `pnpm lint`.
+- [ ] If adding a service widget or a change that requires it, I have added corresponding documentation changes.
+- [ ] If adding a new widget I have reviewed the [guidelines](https://gethomepage.dev/latest/more/development/#service-widget-guidelines).
+- [ ] I have checked that all code style checks pass using pre-commit hooks and linting checks with `pnpm lint` (see development guidelines).
 - [ ] If applicable, I have tested my code for new features & regressions on both mobile & desktop devices, using the latest version of major browsers.

.github/workflows/docker-publish.yml

@@ -12,8 +12,15 @@ on:
     branches: [ "main" ]
     # Publish semver tags as releases.
     tags: [ 'v*.*.*' ]
+    paths-ignore:
+      - 'docs/**'
+      - 'mkdocs.yml'
   pull_request:
     branches: [ "main" ]
+    paths-ignore:
+      - 'docs/**'
+      - 'mkdocs.yml'
+  merge_group:
 
 env:
   # Use docker.io for Docker Hub if empty
@@ -23,9 +30,28 @@ env:
 
 
 jobs:
-  build:
+  pre-commit:
+    name: Linting Checks
+    runs-on: ubuntu-22.04
+    steps:
+      -
+        name: Checkout repository
+        uses: actions/checkout@v4
+      -
+        name: Install python
+        uses: actions/setup-python@v4
+        with:
+          python-version: 3.x
+      -
+        name: Check files
+        uses: pre-commit/action@v3.0.0
 
+  build:
+    name: Docker Build & Push
+    if:  github.repository == 'gethomepage/homepage'
     runs-on: self-hosted
+    needs:
+      - pre-commit
     permissions:
       contents: read
       packages: write
@@ -35,7 +61,7 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       # Install the cosign tool except on PR
       # https://github.com/sigstore/cosign-installer
@@ -48,12 +74,12 @@ jobs:
       # Setup QEMU
       # https://github.com/marketplace/actions/docker-setup-buildx#with-qemu
       - name: Setup QEMU
-        uses: docker/setup-qemu-action@v2
-      
+        uses: docker/setup-qemu-action@v3
+
       # Workaround: https://github.com/docker/build-push-action/issues/461
       - name: Setup Docker buildx
-        uses: docker/setup-buildx-action@v2
-        
+        uses: docker/setup-buildx-action@v3
+
       # This step is being disabled because the runner is on a self-hosted machine
       # where the cache will stick between runs.
       # - name: Cache Docker layers
@@ -68,7 +94,7 @@ jobs:
       # https://github.com/docker/login-action
       - name: Log into registry ${{ env.REGISTRY }}
         if: github.event_name != 'pull_request'
-        uses: docker/login-action@v2
+        uses: docker/login-action@v3
         with:
           registry: ${{ env.REGISTRY }}
           username: ${{ github.actor }}
@@ -78,7 +104,7 @@ jobs:
       # https://github.com/docker/metadata-action
       - name: Extract Docker metadata
         id: meta
-        uses: docker/metadata-action@v4
+        uses: docker/metadata-action@v5
         with:
           images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
           flavor: |
@@ -88,7 +114,7 @@ jobs:
       # https://github.com/docker/build-push-action
       - name: Build and push Docker image
         id: build-and-push
-        uses: docker/build-push-action@v4
+        uses: docker/build-push-action@v5
         with:
           context: .
           push: ${{ github.event_name != 'pull_request' }}

.github/workflows/docs-publish.yml

@@ -0,0 +1,100 @@
+name: Docs
+
+on:
+  push:
+    tags: [ 'v*.*.*' ]
+    branches: ['main']
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+  pull_request:
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+  merge_group:
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  pre-commit:
+    name: Linting Checks
+    runs-on: ubuntu-22.04
+    steps:
+      -
+        name: Checkout repository
+        uses: actions/checkout@v4
+      -
+        name: Install python
+        uses: actions/setup-python@v4
+        with:
+          python-version: 3.x
+      -
+        name: Check files
+        uses: pre-commit/action@v3.0.0
+
+  test:
+    name: Test Build
+    if: github.repository == 'gethomepage/homepage' && github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    needs:
+      - pre-commit
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v4
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+      - uses: actions/cache@v3
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: sudo apt-get install pngquant
+      - run: pip install mike
+      - run: pip install mkdocs-material
+      - name: Test Docs Build
+        run: MKINSIDERS=false mkdocs build
+  deploy:
+    name: Build & Deploy
+    if: github.repository == 'gethomepage/homepage' && github.event_name != 'pull_request'
+    runs-on: ubuntu-latest
+    needs:
+      - pre-commit
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: main
+      - uses: actions/setup-python@v4
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+      - uses: actions/cache@v3
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: sudo apt-get install pngquant
+      - run: pip install mike
+      - run: pip install git+https://${GH_TOKEN}@github.com/benphelps/mkdocs-material-insiders.git
+      - name: Set Git config
+        run: |
+          git config --global user.name "GitHub Action"
+          git config --global user.email "action@github.com"
+      - name: Sync gh-pages
+        run: |
+          git fetch origin gh-pages
+          git checkout gh-pages
+          git pull origin gh-pages
+          git checkout main
+      - name: Docs Deploy for Main
+        if: github.ref == 'refs/heads/main'
+        run: MKINSIDERS=true mike deploy --update --push ${{github.ref_name}}
+      - name: Docs Deploy for Tags
+        if: github.ref != 'refs/heads/main'
+        run: MKINSIDERS=true mike deploy --update --push ${{github.ref_name}} latest
+env:
+  GH_TOKEN: ${{ secrets.GH_TOKEN }}

.gitignore

@@ -4,6 +4,7 @@
 /node_modules
 /.pnp
 .pnp.js
+.pnpm-store
 
 # testing
 /coverage
@@ -45,4 +46,9 @@ next-env.d.ts
 # IDEs
 /.idea/
 
+# MkDocs documentation
+site*/
+.cache/
 
+# venv
+.venv/

.pre-commit-config.yaml

@@ -0,0 +1,19 @@
+# See https://pre-commit.com for more information
+# See https://pre-commit.com/hooks.html for more hooks
+repos:
+-   repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v3.2.0
+    hooks:
+    -   id: trailing-whitespace
+    -   id: end-of-file-fixer
+    -   id: check-yaml
+        exclude: "(^mkdocs\\.yml$)"
+    -   id: check-added-large-files
+-   repo: https://github.com/pre-commit/mirrors-prettier
+    rev: 'v3.0.3'
+    hooks:
+    -   id: prettier
+        types_or:
+          - javascript
+          - markdown
+          - jsx

.prettierrc

@@ -0,0 +1 @@
+{}

.vscode/launch.json

@@ -16,4 +16,4 @@
       }
     }
   ]
-}
+}

.vscode/settings.json

@@ -2,5 +2,18 @@
     "files.exclude": {
         "**/.next": true,
         "**/node_modules": true
-    }
-}
+    },
+    "yaml.schemas": {
+        "https://squidfunk.github.io/mkdocs-material/schema.json": "mkdocs.yml"
+    },
+    "yaml.customTags": [
+        "!ENV scalar",
+        "!ENV sequence",
+        "tag:yaml.org,2002:python/name:material.extensions.emoji.to_svg",
+        "tag:yaml.org,2002:python/name:material.extensions.emoji.twemoji",
+        "tag:yaml.org,2002:python/name:pymdownx.superfences.fence_code_format"
+    ],
+    "[python]": {
+        "editor.defaultFormatter": "ms-python.autopep8"
+    },
+}

CODE_OF_CONDUCT.md

@@ -17,23 +17,23 @@ diverse, inclusive, and healthy community.
 Examples of behavior that contributes to a positive environment for our
 community include:
 
-* Demonstrating empathy and kindness toward other people
-* Being respectful of differing opinions, viewpoints, and experiences
-* Giving and gracefully accepting constructive feedback
-* Accepting responsibility and apologizing to those affected by our mistakes,
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes,
   and learning from the experience
-* Focusing on what is best not just for us as individuals, but for the
+- Focusing on what is best not just for us as individuals, but for the
   overall community
 
 Examples of unacceptable behavior include:
 
-* The use of sexualized language or imagery, and sexual attention or
+- The use of sexualized language or imagery, and sexual attention or
   advances of any kind
-* Trolling, insulting or derogatory comments, and personal or political attacks
-* Public or private harassment
-* Publishing others' private information, such as a physical or email
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email
   address, without their explicit permission
-* Other conduct which could reasonably be considered inappropriate in a
+- Other conduct which could reasonably be considered inappropriate in a
   professional setting
 
 ## Enforcement Responsibilities
@@ -106,7 +106,7 @@ Violating these terms may lead to a permanent ban.
 ### 4. Permanent Ban
 
 **Community Impact**: Demonstrating a pattern of violation of community
-standards, including sustained inappropriate behavior,  harassment of an
+standards, including sustained inappropriate behavior, harassment of an
 individual, or aggression toward or disparagement of classes of individuals.
 
 **Consequence**: A permanent ban from any sort of public interaction within

CONTRIBUTING.md

@@ -1,4 +1,5 @@
 # Contributing to Homepage
+
 We love your input! We want to make contributing to this project as easy and transparent as possible, whether it's:
 
 - Reporting a bug
@@ -8,16 +9,20 @@ We love your input! We want to make contributing to this project as easy and tra
 - Becoming a maintainer
 
 ## We Develop with Github
+
 We use github to host code, to track issues and feature requests, as well as accept pull requests.
 
 ## Any contributions you make will be under the GNU General Public License v3.0
+
 In short, when you submit code changes, your submissions are understood to be under the same [GNU General Public License v3.0](https://choosealicense.com/licenses/gpl-3.0/) that covers the project. Feel free to contact the maintainers if that's a concern.
 
-## Report bugs using Github's [issues](https://github.com/benphelps/homepage/issues)
-We use GitHub issues to track public bugs. Report a bug by [opening a new issue](https://github.com/benphelps/homepage/issues/new); it's that easy!
+## Report bugs using Github's [issues](https://github.com/gethomepage/homepage/issues)
+
+We use GitHub issues to track public bugs. Report a bug by [opening a new issue](https://github.com/gethomepage/homepage/issues/new); it's that easy!
 
 ## Write bug reports with detail, background, and sample configurations
-Homepage includes a lot of configuration options and is often deploying in larger systems.  Please include as much information (configurations, deployment method, Docker & API versions, etc) as you can when reporting an issue.
+
+Homepage includes a lot of configuration options and is often deploying in larger systems. Please include as much information (configurations, deployment method, Docker & API versions, etc) as you can when reporting an issue.
 
 **Great Bug Reports** tend to have:
 
@@ -29,13 +34,20 @@ Homepage includes a lot of configuration options and is often deploying in large
 - What actually happens
 - Notes (possibly including why you think this might be happening, or stuff you tried that didn't work)
 
-People *love* thorough bug reports. I'm not even kidding.
+People _love_ thorough bug reports. I'm not even kidding.
+
+## Development Guidelines
+
+Please see the [documentation regarding development](https://gethomepage.dev/latest/more/development/) and specifically the [guidelines for new service widgets](https://gethomepage.dev/latest/more/development/#service-widget-guidelines) if you are considering making one.
 
 ## Use a Consistent Coding Style
-This project follows the [Airbnb JavaScript Style Guide](https://github.com/airbnb/javascript), please follow it when submitting pull requests.
+
+Please see information in the docs regarding [code formatting with pre-commit hooks](https://gethomepage.dev/latest/more/development.md#code-formatting-with-pre-commit-hooks).
 
 ## License
+
 By contributing, you agree that your contributions will be licensed under its GNU General Public License.
 
 ## References
+
 This document was adapted from the open-source contribution guidelines for [Facebook's Draft](https://github.com/facebook/draft-js/blob/main/CONTRIBUTING.md)

Dockerfile

@@ -29,16 +29,16 @@ COPY . .
 
 SHELL ["/bin/ash", "-xeo", "pipefail", "-c"]
 RUN npm run telemetry \
- && mkdir config && echo '---' > config/settings.yaml \
+ && mkdir config \
  && NEXT_PUBLIC_BUILDTIME=$BUILDTIME NEXT_PUBLIC_VERSION=$VERSION NEXT_PUBLIC_REVISION=$REVISION npm run build
 
 # Production image, copy all the files and run next
 FROM docker.io/node:18-alpine AS runner
 LABEL org.opencontainers.image.title "Homepage"
 LABEL org.opencontainers.image.description "A self-hosted services landing page, with docker and service integrations."
-LABEL org.opencontainers.image.url="https://github.com/benphelps/homepage"
-LABEL org.opencontainers.image.documentation='https://github.com/benphelps/homepage/wiki'
-LABEL org.opencontainers.image.source='https://github.com/benphelps/homepage'
+LABEL org.opencontainers.image.url="https://github.com/gethomepage/homepage"
+LABEL org.opencontainers.image.documentation='https://github.com/gethomepage/homepage/wiki'
+LABEL org.opencontainers.image.source='https://github.com/gethomepage/homepage'
 LABEL org.opencontainers.image.licenses='Apache-2.0'
 
 ENV NODE_ENV production

README.md

@@ -6,72 +6,60 @@
 </p>
 
 <p align="center">
-  A modern <em>(fully static, fast)</em>, secure <em>(fully proxied)</em>, highly customizable application dashboard with integrations for more than 25 services and translations for over 15 languages. Easily configured via YAML files (or discovery via docker labels).
+  A modern, <em>fully static, fast</em>, secure <em>fully proxied</em>, highly customizable application dashboard with integrations for over 100 services and translations into multiple languages. Easily configured via YAML files or through docker label discovery.
 </p>
 
 <p align="center">
-  <img src="images/1.png" />
+  <img src="images/1.png?v=2" />
 </p>
 
 <p align="center">
-  <img src="images/2.png" width="19%" />
-  <img src="images/3.png" width="19%" />
-  <img src="images/4.png" width="19%" />
-  <img src="images/5.png" width="19%" />
-  <img src="images/6.png" width="19%" />
+  <a href="https://github.com/gethomepage/homepage/actions/workflows/docker-publish.yml"><img alt="GitHub Workflow Status (with event)" src="https://img.shields.io/github/actions/workflow/status/gethomepage/homepage/docker-publish.yml"></a>
+  &nbsp;
+  <a href="https://crowdin.com/project/gethomepage" target="_blank"><img src="https://badges.crowdin.net/gethomepage/localized.svg"></a>
+  &nbsp;
+  <a href="https://discord.gg/k4ruYNrudu"><img alt="Discord" src="https://img.shields.io/discord/1019316731635834932"></a>
+  &nbsp;
+  <a href="http://gethomepage.dev/latest/" title="Docs"><img title="Docs" src="https://github.com/gethomepage/homepage/actions/workflows/docs-publish.yml/badge.svg"/></a>
+  &nbsp;
+  <a href="https://paypal.me/phelpsben" title="Donate"><img alt="GitHub Sponsors" src="https://img.shields.io/github/sponsors/benphelps"></a>
 </p>
 
-<p align="center">
-  <a href="https://discord.gg/k4ruYNrudu"><img src="https://img.shields.io/badge/Discord - Chat-blue?logo=discord&logoColor=white" /></a>
-  <a href="https://paypal.me/phelpsben" title="Donate"><img src="https://img.shields.io/badge/PayPal - Donate-blue?logo=paypal&logoColor=white" alt="Linkedin - phelpsben"></a>
-</p>
+# Features
 
-<p align="center">
-  <a href="https://github.com/benphelps/homepage/actions/workflows/docker-publish.yml"><img src="https://github.com/benphelps/homepage/actions/workflows/docker-publish.yml/badge.svg" alt="Docker"></a>
-  <a href="https://hosted.weblate.org/engage/homepage/"><img src="https://hosted.weblate.org/widgets/homepage/-/homepage/svg-badge.svg" alt="Weblate"></a>
-</p>
+With features like quick search, bookmarks, weather support, a wide range of integrations and widgets, an elegant and modern design, and a focus on performance, Homepage is your ideal start to the day and a handy companion throughout it.
 
-## Features
+- **Fast** - The site is statically generated at build time for instant load times.
+- **Secure** - All API requests to backend services are proxied, keeping your API keys hidden. Constantly reviewed for security by the community.
+- **For Everyone** - Images built for AMD64, ARM64, ARMv7, and ARMv6.
+- **Full i18n** - Support for over 40 languages.
+- **Service & Web Bookmarks** - Add custom links to the homepage.
+- **Docker Integration** - Container status and stats. Automatic service discovery via labels.
+- **Service Integration** - Over 100 service integrations, including popular starr and self-hosted apps.
+- **Information & Utility Widgets** - Weather, time, date, search, and more.
+- **And much more...**
 
-- **Fast!** The entire site is statically generated at build time, so you can expect instant load times
-- **Secure!** Every API request to backend services goes through a proxy server, so your API keys are never exposed to the frontend client.
-- Images built for AMD64 (x86_64), ARM64, ARMv7 and ARMv6
-  - Supports all Raspberry Pi's, most SBCs & Apple Silicon
-- Full i18n support with automatic language detection
-  - Translations for Catalan, Chinese, Dutch, Finnish, French, German, Hebrew, Hungarian, Malay, Norwegian Bokmål, Polish, Portuguese, Portuguese (Brazil), Romanian, Russian, Spanish, Swedish and Yue
-  - Want to help translate? [Join the Weblate project](https://hosted.weblate.org/engage/homepage/)
-- Service & Web Bookmarks
-- Docker Integration
-  - Container status (Running / Stopped) & statistics (CPU, Memory, Network)
-  - Automatic service discovery (via labels)
-- Service Integration
-  - Sonarr, Radarr, Readarr, Prowlarr, Bazarr, Lidarr, Emby, Jellyfin, Tautulli, Plex and more
-  - Ombi, Overseerr, Jellyseerr, Jackett, NZBGet, SABnzbd, ruTorrent, Transmission, qBittorrent and more
-  - Portainer, Traefik, Speedtest Tracker, PiHole, AdGuard Home, Nginx Proxy Manager, Gotify, Syncthing Relay Server, Authentik, Proxmox and more
-- Information Providers
-  - Coin Market Cap, Mastodon and more
-- Information & Utility Widgets
-  - System Stats (Disk, CPU, Memory)
-  - Weather via [OpenWeatherMap](https://openweathermap.org/) or [Open-Meteo](https://open-meteo.com/)
-  - Web Search Bar
-  - UniFi Console, Glances and more
-- Instant "Quick-launch" search
-- Customizable
-  - 21 theme colors with light and dark mode support
-  - Background image support
-  - Column and Row layout options
+## Docker Integration
 
-## Support & Suggestions
+Homepage has built-in support for Docker, and can automatically discover and add services to the homepage based on labels. See the [Docker](https://gethomepage.dev/latest/installation/docker/) page for more information.
 
-If you have any questions, suggestions, or general issues, please start a discussion on the [Discussions](https://github.com/benphelps/homepage/discussions) page.
+## Service Widgets
 
-For bug reports, please open an issue on the [Issues](https://github.com/benphelps/homepage/issues) page.
+Homepage also has support for over 100 3rd party services, including all popular starr apps, and most popular self-hosted apps. Some examples include: Radarr, Sonarr, Lidarr, Bazarr, Ombi, Tautulli, Plex, Jellyfin, Emby, Transmission, qBittorrent, Deluge, Jackett, NZBGet, SABnzbd, etc. As well as service integrations, Homepage also has a number of information providers, sourcing information from a variety of external 3rd party APIs. See the [Service](https://gethomepage.dev/latest/configs/service-widgets/) page for more information.
 
-## Getting Started
+## Information Widgets
 
-For configuration options, examples and more, [please check out the homepage site](http://gethomepage.dev).
+Homepage has built-in support for a number of information providers, including weather, time, date, search, glances and more. System and status information presented at the top of the page. See the [Information Providers](https://gethomepage.dev/latest/configs/widgets/) page for more information.
 
-### With Docker
+## Customization
+
+Homepage is highly customizable, with support for custom themes, custom CSS & JS, custom layouts, formatting, localization and more. See the [Settings](https://gethomepage.dev/latest/configs/settings/) page for more information.
+
+# Getting Started
+
+For configuration options, examples and more, [please check out the homepage documentation](http://gethomepage.dev).
+
+## With Docker
 
 Using docker compose:
 
@@ -79,27 +67,38 @@ Using docker compose:
 version: "3.3"
 services:
   homepage:
-    image: ghcr.io/benphelps/homepage:latest
+    image: ghcr.io/gethomepage/homepage:latest
     container_name: homepage
+    environment:
+      PUID: 1000 -- optional, your user id
+      PGID: 1000 -- optional, your group id
     ports:
       - 3000:3000
     volumes:
       - /path/to/config:/app/config # Make sure your local config directory exists
-      - /var/run/docker.sock:/var/run/docker.sock:ro # (optional) For docker integrations
+      - /var/run/docker.sock:/var/run/docker.sock:ro # optional, for docker integrations
+    restart: unless-stopped
 ```
 
 or docker run:
 
 ```bash
-docker run -p 3000:3000 -v /path/to/config:/app/config -v /var/run/docker.sock:/var/run/docker.sock ghcr.io/benphelps/homepage:latest
+docker run --name homepage \
+  -e PUID=1000 \
+  -e PGID=1000 \
+  -p 3000:3000 \
+  -v /path/to/config:/app/config \
+  -v /var/run/docker.sock:/var/run/docker.sock:ro \
+  --restart unless-stopped \
+  ghcr.io/gethomepage/homepage:latest
 ```
 
-### With Node
+## With Node
 
 First, clone the repository:
 
 ```bash
-git clone https://github.com/benphelps/homepage.git
+git clone https://github.com/gethomepage/homepage.git
 ```
 
 Then install dependencies and build the production bundle (I'm using pnpm here, you can use npm or yarn if you like):
@@ -111,22 +110,23 @@ pnpm build
 
 If this is your first time starting, copy the `src/skeleton` directory to `config/` to populate initial example config files.
 
-Finally, run the server:
+Finally, run the server in production mode:
 
 ```bash
 pnpm start
 ```
 
-## Configuration
+or development mode:
 
-Configuration files will be generated and placed on the first request.
+```bash
+pnpm dev
+```
 
-Configuration is done in the /config directory using .yaml files. Refer to each config for
-the specific configuration options.
+# Configuration
 
-You may also check [the homepage site](http://gethomepage.dev) for detailed configuration instructions, examples and more.
+Please refer to the [homepage documentation](https://gethomepage.dev/) website for more information. Everything you need to know about configuring Homepage is there. Please read everything carefully before asking for help, as most questions are answered there or are simple YAML configuration issues.
 
-## Development
+# Development
 
 Install NPM packages, this project uses [pnpm](https://pnpm.io/) (and so should you!):
 
@@ -142,21 +142,34 @@ pnpm dev
 
 Open [http://localhost:3000](http://localhost:3000) to start.
 
-This is a [Next.js](https://nextjs.org/) application, see their doucmentation for more information:
+This is a [Next.js](https://nextjs.org/) application, see their documentation for more information.
 
-## Contributors
+# Documentation
 
-<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
-<!-- prettier-ignore-start -->
-<!-- markdownlint-disable -->
+The homepage documentation is available at [https://gethomepage.dev/](https://gethomepage.dev/).
 
-<!-- markdownlint-restore -->
-<!-- prettier-ignore-end -->
+Homepage uses Material for MkDocs for documentation. To run the documentation locally, first install the dependencies:
 
-<!-- ALL-CONTRIBUTORS-LIST:END -->
+```bash
+pip install -r requirements.txt
+```
 
+Then run the development server:
 
+```bash
+mkdocs serve # or build, to build the static site
+```
 
-<!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
-[![All Contributors](https://img.shields.io/badge/all_contributors-13-orange.svg?style=flat-square)](#contributors)
-<!-- ALL-CONTRIBUTORS-BADGE:END -->
+# Support & Suggestions
+
+If you have any questions, suggestions, or general issues, please start a discussion on the [Discussions](https://github.com/gethomepage/homepage/discussions) page.
+
+For bug reports, please open an issue on the [Issues](https://github.com/gethomepage/homepage/issues) page.
+
+## Contributing & Contributers
+
+Contributions are welcome! Please see the [CONTRIBUTING.md](CONTRIBUTING.md) file for more information.
+
+Thanks to the over 200 contributors who have helped make this project what it is today!
+
+Especially huge thanks to [@shamoon](https://github.com/shamoon), who has been the backbone of this community from the very start.

crowdin.yml

@@ -0,0 +1,3 @@
+files:
+  - source: /public/locales/en/*.json
+    translation: /public/locales/%osx_locale%/%original_file_name%

docker-entrypoint.sh

@@ -10,6 +10,8 @@ export PGID=${PGID:-0}
 # while also supporting the lscr.io /config directory
 [ ! -d "/app/config" ] && ln -s /config /app/config
 
+export HOMEPAGE_BUILDTIME=$(date +%s)
+
 # Set privileges for /app but only if pid 1 user is root and we are dropping privileges.
 # If container is run as an unprivileged user, it means owner already handled ownership setup on their own.
 # Running chown in that case (as non-root) will cause error

docs/assets/custom.css

@@ -0,0 +1,3 @@
+.md-typeset[data-page-id="landing"] .md-header-anchor {
+    display: none;
+}

docs/configs/bookmarks.md

@@ -0,0 +1,32 @@
+---
+title: Bookmarks
+description: Bookmark Configuration
+---
+
+Bookmarks function much the same as [Services](services.md), in how groups and lists work. They're just much simpler, smaller, and contain no extra features other than being a link out.
+
+The design of homepage expects `abbr` to be 2 letters, but is not otherwise forced.
+
+You can also use an icon for bookmarks similar to the [options for service icons](services.md#icons). If both icon and abbreviation are supplied, the icon takes precedence.
+
+By default, the description will use the hostname of the link, but you can override it with a custom description.
+
+```yaml
+- Developer:
+    - Github:
+        - abbr: GH
+          href: https://github.com/
+
+- Social:
+    - Reddit:
+        - icon: reddit.png
+          href: https://reddit.com/
+          description: The front page of the internet
+
+- Entertainment:
+    - YouTube:
+        - abbr: YT
+          href: https://youtube.com/
+```
+
+<img width="1000" alt="Bookmarks" src="https://user-images.githubusercontent.com/19408/269307009-d7e45885-230f-4e07-b421-9822017ae878.png">

docs/configs/custom-css-js.md

@@ -0,0 +1,17 @@
+---
+title: Custom CSS & JS
+description: Adding Custom CSS or JS
+---
+
+As of version v0.6.30 homepage supports adding your own custom css & javascript. Please do so **at your own risk**.
+
+To add custom css simply edit the `custom.css` file under your config directory, similarly for javascript you would edit `custom.js`. You can then target elements in homepage with various classes / ids to customize things to your liking.
+
+You can also set a specific `id` for a service or bookmark to target with your custom css or javascript, e.g.
+
+```yaml
+Service:
+    id: myserviceid
+    icon: icon.png
+    ...
+```

docs/configs/docker.md

@@ -0,0 +1,222 @@
+---
+title: Docker
+description: Docker Configuration
+---
+
+Docker instances are configured inside the `docker.yaml` file. Both IP:PORT and Socket connections are supported.
+
+For IP:PORT, simply make sure your Docker instance [has been configured](https://gist.github.com/styblope/dc55e0ad2a9848f2cc3307d4819d819f) to accept API traffic over the HTTP API.
+
+```yaml
+my-remote-docker:
+  host: 192.168.0.101
+  port: 2375
+```
+
+## Using Docker TLS
+
+Since Docker supports connecting with TLS and client certificate authentication, you can include TLS details when connecting to the HTTP API. Further details of setting up Docker to accept TLS connections, and generation of the keys and certs can be found [in the Docker documentation](https://docs.docker.com/engine/security/protect-access/#use-tls-https-to-protect-the-docker-daemon-socket). The file entries are relative to the `config` directory (location of `docker.yaml` file).
+
+```yaml
+my-remote-docker:
+  host: 192.168.0.101
+  port: 275
+  tls:
+    keyFile: tls/key.pem
+    caFile: tls/ca.pem
+    certFile: tls/cert.pem
+```
+
+## Using Docker Socket Proxy
+
+Due to security concerns with exposing the docker socket directly, you can use a [docker-socket-proxy](https://github.com/Tecnativa/docker-socket-proxy) container to expose the docker socket on a more restricted and secure API.
+
+Here is an example docker-compose file that will expose the docker socket, and then connect to it from the homepage container:
+
+```yaml
+dockerproxy:
+  image: ghcr.io/tecnativa/docker-socket-proxy:latest
+  container_name: dockerproxy
+  environment:
+    - CONTAINERS=1 # Allow access to viewing containers
+    - SERVICES=1 # Allow access to viewing services (necessary when using Docker Swarm)
+    - TASKS=1 # Allow access to viewing tasks (necessary when using Docker Swarm)
+    - POST=0 # Disallow any POST operations (effectively read-only)
+  ports:
+    - 127.0.0.1:2375:2375
+  volumes:
+    - /var/run/docker.sock:/var/run/docker.sock:ro # Mounted as read-only
+  restart: unless-stopped
+
+homepage:
+  image: ghcr.io/gethomepage/homepage:latest
+  container_name: homepage
+  volumes:
+    - /path/to/config:/app/config
+  ports:
+    - 3000:3000
+  restart: unless-stopped
+```
+
+Then, inside of your `docker.yaml` settings file, you'd configure the docker instance like so:
+
+```yaml
+my-docker:
+  host: dockerproxy
+  port: 2375
+```
+
+## Using Socket Directly
+
+If you'd rather use the socket directly, first make sure that you're passing the local socket into the Docker container.
+
+!!! note
+
+    In order to use the socket directly homepage must be running as root
+
+```yaml
+homepage:
+  image: ghcr.io/gethomepage/homepage:latest
+  container_name: homepage
+  volumes:
+    - /path/to/config:/app/config
+    - /var/run/docker.sock:/var/run/docker.sock # pass local proxy
+  ports:
+    - 3000:3000
+  restart: unless-stopped
+```
+
+If you're using `docker run`, this would be `-v /var/run/docker.sock:/var/run/docker.sock`.
+
+Then, inside of your `docker.yaml` settings file, you'd configure the docker instance like so:
+
+```yaml
+my-docker:
+  socket: /var/run/docker.sock
+```
+
+## Services
+
+Once you've configured your docker instances, you can then apply them to your services, to get stats and status reporting shown.
+
+Inside of the service you'd like to connect to docker:
+
+```yaml
+- Emby:
+  icon: emby.png
+  href: "http://emby.home/"
+  description: Media server
+  server: my-docker # The docker server that was configured
+  container: emby # The name of the container you'd like to connect
+```
+
+## Automatic Service Discovery
+
+Homepage features automatic service discovery for containers with the proper labels attached, all configuration options can be applied using dot notation, beginning with `homepage`.
+
+Below is an example of the same service entry shown above, as docker labels.
+
+```yaml
+services:
+  emby:
+    image: lscr.io/linuxserver/emby:latest
+    container_name: emby
+    ports:
+      - 8096:8096
+    restart: unless-stopped
+    labels:
+      - homepage.group=Media
+      - homepage.name=Emby
+      - homepage.icon=emby.png
+      - homepage.href=http://emby.home/
+      - homepage.description=Media server
+```
+
+When your Docker instance has been properly configured, this service will be automatically discovered and added to your Homepage. **You do not need to specify the `server` or `container` values, as they will be automatically inferred.**
+
+**When using docker swarm use _deploy/labels_**
+
+## Widgets
+
+You may also configure widgets, along with the standard service entry, again, using dot notation.
+
+```yaml
+labels:
+  - homepage.group=Media
+  - homepage.name=Emby
+  - homepage.icon=emby.png
+  - homepage.href=http://emby.home/
+  - homepage.description=Media server
+  - homepage.widget.type=emby
+  - homepage.widget.url=http://emby.home
+  - homepage.widget.key=yourembyapikeyhere
+  - homepage.widget.fields=["field1","field2"] # optional
+```
+
+You can add specify fields for e.g. the [CustomAPI](/widgets/services/customapi) widget by using array-style dot notation:
+
+```yaml
+labels:
+  - homepage.group=Media
+  - homepage.name=Emby
+  - homepage.icon=emby.png
+  - homepage.href=http://emby.home/
+  - homepage.description=Media server
+  - homepage.widget.type=customapi
+  - homepage.widget.url=http://argus.service/api/v1/service/summary/emby
+  - homepage.widget.field[0].label=Deployed Version
+  - homepage.widget.field[0].field.status=deployed_version
+  - homepage.widget.field[1].label=Latest Version
+  - homepage.widget.field[1].field.status=latest_version
+```
+
+## Docker Swarm
+
+Docker swarm is supported and Docker services are specified with the same `server` and `container` notation. To enable swarm support you will need to include a `swarm` setting in your docker.yaml, e.g.
+
+```yaml
+my-docker:
+  socket: /var/run/docker.sock
+  swarm: true
+```
+
+For the automatic service discovery to discover all services it is important that homepage should be deployed on a manager node. Set deploy requirements to the master node in your stack yaml config, e.g.
+
+```yaml
+....
+  deploy:
+    placement:
+      constraints:
+        - node.role == manager
+...
+```
+
+In order to detect every service within the Docker swarm it is necessary that service labels should be used and not container labels. Specify the homepage labels as:
+
+```yaml
+....
+  deploy:
+    labels:
+      - homepage.icon=foobar
+...
+```
+
+## Ordering
+
+As of v0.6.4 discovered services can include an optional `weight` field to determine sorting such that:
+
+- Default weight for discovered services is 0
+- Default weight for configured services is their index within their group scaled by 100, i.e. (index + 1) \* 100
+- If two items have the same weight value, then they will be sorted by name
+
+## Show stats
+
+You can show the docker stats by clicking the status indicator but this can also be controlled per-service with:
+
+```yaml
+- Example Service:
+  ...
+  showStats: true
+```
+
+Also see the settings for [show docker stats](docker.md#show-docker-stats).

docs/configs/index.md

@@ -0,0 +1,16 @@
+---
+title: Configuration
+description: Homepage Configuration
+---
+
+Homepage uses YAML for configuration, YAML stands for "YAML Ain't Markup Language.". It's a human-readable data serialization format that's a superset of JSON. Great for config files, easy to read and write. Supports complex data types like lists and objects. **Indentation matters.** If you already use Docker Compose, you already use YAML.
+
+Here are some tips when writing YAML:
+
+1. **Use Indentation Carefully**: YAML relies on indentation, not brackets.
+2. Avoid Tabs: Stick to spaces for indentation to avoid parsing errors. 2 spaces are common.
+3. Quote Strings: Use single or double quotes for strings with special characters, this is especially important for API keys.
+4. Key-Value Syntax: Use key: value format. Colon must be followed by a space.
+5. Validate: Always validate your YAML with a linter before deploying.
+
+You can find tons of online YAML validators, here's one: [https://codebeautify.org/yaml-validator](https://codebeautify.org/yaml-validator), heres another: [https://jsonformatter.org/yaml-validator](https://jsonformatter.org/yaml-validator).

docs/configs/kubernetes.md

@@ -0,0 +1,139 @@
+---
+title: Kubernetes
+description: Kubernetes Configuration
+---
+
+The Kubernetes connectivity has the following requirements:
+
+- Kubernetes 1.19+
+- Metrics Service
+- An Ingress controller
+
+The Kubernetes connection is configured in the `kubernetes.yaml` file. There are 3 modes to choose from:
+
+- **disabled** - disables kubernetes connectivity
+- **default** - uses the default kubeconfig [resolution](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/)
+- **cluster** - uses a service account inside the cluster
+
+```yaml
+mode: default
+```
+
+## Services
+
+Once the Kubernetes connection is configured, individual services can be configured to pull statistics. Only CPU and Memory are currently supported.
+
+Inside of the service you'd like to connect to a pod:
+
+```yaml
+- Emby:
+  icon: emby.png
+  href: "http://emby.home/"
+  description: Media server
+  namespace: media # The kubernetes namespace the app resides in
+  app: emby # The name of the deployed app
+```
+
+The `app` field is used to create a label selector, in this example case it would match pods with the label: `app.kubernetes.io/name=emby`.
+
+Sometimes this is insufficient for complex or atypical application deployments. In these cases, the `pod-selector` field can be used. Any field selector can be used with it, so it allows for some very powerful selection capabilities.
+
+For instance, it can be utilized to roll multiple underlying deployments under one application to see a high-level aggregate:
+
+```yaml
+- Element Chat:
+    icon: matrix-light.png
+    href: https://chat.example.com
+    description: Matrix Synapse Powered Chat
+    app: matrix-element
+    namespace: comms
+    pod-selector: >-
+      app.kubernetes.io/instance in (
+          matrix-element,
+          matrix-media-repo,
+          matrix-media-repo-postgresql,
+          matrix-synapse
+      )
+```
+
+!!! note
+
+    A blank string as a pod-selector does not deactivate it, but will actually select all pods in the namespace. This is a useful way to capture the resource usage of a complex application siloed to a single namespace, like Longhorn.
+
+## Automatic Service Discovery
+
+Homepage features automatic service discovery by Ingress annotations. All configuration options can be applied using typical annotation syntax, beginning with `gethomepage.dev/`.
+
+```yaml
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: emby
+  annotations:
+    gethomepage.dev/enabled: "true"
+    gethomepage.dev/description: Media Server
+    gethomepage.dev/group: Media
+    gethomepage.dev/icon: emby.png
+    gethomepage.dev/name: Emby
+    gethomepage.dev/widget.type: "emby"
+    gethomepage.dev/widget.url: "https://emby.example.com"
+    gethomepage.dev/pod-selector: ""
+    gethomepage.dev/weight: 10 # optional
+spec:
+  rules:
+    - host: emby.example.com
+      http:
+        paths:
+          - backend:
+              service:
+                name: emby
+                port:
+                  number: 8080
+            path: /
+            pathType: Prefix
+```
+
+When the Kubernetes cluster connection has been properly configured, this service will be automatically discovered and added to your Homepage. **You do not need to specify the `namespace` or `app` values, as they will be automatically inferred.**
+
+### Traefik IngressRoute support
+
+Homepage can also read ingresses defined using the Traefik IngressRoute custom resource definition. Due to the complex nature of Traefik routing rules, it is required for the `gethomepage.dev/href` annotation to be set:
+
+```yaml
+apiVersion: traefik.io/v1alpha1
+kind: IngressRoute
+metadata:
+  name: emby
+  annotations:
+    gethomepage.dev/href: "https://emby.example.com"
+    gethomepage.dev/enabled: "true"
+    gethomepage.dev/description: Media Server
+    gethomepage.dev/group: Media
+    gethomepage.dev/icon: emby.png
+    gethomepage.dev/app: emby-app # optional, may be needed if app.kubernetes.io/name != ingress metadata.name
+    gethomepage.dev/name: Emby
+    gethomepage.dev/widget.type: "emby"
+    gethomepage.dev/widget.url: "https://emby.example.com"
+    gethomepage.dev/pod-selector: ""
+    gethomepage.dev/weight: 10 # optional
+spec:
+  entryPoints:
+    - websecure
+  routes:
+    - kind: Rule
+      match: Host(`emby.example.com`)
+      services:
+        - kind: Service
+          name: emby
+          namespace: emby
+          port: 8080
+          scheme: http
+          strategy: RoundRobin
+          weight: 10
+```
+
+If the `href` attribute is not present, Homepage will ignore the specific IngressRoute.
+
+## Caveats
+
+Similarly to Docker service discovery, there currently is no rigid ordering to discovered services and discovered services will be displayed above those specified in the `services.yaml`.

docs/configs/service-widgets.md

@@ -0,0 +1,40 @@
+---
+title: Service Widgets
+description: Service Widget Configuration
+---
+
+Unless otherwise noted, URLs should not end with a `/` or other API path. Each widget will handle the path on its own.
+
+Each service can have one widget attached to it (often matching the service type, but thats not forced).
+
+In addition to the href of the service, you can also specify the target location in which to open that link. See [Link Target](settings.md#link-target) for more details.
+
+Using Emby as an example, this is how you would attach the Emby service widget.
+
+```yaml
+- Emby:
+    icon: emby.png
+    href: http://emby.host.or.ip/
+    description: Movies & TV Shows
+    widget:
+      type: emby
+      url: http://emby.host.or.ip
+      key: apikeyapikeyapikeyapikeyapikey
+```
+
+## Field Visibility
+
+Each widget can optionally provide a list of which fields should be visible via the `fields` widget property. If no fields are specified, then all fields will be displayed. The `fields` property must be a valid YAML array of strings. As an example, here is the entry for Sonarr showing only a couple of fields.
+
+**In all cases a widget will work and display all fields without specifying the `fields` property.**
+
+```yaml
+- Sonarr:
+    icon: sonarr.png
+    href: http://sonarr.host.or.ip
+    widget:
+      type: sonarr
+      fields: ["wanted", "queued"]
+      url: http://sonarr.host.or.ip
+      key: apikeyapikeyapikeyapikeyapikey
+```

docs/configs/services.md

@@ -0,0 +1,188 @@
+---
+title: Services
+description: Service Configuration
+---
+
+Services are configured inside the `services.yaml` file. You can have any number of groups, and any number of services per group.
+
+## Groups
+
+Groups are defined as top-level array entries.
+
+```yaml
+- Group A:
+    - Service A:
+        href: http://localhost/
+
+- Group B:
+    - Service B:
+        href: http://localhost/
+```
+
+<img width="1038" alt="Service Groups" src="https://user-images.githubusercontent.com/82196/187040754-28065242-4534-4409-881c-93d1921c6141.png">
+
+## Services
+
+Services are defined as array entries on groups,
+
+```yaml
+- Group A:
+    - Service A:
+        href: http://localhost/
+
+    - Service B:
+        href: http://localhost/
+
+    - Service C:
+        href: http://localhost/
+
+- Group B:
+    - Service D:
+        href: http://localhost/
+```
+
+<img width="1038" alt="Service Services" src="https://user-images.githubusercontent.com/82196/187040763-038023a2-8bee-4d87-b5cc-13447e7365a4.png">
+
+## Descriptions
+
+Services may have descriptions,
+
+```yaml
+- Group A:
+    - Service A:
+        href: http://localhost/
+        description: This is my service
+
+- Group B:
+    - Service B:
+        href: http://localhost/
+        description: This is another service
+```
+
+<img width="1038" alt="Service Descriptions" src="https://user-images.githubusercontent.com/82196/187040817-11a3d0eb-c997-4ef9-8f06-2d03a11332b6.png">
+
+## Icons
+
+Services may have an icon attached to them, you can use icons from [Dashboard Icons](https://github.com/walkxcode/dashboard-icons) automatically, by passing the name of the icon, with, or without `.png` or with `.svg` to use the svg version.
+
+You can also specify prefixed icons from [Material Design Icons](https://materialdesignicons.com) with `mdi-XX` or [Simple Icons](https://simpleicons.org/) with `si-XX`.
+
+You can specify a custom color by adding a hex color code as suffix e.g. `mdi-XX-#f0d453` or `si-XX-#a712a2`.
+
+To use a remote icon, use the absolute URL (e.g. `https://...`).
+
+To use a local icon, first create a Docker mount to `/app/public/icons` and then reference your icon as `/icons/myicon.png`. You will need to restart the container when adding new icons.
+
+!!! warning
+
+      Material Design Icons for **brands** were deprecated and may be removed in the future. Using Simple Icons for brand icons will prevent any issues if / when the Material Design Icons are removed.
+
+```yaml
+- Group A:
+    - Sonarr:
+        icon: sonarr.png
+        href: http://sonarr.host/
+        description: Series management
+
+- Group B:
+    - Radarr:
+        icon: radarr.png
+        href: http://radarr.host/
+        description: Movie management
+
+- Group C:
+    - Service:
+        icon: mdi-flask-outline
+        href: http://service.host/
+        description: My cool service
+```
+
+<img width="1038" alt="Service Icons" src="https://user-images.githubusercontent.com/82196/187040777-da1361d7-f0c4-4531-95db-136cd00a1611.png">
+
+## Ping
+
+Services may have an optional `ping` property that allows you to monitor the availability of an endpoint you chose and have the response time displayed. You do not need to set your ping URL equal to your href URL.
+
+!!! note
+
+    The ping feature works by making an http `HEAD` request to the URL, and falls back to `GET` in case that fails. It will not, for example, login if the URL requires auth or is behind e.g. Authelia. In the case of a reverse proxy and/or auth this usually requires the use of an 'internal' URL to make the ping feature correctly display status.
+
+```yaml
+- Group A:
+    - Sonarr:
+        icon: sonarr.png
+        href: http://sonarr.host/
+        ping: http://sonarr.host/
+
+- Group B:
+    - Radarr:
+        icon: radarr.png
+        href: http://radarr.host/
+        ping: http://some.other.host/
+```
+
+<img width="1038" alt="Ping" src="https://github.com/gethomepage/homepage/assets/88257202/7bc13bd3-0d0b-44e3-888c-a20e069a3233">
+
+You can also apply different styles to the ping indicator by using the `statusStyle` property, see [settings](settings.md#status-style).
+
+## Docker Integration
+
+Services may be connected to a Docker container, either running on the local machine, or a remote machine.
+
+```yaml
+- Group A:
+    - Service A:
+        href: http://localhost/
+        description: This is my service
+        server: my-server
+        container: my-container
+
+- Group B:
+    - Service B:
+        href: http://localhost/
+        description: This is another service
+        server: other-server
+        container: other-container
+```
+
+<img width="1038" alt="Service Containers" src="https://github.com/gethomepage/homepage/assets/88257202/4c685783-52c6-4e55-afb3-affe9baac09b">
+
+**Clicking on the status label of a service with Docker integration enabled will expand the container stats, where you can see CPU, Memory, and Network activity.**
+
+!!! note
+
+      This can also be controlled with `showStats`. See [show docker stats](docker.md#show-docker-stats) for more information
+
+<img width="1038" alt="Docker Stats Expanded" src="https://github.com/gethomepage/homepage/assets/88257202/f95fd595-449e-48ae-af67-fd89618904ec">
+
+## Service Integrations
+
+Services may also have a service widget (or integration) attached to them, this works independently of the Docker integration.
+
+You can find information and configuration for each of the supported integrations on the [Service Widgets](service-widgets.md) page.
+
+Here is an example of a Radarr & Sonarr service, with their respective integrations.
+
+```yaml
+- Group A:
+    - Sonarr:
+        icon: sonarr.png
+        href: http://sonarr.host/
+        description: Series management
+        widget:
+          type: sonarr
+          url: http://sonarr.host
+          key: apikeyapikeyapikeyapikeyapikey
+
+- Group B:
+    - Radarr:
+        icon: radarr.png
+        href: http://radarr.host/
+        description: Movie management
+        widget:
+          type: radarr
+          url: http://radarr.host
+          key: apikeyapikeyapikeyapikeyapikey
+```
+
+<img width="1038" alt="Service Integrations" src="https://user-images.githubusercontent.com/82196/187040838-6cd518c2-4f08-41ef-8aa6-364df5e2660e.png">

docs/configs/settings.md

@@ -0,0 +1,425 @@
+---
+title: Settings
+description: Service Configuration
+---
+
+The `settings.yaml` file allows you to define application level options. For changes made to this file to take effect, you will need to regenerate the static HTML, this can be done by clicking the refresh icon in the bottom right of the page.
+
+## Title
+
+You can customize the title of the page if you'd like.
+
+```yaml
+title: My Awesome Homepage
+```
+
+## Start URL
+
+You can customize the start_url as required for installable apps. The default is "/".
+
+```yaml
+startUrl: https://custom.url
+```
+
+## Background Image
+
+!!! warning "Heads Up!"
+
+    You will need to restart the container any time you add new images, this is a limitation of the Next.js static site server.
+
+!!! warning "Heads Up!"
+
+    Do not create a bind mount to the entire `/app/public/` directory.
+
+If you'd like to use a background image instead of the solid theme color, you may provide a full URL to an image of your choice.
+
+```yaml
+background: https://images.unsplash.com/photo-1502790671504-542ad42d5189?auto=format&fit=crop&w=2560&q=80
+```
+
+Or you may pass the path to a local image relative to e.g. `/app/public/images` directory.
+
+For example, inside of your Docker Compose file, mount a path to where your images are kept:
+
+```yaml
+volumes:
+  - /my/homepage/images:/app/public/images
+```
+
+and then reference that image:
+
+```yaml
+background: /images/background.png
+```
+
+### Background Opacity & Filters
+
+You can specify filters to apply over your background image for blur, saturation and brightness as well as opacity to blend with the background color. The first three filter settings use tailwind CSS classes, see notes below regarding the options for each. You do not need to specify all options.
+
+```yaml
+background:
+  image: /images/background.png
+  blur: sm # sm, "", md, xl... see https://tailwindcss.com/docs/backdrop-blur
+  saturate: 50 # 0, 50, 100... see https://tailwindcss.com/docs/backdrop-saturate
+  brightness: 50 # 0, 50, 75... see https://tailwindcss.com/docs/backdrop-brightness
+  opacity: 50 # 0-100
+```
+
+### Card Background Blur
+
+You can apply a blur filter to the service & bookmark cards. Note this option is incompatible with the backround blur, saturate and brightness filters.
+
+```yaml
+cardBlur: sm # sm, "", md, etc... see https://tailwindcss.com/docs/backdrop-blur
+```
+
+## Favicon
+
+If you'd like to use a custom favicon instead of the included one, you may provide a full URL to an image of your choice.
+
+```yaml
+favicon: https://www.google.com/favicon.ico
+```
+
+Or you may pass the path to a local image relative to the `/app/public` directory. See [Background Image](#background-image) for more detailed information on how to provide your own files.
+
+## Theme
+
+You can configure a fixed them (and disable the theme switcher) by passing the `theme` option, like so:
+
+```yaml
+theme: dark # or light
+```
+
+## Color Palette
+
+You can configured a fixed color palette (and disable the palette switcher) by passing the `color` option, like so:
+
+```yaml
+color: slate
+```
+
+Supported colors are: `slate`, `gray`, `zinc`, `neutral`, `stone`, `amber`, `yellow`, `lime`, `green`, `emerald`, `teal`, `cyan`, `sky`, `blue`, `indigo`, `violet`, `purple`, `fuchsia`, `pink`, `rose`, `red`, `white`
+
+## Layout
+
+You can configure service and bookmarks sections to be either "column" or "row" based layouts, like so:
+
+Assuming you have a group named `Media` in your `services.yaml` or `bookmarks.yaml` file,
+
+```yaml
+layout:
+  Media:
+    style: row
+    columns: 4
+```
+
+As an example, this would produce the following layout:
+
+<img width="1260" alt="Screenshot 2022-09-15 at 8 03 57 PM" src="https://user-images.githubusercontent.com/82196/190466646-8ca94505-0fcf-4964-9687-3a6c7cd3144f.png">
+
+### Sorting
+
+Service groups and bookmark groups can be mixed in order, **but should use different group names**. If you do not specify any bookmark groups they will all show at the bottom of the page.
+
+**_Using the same name for a service and bookmark group can cause unexpected behavior like a bookmark group being hidden_**
+
+Groups will sort based on the order in the layout block. You can also mix in groups defined by docker labels, e.g.
+
+```yaml
+layout:
+  - Auto-Discovered1:
+  - Configured1:
+  - Configured2:
+  - Auto-Discovered2:
+  - Configured3:
+      style: row
+      columns: 3
+```
+
+### Headers
+
+You can hide headers for each section in the layout as well by passing `header` as false, like so:
+
+```yaml
+layout:
+  Section A:
+    header: false
+  Section B:
+    style: row
+    columns: 3
+    header: false
+```
+
+### Category Icons
+
+You can also add an icon to a category under the `layout` setting similar to the [options for service icons](services.md#icons), e.g.
+
+```yaml
+  Home Management & Info:
+    icon: home-assistant.png
+  Server Tools:
+    icon: https://cdn-icons-png.flaticon.com/512/252/252035.png
+  ...
+```
+
+### Icon Style
+
+The default style for icons (e.g. `icon: mdi-XXXX`) is a gradient, or you can specify that prefixed icons match your theme with a 'flat' style using the setting below.
+More information about prefixed icons can be found in [options for service icons](services.md#icons).
+
+```yaml
+iconStyle: theme # optional, defaults to gradient
+```
+
+### Tabs
+
+Version 0.6.30 introduced a tabbed view to layouts which can be optionally specified in the layout. Tabs is only active if you set the `tab` field on at least one layout group.
+
+Tabs are sorted based on the order in the layout block. If a group has no tab specified (and tabs are set on other groups), services and bookmarks will be shown on all tabs.
+
+Every tab can be accessed directly by visiting Homepage URL with `#Group` (name lowercase and URI-encoded) at the end of the URL.
+
+For example, the following would create four tabs:
+
+```yaml
+layout:
+  ...
+  Bookmark Group on First Tab:
+    tab: First
+
+  First Service Group:
+    tab: First
+    style: row
+    columns: 4
+
+  Second Service Group:
+    tab: Second
+    columns: 4
+
+  Third Service Group:
+    tab: Third
+    style: row
+
+  Bookmark Group on Fourth Tab:
+    tab: Fourth
+
+  Service Group on every Tab:
+    style: row
+    columns: 4
+```
+
+### Five Columns
+
+You can add a fifth column (when `style: columns` which is default) by adding:
+
+```yaml
+fiveColumns: true
+```
+
+By default homepage will max out at 4 columns for column style
+
+### Collapsible sections
+
+You can disable the collapsible feature of services & bookmarks by adding:
+
+```yaml
+disableCollapse: true
+```
+
+By default the feature is enabled.
+
+## Header Style
+
+There are currently 4 options for header styles, you can see each one below.
+
+<img width="1000" alt="underlined" src="https://user-images.githubusercontent.com/82196/194725622-39ce271c-34e5-414d-be53-62d221811f88.png">
+
+```yaml
+headerStyle: underlined # default style
+```
+
+---
+
+<img width="1000" alt="boxed" src="https://user-images.githubusercontent.com/82196/194725645-abcb8ed9-d017-416f-9e74-cc5642fa982c.png">
+
+```yaml
+headerStyle: boxed
+```
+
+---
+
+<img width="1000" alt="clean" src="https://user-images.githubusercontent.com/82196/194725650-7a86e818-172d-4d0f-9861-5eae7fecb50a.png">
+
+```yaml
+headerStyle: clean
+```
+
+---
+
+<img width="1000" alt="boxedWidgets" src="https://user-images.githubusercontent.com/5442891/232258758-ed5262d6-f940-462c-b39e-00e54c19b9ce.png">
+
+```yaml
+headerStyle: boxedWidgets
+```
+
+## Base URL
+
+In some proxy configurations, it may be necessary to set the documents base URL. You can do this by providing a `base` value, like so:
+
+```yaml
+base: http://host.local/homepage
+```
+
+**_The URL must be a full, absolute URL, or it will be ignored by the browser._**
+
+## Language
+
+Set your desired language using:
+
+```yaml
+language: fr
+```
+
+Currently supported languages: ca, de, en, es, fr, he, hr, hu, it, nb-NO, nl, pt, ru, sv, vi, zh-CN, zh-Hant
+
+You can also specify locales e.g. for the DateTime widget, e.g. en-AU, en-GB, etc.
+
+## Link Target
+
+Changes the behaviour of links on the homepage,
+
+```yaml
+target: _blank # Possible options include _blank, _self, and _top
+```
+
+Use `_blank` to open links in a new tab, `_self` to open links in the same tab, and `_top` to open links in a new window.
+
+This can also be set for individual services. Note setting this at the service level overrides any setting in settings.json, e.g.:
+
+```yaml
+- Example Service:
+    href: https://example.com/
+    ...
+    target: _self
+```
+
+## Providers
+
+The `providers` section allows you to define shared API provider options and secrets. Currently this allows you to define your weather API keys in secret and is also the location of the Longhorn URL and credentials.
+
+```yaml
+providers:
+  openweathermap: openweathermapapikey
+  weatherapi: weatherapiapikey
+  longhorn:
+    url: https://longhorn.example.com
+    username: admin
+    password: LonghornPassword
+```
+
+You can then pass `provider` instead of `apiKey` in your widget configuration.
+
+```yaml
+- weather:
+    latitude: 50.449684
+    longitude: 30.525026
+    provider: weatherapi
+```
+
+## Quick Launch
+
+You can use the 'Quick Launch' feature to search services, perform a web search or open a URL. To use Quick Launch, just start typing while on your homepage (as long as the search widget doesnt have focus).
+
+<img width="1000" alt="quicklaunch" src="https://user-images.githubusercontent.com/4887959/216880811-90ff72cb-2990-4475-889b-7c3a31e6beef.png">
+
+There are a few optional settings for the Quick Launch feature:
+
+- `searchDescriptions`: which lets you control whether item descriptions are included in searches. This is off by default. When enabled, results that match the item name will be placed above those that only match the description.
+- `hideInternetSearch`: disable automatically including the currently-selected web search (e.g. from the widget) as a Quick Launch option. This is false by default, enabling the feature.
+- `hideVisitURL`: disable detecting and offering an option to open URLs. This is false by default, enabling the feature.
+
+```yaml
+quicklaunch:
+  searchDescriptions: true
+  hideInternetSearch: true
+  hideVisitURL: true
+```
+
+## Homepage Version
+
+By default the release version is displayed at the bottom of the page. To hide this, use the `hideVersion` setting, like so:
+
+```yaml
+hideVersion: true
+```
+
+## Log Path
+
+By default the homepage logfile is written to the a `logs` subdirectory of the `config` folder. In order to customize this path, you can set the `logpath` setting. A `logs` folder will be created in that location where the logfile will be written.
+
+```yaml
+logpath: /logfile/path
+```
+
+## Show Docker Stats
+
+You can show all docker stats expanded in `settings.yaml`:
+
+```yaml
+showStats: true
+```
+
+or per-service (`services.yaml`) with:
+
+```yaml
+- Example Service:
+    ...
+    showStats: true
+```
+
+If you have both set the per-service settings take precedence.
+
+## Status Style
+
+You can choose from the following styles for docker or k8s status and ping: `dot` or `basic`
+
+- The default is no value, and displays the ping response time in ms and the docker / k8s container status
+- `dot` shows a green dot for a successful ping or healthy status.
+- `basic` shows either UP or DOWN for ping
+
+For example:
+
+```yaml
+statusStyle: "dot"
+```
+
+or per-service (`services.yaml`) with:
+
+```yaml
+- Example Service:
+    ...
+    statusStyle: 'dot'
+```
+
+If you have both set, the per-service settings take precedence.
+
+## Hide Widget Error Messages
+
+Hide the visible API error messages either globally in `settings.yaml`:
+
+```yaml
+hideErrors: true
+```
+
+or per service widget (`services.yaml`) with:
+
+```yaml
+- Example Service:
+    ...
+    widget:
+    ...
+        hideErrors: true
+```
+
+If either value is set to true, the errror message will be hidden.

docs/index.md

@@ -0,0 +1,19 @@
+---
+title: Home
+hide:
+  - navigation
+  - toc
+  - path
+---
+
+#
+
+<div style="margin-top: -100px;"></div>
+
+<p align="center" style="max-width: 75%; margin: 0 auto; display: block;" markdown>
+![Alt text](assets/banner_dark@2x.png#only-light)
+![Alt text](assets/banner_light@2x.png#only-dark)
+
+A modern, <em>fully static, fast</em>, secure <em>fully proxied</em>, highly customizable application dashboard with integrations for over 100 services and translations into multiple languages. Easily configured via YAML files or through docker label discovery.
+
+![Alt text](assets/homepage_demo.png)

docs/installation/docker.md

@@ -0,0 +1,57 @@
+---
+title: Docker Installation
+description: Install and run homepage from Docker
+---
+
+Using docker compose:
+
+```yaml
+version: "3.3"
+services:
+  homepage:
+    image: ghcr.io/gethomepage/homepage:latest
+    container_name: homepage
+    ports:
+      - 3000:3000
+    volumes:
+      - /path/to/config:/app/config # Make sure your local config directory exists
+      - /var/run/docker.sock:/var/run/docker.sock # (optional) For docker integrations
+```
+
+### Running as non-root
+
+By default, the Homepage container runs as root. Homepage also supports running your container as non-root via the standard `PUID` and `PGID` environment variables. When using these variables, make sure that any volumes mounted in to the container have the correct ownership and permissions set.
+
+_Using the docker socket directly is not the recommended method of integration and requires either running homepage as root or that the user be part of the docker group_
+
+In the docker compose example below, the environment variables `$PUID` and `$PGID` are set in a `.env` file.
+
+```yaml
+version: "3.3"
+services:
+  homepage:
+    image: ghcr.io/gethomepage/homepage:latest
+    container_name: homepage
+    ports:
+      - 3000:3000
+    volumes:
+      - /path/to/config:/app/config # Make sure your local config directory exists
+      - /var/run/docker.sock:/var/run/docker.sock # (optional) For docker integrations, see alternative methods
+    environment:
+      PUID: $PUID
+      PGID: $PGID
+```
+
+### With Docker Run
+
+```bash
+docker run -p 3000:3000 -v /path/to/config:/app/config -v /var/run/docker.sock:/var/run/docker.sock ghcr.io/gethomepage/homepage:latest
+```
+
+### Using Environment Secrets
+
+You can also include environment variables in your config files to protect sensitive information. Note:
+
+- Environment variables must start with `HOMEPAGE_VAR_` or `HOMEPAGE_FILE_`
+- The value of env var `HOMEPAGE_VAR_XXX` will replace `{{HOMEPAGE_VAR_XXX}}` in any config
+- The value of env var `HOMEPAGE_FILE_XXX` must be a file path, the contents of which will be used to replace `{{HOMEPAGE_FILE_XXX}}` in any config

docs/installation/index.md

@@ -0,0 +1,25 @@
+---
+title: Installation
+description: Docs intro
+---
+
+<p>
+You have a few options for deploying homepage, depending on your needs. We offer docker images for a majority of platforms. You can also install and run homepage from source if Docker is not your thing. It can even be installed on Kubernetes with Helm.
+</p>
+
+<br>
+
+<div class="grid cards" style="margin: 0 auto;" markdown>
+:simple-docker: [&nbsp; Install on Docker :octicons-arrow-right-24:](docker.md)
+{ .card }
+
+:simple-kubernetes: [&nbsp; Install on Kubernetes :octicons-arrow-right-24:](k8s.md)
+{ .card }
+
+:simple-unraid: [&nbsp; Install on UNRAID :octicons-arrow-right-24:](unraid.md)
+{ .card }
+
+:simple-nextdotjs: [&nbsp; Building from source :octicons-arrow-right-24:](source.md)
+{ .card }
+
+</div>

docs/installation/k8s.md

@@ -0,0 +1,363 @@
+---
+title: Kubernetes Installation
+description: Install on Kubernetes
+---
+
+## Install with Helm
+
+There is an [unofficial helm chart](https://github.com/jameswynn/helm-charts/tree/main/charts/homepage) that creates all the necessary manifests, including the service account and RBAC entities necessary for service discovery.
+
+```sh
+helm repo add jameswynn https://jameswynn.github.io/helm-charts
+helm install homepage jameswynn/homepage -f values.yaml
+```
+
+The helm chart allows for all the configurations to be inlined directly in your `values.yaml`:
+
+```yaml
+config:
+  bookmarks:
+    - Developer:
+        - Github:
+            - abbr: GH
+              href: https://github.com/
+  services:
+    - My First Group:
+        - My First Service:
+            href: http://localhost/
+            description: Homepage is awesome
+
+    - My Second Group:
+        - My Second Service:
+            href: http://localhost/
+            description: Homepage is the best
+
+    - My Third Group:
+        - My Third Service:
+            href: http://localhost/
+            description: Homepage is 😎
+  widgets:
+    # show the kubernetes widget, with the cluster summary and individual nodes
+    - kubernetes:
+        cluster:
+          show: true
+          cpu: true
+          memory: true
+          showLabel: true
+          label: "cluster"
+        nodes:
+          show: true
+          cpu: true
+          memory: true
+          showLabel: true
+    - search:
+        provider: duckduckgo
+        target: _blank
+  kubernetes:
+    mode: cluster
+  settings:
+
+# The service account is necessary to allow discovery of other services
+serviceAccount:
+  create: true
+  name: homepage
+
+# This enables the service account to access the necessary resources
+enableRbac: true
+
+ingress:
+  main:
+    enabled: true
+    annotations:
+      # Example annotations to add Homepage to your Homepage!
+      gethomepage.dev/enabled: "true"
+      gethomepage.dev/name: "Homepage"
+      gethomepage.dev/description: "Dynamically Detected Homepage"
+      gethomepage.dev/group: "Dynamic"
+      gethomepage.dev/icon: "homepage.png"
+    hosts:
+      - host: homepage.example.com
+        paths:
+          - path: /
+            pathType: Prefix
+```
+
+## Install with Kubernetes Manifests
+
+If you don't want to use the unofficial Helm chart, you can also create your own Kubernetes manifest(s) and apply them with `kubectl apply -f filename.yaml`.
+
+Here's a working example of the resources you need:
+
+#### ServiceAccount
+
+```yaml
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: homepage
+  namespace: default
+  labels:
+    app.kubernetes.io/name: homepage
+secrets:
+  - name: homepage
+```
+
+#### Secret
+
+```yaml
+apiVersion: v1
+kind: Secret
+type: kubernetes.io/service-account-token
+metadata:
+  name: homepage
+  namespace: default
+  labels:
+    app.kubernetes.io/name: homepage
+  annotations:
+    kubernetes.io/service-account.name: homepage
+```
+
+#### ConfigMap
+
+```yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: homepage
+  namespace: default
+  labels:
+    app.kubernetes.io/name: homepage
+data:
+  kubernetes.yaml: |
+    mode: cluster
+  settings.yaml: ""
+  #settings.yaml: |
+  #  providers:
+  #    longhorn:
+  #      url: https://longhorn.my.network
+  custom.css: ""
+  custom.js: ""
+  bookmarks.yaml: |
+    - Developer:
+        - Github:
+            - abbr: GH
+              href: https://github.com/
+  services.yaml: |
+    - My First Group:
+        - My First Service:
+            href: http://localhost/
+            description: Homepage is awesome
+
+    - My Second Group:
+        - My Second Service:
+            href: http://localhost/
+            description: Homepage is the best
+
+    - My Third Group:
+        - My Third Service:
+            href: http://localhost/
+            description: Homepage is 😎
+  widgets.yaml: |
+    - kubernetes:
+        cluster:
+          show: true
+          cpu: true
+          memory: true
+          showLabel: true
+          label: "cluster"
+        nodes:
+          show: true
+          cpu: true
+          memory: true
+          showLabel: true
+    - resources:
+        backend: resources
+        expanded: true
+        cpu: true
+        memory: true
+    - search:
+        provider: duckduckgo
+        target: _blank
+  docker.yaml: ""
+```
+
+#### ClusterRole and ClusterRoleBinding
+
+```yaml
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+  name: homepage
+  labels:
+    app.kubernetes.io/name: homepage
+rules:
+  - apiGroups:
+      - ""
+    resources:
+      - namespaces
+      - pods
+      - nodes
+    verbs:
+      - get
+      - list
+  - apiGroups:
+      - extensions
+      - networking.k8s.io
+    resources:
+      - ingresses
+    verbs:
+      - get
+      - list
+  - apiGroups:
+      - traefik.containo.us
+    resources:
+      - ingressroutes
+    verbs:
+      - get
+      - list
+  - apiGroups:
+      - metrics.k8s.io
+    resources:
+      - nodes
+      - pods
+    verbs:
+      - get
+      - list
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+  name: homepage
+  labels:
+    app.kubernetes.io/name: homepage
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: ClusterRole
+  name: homepage
+subjects:
+  - kind: ServiceAccount
+    name: homepage
+    namespace: default
+```
+
+#### Service
+
+```yaml
+apiVersion: v1
+kind: Service
+metadata:
+  name: homepage
+  namespace: default
+  labels:
+    app.kubernetes.io/name: homepage
+  annotations:
+spec:
+  type: ClusterIP
+  ports:
+    - port: 3000
+      targetPort: http
+      protocol: TCP
+      name: http
+  selector:
+    app.kubernetes.io/name: homepage
+```
+
+#### Deployment
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: homepage
+  namespace: default
+  labels:
+    app.kubernetes.io/name: homepage
+spec:
+  revisionHistoryLimit: 3
+  replicas: 1
+  strategy:
+    type: RollingUpdate
+  selector:
+    matchLabels:
+      app.kubernetes.io/name: homepage
+  template:
+    metadata:
+      labels:
+        app.kubernetes.io/name: homepage
+    spec:
+      serviceAccountName: homepage
+      automountServiceAccountToken: true
+      dnsPolicy: ClusterFirst
+      enableServiceLinks: true
+      containers:
+        - name: homepage
+          image: "ghcr.io/gethomepage/homepage:latest"
+          imagePullPolicy: Always
+          ports:
+            - name: http
+              containerPort: 3000
+              protocol: TCP
+          volumeMounts:
+            - mountPath: /app/config/custom.js
+              name: homepage-config
+              subPath: custom.js
+            - mountPath: /app/config/custom.css
+              name: homepage-config
+              subPath: custom.css
+            - mountPath: /app/config/bookmarks.yaml
+              name: homepage-config
+              subPath: bookmarks.yaml
+            - mountPath: /app/config/docker.yaml
+              name: homepage-config
+              subPath: docker.yaml
+            - mountPath: /app/config/kubernetes.yaml
+              name: homepage-config
+              subPath: kubernetes.yaml
+            - mountPath: /app/config/services.yaml
+              name: homepage-config
+              subPath: services.yaml
+            - mountPath: /app/config/settings.yaml
+              name: homepage-config
+              subPath: settings.yaml
+            - mountPath: /app/config/widgets.yaml
+              name: homepage-config
+              subPath: widgets.yaml
+            - mountPath: /app/config/logs
+              name: logs
+      volumes:
+        - name: homepage-config
+          configMap:
+            name: homepage
+        - name: logs
+          emptyDir: {}
+```
+
+#### Ingress
+
+```yaml
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: homepage
+  namespace: default
+  labels:
+    app.kubernetes.io/name: homepage
+  annotations:
+    gethomepage.dev/description: Dynamically Detected Homepage
+    gethomepage.dev/enabled: "true"
+    gethomepage.dev/group: Cluster Management
+    gethomepage.dev/icon: homepage.png
+    gethomepage.dev/name: Homepage
+spec:
+  rules:
+    - host: "homepage.my.network"
+      http:
+        paths:
+          - path: "/"
+            pathType: Prefix
+            backend:
+              service:
+                name: homepage
+                port:
+                  number: 3000
+```

docs/installation/source.md

@@ -0,0 +1,25 @@
+---
+title: Source Installation
+description: Install and run homepage from source
+---
+
+First, clone the repository:
+
+```bash
+git clone https://github.com/gethomepage/homepage.git
+```
+
+Then install dependencies and build the production bundle (I'm using pnpm here, you can use npm or yarn if you like):
+
+```bash
+pnpm install
+pnpm build
+```
+
+If this is your first time starting, copy the `src/skeleton` directory to `config/` to populate initial example config files.
+
+Finally, run the server:
+
+```bash
+pnpm start
+```

docs/installation/unraid.md

@@ -0,0 +1,45 @@
+---
+title: UNRAID Installation
+description: Install and run homepage on UNRAID
+---
+
+Homepage has an UNRAID community package that you may use to install homepage. This is the easiest way to get started with homepage on UNRAID.
+
+## Install the Plugin
+
+- In the UNRAID webGUI, go to the **Apps** tab.
+- In the search bar, search for `homepage`.
+- Click on **Install**.
+- Change the parameters to your liking.
+  - Click on **APPLY**.
+
+## Run the Container
+
+- While the container is running, open the WebUI.
+  - Opening the page will generate the configuration files.
+
+You may need to set the permissions of the folders to be able to edit the files.
+
+- Click on the Homepage icon.
+- Click on **Console**.
+  - Enter `chmod -R u-x,go-rwx,go+u,ugo+X /app/config` and press **Enter**.
+  - Enter `chmod -R u-x,go-rwx,go+u,ugo+X /app/public/icons` and press **Enter**.
+  - Enter `chown -R nobody:users /app/config` and press **Enter**.
+  - Enter `chown -R nobody:users /app/public/icons` and press **Enter**.
+
+## Some Other Notes
+
+- To use the [Docker integration](../configs/docker.md), you only need to use the `container:` parameter. There is no need to set the server.
+
+  !!! note
+
+        To view detailed container statistics (CPU, RAM, etc.), or if you use a remote docker socket, `container:` will still need to be set. For example:
+
+  ```
+      - Plex:
+          icon: /icons/plex.png
+          href: https://app.plex.com
+          container: plex
+  ```
+
+- When you upload a new image into the **/images** folder, you will need to restart the container for it to show up in the WebUI. Please see the [service icons](../configs/services.md#icons) for more information.

docs/more/development.md

@@ -0,0 +1,51 @@
+---
+title: Development
+description: Homepage Development
+---
+
+## Development Overview
+
+First, clone the homepage repository.
+
+For installing NPM packages, this project uses [pnpm](https://pnpm.io/) (and so should you!):
+
+```bash
+pnpm install
+```
+
+Start the development server:
+
+```bash
+pnpm dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) to start.
+
+This is a [Next.js](https://nextjs.org/) application, see their documentation for more information.
+
+## Code Linting
+
+Once dependencies have been installed you can lint your code with
+
+```bash
+pnpm lint
+```
+
+## Code formatting with pre-commit hooks
+
+To ensure a consistent style and formatting across the project source, the project utilizes Git [`pre-commit`](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks) hooks to perform some formatting and linting before a commit is allowed.
+That way, everyone uses the same style and some common issues can be caught early on.
+
+Once installed, hooks will run when you commit. If the formatting isn't quite right or a linter catches something, the commit will be rejected.
+You'll need to look at the output and fix the issue. Some hooks will format failing files, so all you need to do is `git add` those files again
+and retry your commit.
+
+## Service Widget Guidelines
+
+To ensure cohesiveness of various widgets, the following should be used as a guide for developing new widgets:
+
+- Please only submit widgets that have been requested and have at least 5 'up-votes'
+- Widgets should be only one row of blocks
+- Widgets should be no more than 4 blocks wide
+- Minimize the number of API calls
+- Avoid the use of custom proxy unless absolutely necessary

docs/more/homepage-move.md

@@ -0,0 +1,8 @@
+---
+title: Homepage Move
+description: Homepage Container Deprecation
+---
+
+As of v0.7.2 homepage migrated from benphelps/homepage to an "organization" repository located at [gethomepage/homepage](https://github.com/gethomepage/homepage/). The reason for this was to setup the project for longevity and allow for community maintenance.
+
+Migrating your installation should be as simple as changing `image: ghcr.io/benphelps/homepage:latest` to `image: ghcr.io/gethomepage/homepage:latest`.

docs/more/index.md

@@ -0,0 +1,6 @@
+---
+title: More
+description: More homepage resources and guides.
+---
+
+Here you'll find resources and guides for Homepage, troubleshooting tips, and more.

docs/more/translations.md

@@ -0,0 +1,19 @@
+---
+title: Translations
+description: Contributing Translations
+---
+
+Homepage is developed in English, component contributions must be in English. All translations are community provided, so a huge thanks go out to all those who have helped out so far!
+
+## Support Translations
+
+If you'd like to lend a hand in translating Homepage into more languages, or to improve existing translations, the process is very simple:
+
+1. Create a free account at [Crowdin](https://crowdin.com/join)
+2. Visit the [Homepage project](https://crowdin.com/project/gethomepage)
+3. Select the language you'd like to translate
+4. Start translating!
+
+## Adding a new language
+
+If you'd like to add a new language, please [create a new Discussion on Crowdin](https://crowdin.com/project/gethomepage/discussions), and we'll add it to the project.

docs/more/troubleshooting.md

@@ -0,0 +1,66 @@
+---
+title: Troubleshooting
+description: Basic Troubleshooting
+
+hide:
+  - navigation
+---
+
+## General Troubleshooting Tips
+
+- For API errors, clicking the "API Error Information" button in the widget will usually show some helpful information as to whether the issue is reaching the service host, an authentication issue, etc.
+- Check config/logs/homepage.log, on docker simply e.g. `docker logs homepage`. This may provide some insight into the reason for an error.
+- Check the browser error console, this can also sometimes provide useful information.
+- Consider setting the `ENV` variable `LOG_LEVEL` to `debug`.
+
+## Service Widget Errors
+
+All service widgets work essentially the same, that is, homepage makes a proxied call to an API made available by that service. The majority of the time widgets don't work it is a configuration issue. Of course, sometimes things do break. Some basic steps to try:
+
+1.  Ensure that you follow the rule mentioned on https://gethomepage.dev/latest/configs/service-widgets/. **Unless otherwise noted, URLs should not end with a / or other API path. Each widget will handle the path on its own.**. This is very important as including a trailing slash can result in an error.
+
+2.  Verify the homepage installation can connect to the IP address or host you are using for the widget `url`. This is most simply achieved by pinging the server from the homepage machine, in Docker this means _from inside the container_ itself, e.g.:
+
+    ```
+    docker exec homepage ping SERVICEIPORDOMAIN
+    ```
+
+    If your homepage install (container) cannot reach the service then you need to figure out why, for example in Docker this can mean putting the two containers on the same network, checking firewall issues, etc.
+
+3.  If you have verified that homepage can in fact reach the service then you can also check the API output using e.g. `curl`, which is often helpful if you do need to file a bug report. Again, depending on your networking setup this may need to be run from _inside the container_ as IP / hostname resolution can differ inside vs outside.
+
+    !!! note
+
+        `curl` is not installed in the base image by default but can be added inside the container with `apk add curl`.
+
+    The exact API endpoints and authentication vary of course, but in many cases instructions can be found by searching the web or if you feel comfortable looking at the homepage source code (e.g. `src/widgets/{widget}/widget.js`).
+
+    It is out of the scope of this to go into full detail about how to , but an example for PiHole would be:
+
+    ```
+    curl -L -k http://PIHOLEIPORHOST/admin/api.php
+    ```
+
+    Or for AdGuard:
+
+    ```
+    curl -L -k -u 'username:password' http://ADGUARDIPORHOST/control/stats
+    ```
+
+    Or for Portainer:
+
+    ```
+    curl -L -k -H 'X-Api-Key:YOURKEY' 'https://PORTAINERIPORHOST:PORT/api/endpoints/2/docker/containers/json'
+    ```
+
+    Sonarr:
+
+    ```
+    curl -L -k 'http://SONARRIPORHOST:PORT/api/v3/queue?apikey=YOURAPIKEY'
+    ```
+
+    This will return some data which may reveal an issue causing a true bug in the service widget.
+
+## Missing custom icons
+
+If, after correctly adding and mapping your custom icons via the [Icons](../configs/services.md#icons) instructions, you are still unable to see your icons please try recreating your container.

docs/stylesheets/extra.css

@@ -0,0 +1,20 @@
+[data-md-toggle="search"]:not(:checked) ~ .md-header .md-search__form::after {
+    position: absolute;
+    top: .3rem;
+    right: .3rem;
+    display: block;
+    padding: .1rem .4rem;
+    color: var(--md-default-fg-color--lighter);
+    font-weight: bold;
+    font-size: .8rem;
+    border: .05rem solid var(--md-default-fg-color--lighter);
+    border-radius: .1rem;
+    content: "/";
+  }
+
+[data-md-color-scheme="default"][data-md-color-primary="black"] {
+    [data-md-toggle="search"]:not(:checked) ~ .md-header .md-search__form::after {
+        color: var(--md-default-bg-color--lighter);
+        border-color: var(--md-default-bg-color--lighter);
+    }
+}

docs/widgets/index.md

@@ -0,0 +1,35 @@
+---
+title: Widgets
+description: Homepage info and status widgets.
+---
+
+Homepage has two types of widgets: info and service. Below we'll cover each type and how to configure them.
+
+## Service Widgets
+
+Service widgets are used to display the status of a service, often a web service or API. Services (and their widgets) are defined in your `services.yml` file. Here's an example:
+
+```yaml
+- Plex:
+    icon: plex.png
+    href: https://plex.my.host
+    description: Watch movies and TV shows.
+    server: localhost
+    container: plex
+    widget:
+      type: tautulli
+      url: http://172.16.1.1:8181
+      key: aabbccddeeffgghhiijjkkllmmnnoo
+```
+
+## Info Widgets
+
+Info widgets are used to display information in the header, often about your system or environment. Info widgets are defined your `widgets.yml` file. Here's an example:
+
+```yaml
+- openmeteo:
+    label: Current
+    latitude: 36.66
+    longitude: -117.51
+    cache: 5
+```

docs/widgets/info/datetime.md

@@ -0,0 +1,51 @@
+---
+title: Date & Time
+description: Date & Time Information Widget Configuration
+---
+
+This allows you to display the date and/or time, can be heavily configured using [Intl.DateTimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat).
+
+Formatting is locale aware and will present your date in the regional format you expect, for example, `9/16/22, 3:03 PM` for locale `en` and `16.09.22, 15:03` for `de`. You can also specify a locale just for the datetime widget with the `locale` option (see below).
+
+```yaml
+- datetime:
+    text_size: xl
+    format:
+      timeStyle: short
+```
+
+Any options passed to `format` are passed directly to [Intl.DateTimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat), please reference the MDN documentation for all available options.
+
+Valid text sizes are `4xl`, `3xl`, `2xl`, `xl`, `md`, `sm`, `xs`.
+
+A few examples,
+
+```yaml
+# 13:37
+format:
+  timeStyle: short
+  hourCycle: h23
+```
+
+```yaml
+# 1:37 PM
+format:
+  timeStyle: short
+  hour12: true
+```
+
+```yaml
+# 1/23/22, 1:37 PM
+format:
+  dateStyle: short
+  timeStyle: short
+  hour12: true
+```
+
+```yaml
+# 4 januari 2023 om 13:51:25 PST
+locale: nl
+format:
+  dateStyle: long
+  timeStyle: long
+```

docs/widgets/info/glances.md

@@ -0,0 +1,33 @@
+---
+title: Glances
+description: Glances Information Widget Configuration
+---
+
+_(Find the Glances service widget [here](../services/glances.md))_
+
+The Glances widget allows you to monitor the resources (CPU, memory, storage, temp & uptime) of host or another machine, and is designed to match the `resources` info widget. You can have multiple instances by adding another configuration block. The `cputemp`, `uptime` & `disk` states require separate API calls and thus are not enabled by default. Glances needs to be running in "web server" mode to enable the API, see the [glances docs](https://glances.readthedocs.io/en/latest/quickstart.html#web-server-mode).
+
+```yaml
+- glances:
+    url: http://host.or.ip:port
+    username: user # optional if auth enabled in Glances
+    password: pass # optional if auth enabled in Glances
+    cpu: true # optional, enabled by default, disable by setting to false
+    mem: true # optional, enabled by default, disable by setting to false
+    cputemp: true # disabled by default
+    uptime: true # disabled by default
+    disk: / # disabled by default, use mount point of disk(s) in glances. Can also be a list (see below)
+    expanded: true # show the expanded view
+    label: MyMachine # optional
+```
+
+Multiple disks can be specified as:
+
+```yaml
+disk:
+  - /
+  - /boot
+  ...
+```
+
+_Added in v0.4.18, updated in v0.6.11, v0.6.21_

docs/widgets/info/greeting.md

@@ -0,0 +1,14 @@
+---
+title: Greeting
+description: Greeting Information Widget Configuration
+---
+
+This allows you to display simple text, can be configured like so:
+
+```yaml
+- greeting:
+    text_size: xl
+    text: Greeting Text
+```
+
+Valid text sizes are `4xl`, `3xl`, `2xl`, `xl`, `md`, `sm`, `xs`.

docs/widgets/info/index.md

@@ -0,0 +1,4 @@
+---
+title: Info Widgets
+description: Homepage info widgets.
+---

docs/widgets/info/kubernetes.md

@@ -0,0 +1,31 @@
+---
+title: Kubernetes
+description: Kubernetes Information Widget Configuration
+---
+
+This is very similar to the Resources widget, but provides resource information about a Kubernetes cluster.
+
+It provides CPU and Memory usage, by node and/or at the cluster level.
+
+```yaml
+- kubernetes:
+    cluster:
+      # Shows cluster-wide statistics
+      show: true
+      # Shows the aggregate CPU stats
+      cpu: true
+      # Shows the aggregate memory stats
+      memory: true
+      # Shows a custom label
+      showLabel: true
+      label: "cluster"
+    nodes:
+      # Shows node-specific statistics
+      show: true
+      # Shows the CPU for each node
+      cpu: true
+      # Shows the memory for each node
+      memory: true
+      # Shows the label, which is always the node name
+      showLabel: true
+```

docs/widgets/info/logo.md

@@ -0,0 +1,13 @@
+---
+title: Logo
+description: Logo Information Widget Configuration
+---
+
+This allows you to display the homepage logo, you can optionally specify your own icon using similar options as other icons, see [service icons](../../configs/services.md#icons).
+
+```yaml
+- logo:
+    icon: https://upload.wikimedia.org/wikipedia/commons/thumb/d/d5/I_Love_New_York.svg/1101px-I_Love_New_York.svg.png # optional
+```
+
+_Added in v0.4.18, updated in 0.X.X_

docs/widgets/info/longhorn.md

@@ -0,0 +1,29 @@
+---
+title: Longhorn
+description: Longhorn Storage Widget Configuration
+---
+
+The Longhorn widget pulls storage utilization metrics from the Longhorn storage driver on Kubernetes.
+It is designed to appear similar to the Resource widget's disk representation.
+
+The exact metrics should be very similar to what is seen on the Longhorn dashboard itself.
+
+It can show the aggregate metrics and/or the individual node metrics.
+
+```yaml
+- longhorn:
+    # Show the expanded view
+    expanded: true
+    # Shows a node representing the aggregate values
+    total: true
+    # Shows the node names as labels
+    labels: true
+    # Show the nodes
+    nodes: true
+    # An explicit list of nodes to show. All are shown by default if "nodes" is true
+    include:
+      - node1
+      - node2
+```
+
+The Longhorn URL and credentials are stored in the `providers` section of the `settings.yaml`.

docs/widgets/info/openmeteo.md

@@ -0,0 +1,18 @@
+---
+title: Open-Meteo
+description: Open-Meteo Information Widget Configuration
+---
+
+No registration is required at all! See [https://open-meteo.com/en/docs](https://open-meteo.com/en/docs)
+
+```yaml
+- openmeteo:
+    label: Kyiv # optional
+    latitude: 50.449684
+    longitude: 30.525026
+    timezone: Europe/Kiev # optional
+    units: metric # or imperial
+    cache: 5 # Time in minutes to cache API responses, to stay within limits
+```
+
+You can optionally not pass a `latitude` and `longitude` and the widget will use your current location (requires a secure context, eg. HTTPS).

docs/widgets/info/openweathermap.md

@@ -0,0 +1,19 @@
+---
+title: OpenWeatherMap
+description: OpenWeatherMap Information Widget Configuration
+---
+
+The free tier "One Call API" is all thats required, you will need to [subscribe](https://home.openweathermap.org/subscriptions/unauth_subscribe/onecall_30/base) and grab your API key.
+
+```yaml
+- openweathermap:
+    label: Kyiv #optional
+    latitude: 50.449684
+    longitude: 30.525026
+    units: metric # or imperial
+    provider: openweathermap
+    apiKey: youropenweathermapkey # required only if not using provider, this reveals api key in requests
+    cache: 5 # Time in minutes to cache API responses, to stay within limits
+```
+
+You can optionally not pass a `latitude` and `longitude` and the widget will use your current location (requires a secure context, eg. HTTPS).

docs/widgets/info/resources.md

@@ -0,0 +1,71 @@
+---
+title: Resources
+description: Resources Information Widget Configuration
+---
+
+You can include all or some of the available resources. If you do not want to see that resource, simply pass `false`.
+
+The disk path is the path reported by `df` (Mounted On), or the mount point of the disk.
+
+The cpu and memory resource information are the container's usage while [glances](glances.md) displays statistics for the host machine on which it is installed.
+
+_Note: unfortunately, the package used for getting CPU temp ([systeminformation](https://systeminformation.io)) is not compatibile with some setups and will not report any value(s) for CPU temp._
+
+**Any disk you wish to access must be mounted to your container as a volume.**
+
+```yaml
+- resources:
+    cpu: true
+    memory: true
+    disk: /disk/mount/path
+    cputemp: true
+    uptime: true
+    units: imperial # only used by cpu temp
+    refresh: 3000 # optional, in ms
+```
+
+You can also pass a `label` option, which allows you to group resources under named sections,
+
+```yaml
+- resources:
+    label: System
+    cpu: true
+    memory: true
+
+- resources:
+    label: Storage
+    disk: /mnt/storage
+```
+
+Which produces something like this,
+
+<img width="373" alt="Resource Groups" src="https://user-images.githubusercontent.com/82196/189524699-e9005138-e049-4a9c-8833-ac06e39882da.png">
+
+If you have more than a single disk and would like to group them together under the same label, you can pass an array of paths instead,
+
+```yaml
+- resources:
+    label: Storage
+    disk:
+      - /mnt/storage
+      - /mnt/backup
+      - /mnt/media
+```
+
+To produce something like this,
+
+<img width="369" alt="Screenshot 2022-09-11 at 2 15 42 PM" src="https://user-images.githubusercontent.com/82196/189524583-abdf4cc6-99da-430c-b316-16c567db5639.png">
+
+You can additionally supply an optional `expanded` property set to true in order to show additional details about the resources. By default the expanded property is set to false when not supplied.
+
+```yaml
+- resources:
+    label: Array Disks
+    expanded: true
+    disk:
+      - /disk1
+      - /disk2
+      - /disk3
+```
+
+![194136533-c4238c82-4d67-41a4-b3c8-18bf26d33ac2](https://user-images.githubusercontent.com/3441425/194728642-a9885274-922b-4027-acf5-a746f58fdfce.png)

docs/widgets/info/search.md

@@ -0,0 +1,31 @@
+---
+title: Search
+description: Search Information Widget Configuration
+---
+
+You can add a search bar to your top widget area that can search using Google, Duckduckgo, Bing, Baidu, Brave or any other custom provider that supports the basic `?q=` search query param.
+
+```yaml
+- search:
+    provider: google # google, duckduckgo, bing, baidu, brave or custom
+    focus: true # Optional, will set focus to the search bar on page load
+    target: _blank # One of _self, _blank, _parent or _top
+```
+
+or for a custom search:
+
+```yaml
+- search:
+    provider: custom
+    url: https://lougle.com/?q=
+    target: _blank
+```
+
+multiple providers is also supported via a dropdown (excluding custom):
+
+```yaml
+- search:
+    provider: [brave, google, duckduckgo]
+```
+
+_Added in v0.1.6, updated in 0.6.0_

docs/widgets/info/unifi_controller.md

@@ -0,0 +1,24 @@
+---
+title: Unifi Controller
+description: Unifi Controller Information Widget Configuration
+---
+
+_(Find the Unifi Controller service widget [here](../services/unifi-controller.md))_
+
+You can display general connectivity status from your Unifi (Network) Controller. When authenticating you will want to use a local account that has at least read privileges.
+
+An optional 'site' parameter can be supplied, if it is not the widget will use the default site for the controller.
+
+_Note: If you enter e.g. incorrect credentials and receive an "API Error", you may need to recreate the container to clear the cache._
+
+<img width="162" alt="unifi_infowidget" src="https://user-images.githubusercontent.com/4887959/197706832-f5a8706b-7282-4892-a666-b7d999752562.png">
+
+```yaml
+- unifi_console:
+    url: https://unifi.host.or.ip:port
+    username: user
+    password: pass
+    site: Site Name # optional
+```
+
+_Added in v0.4.18, updated in 0.6.7_

docs/widgets/info/weather.md

@@ -0,0 +1,20 @@
+---
+title: Weather API
+description: Weather API Information Widget Configuration
+---
+
+**Note: this widget is considered 'deprecated' since there is no longer a free Weather API tier for new members. See the openmeteo or openweathermap widgets for alternatives.**
+
+The free tier is all thats required, you will need to [register](https://www.weatherapi.com/signup.aspx) and grab your API key.
+
+```yaml
+- weatherapi:
+    label: Kyiv # optional
+    latitude: 50.449684
+    longitude: 30.525026
+    units: metric # or imperial
+    apiKey: yourweatherapikey
+    cache: 5 # Time in minutes to cache API responses, to stay within limits
+```
+
+You can optionally not pass a `latitude` and `longitude` and the widget will use your current location (requires a secure context, eg. HTTPS).

docs/widgets/services/adguard-home.md

@@ -0,0 +1,16 @@
+---
+title: Adguard Home
+description: Adguard Home Widget Configuration
+---
+
+The username and password are the same as used to login to the web interface.
+
+Allowed fields: `["queries", "blocked", "filtered", "latency"]`.
+
+```yaml
+widget:
+  type: adguard
+  url: http://adguard.host.or.ip
+  username: admin
+  password: password
+```

docs/widgets/services/atsumeru.md

@@ -0,0 +1,16 @@
+---
+title: Atsumeru
+description: Atsumeru Widget Configuration
+---
+
+Define same username and password that is used for login from web or supported apps
+
+Allowed fields: `["series", "archives", "chapters", "categories"]`.
+
+```yaml
+widget:
+  type: atsumeru
+  url: http://atsumeru.host.or.ip:port
+  username: username
+  password: password
+```

docs/widgets/services/audiobookshelf.md

@@ -0,0 +1,15 @@
+---
+title: Audiobookshelf
+description: Audiobookshelf Widget Configuration
+---
+
+You can find your API token by logging into the Audiobookshelf web app as an admin, go to the config → users page, and click on your account.
+
+Allowed fields: `["podcasts", "podcastsDuration", "books", "booksDuration"]`
+
+```yaml
+widget:
+  type: audiobookshelf
+  url: http://audiobookshelf.host.or.ip:port
+  key: audiobookshelflapikey
+```

docs/widgets/services/authentik.md

@@ -0,0 +1,24 @@
+---
+title: Authentik
+description: Authentik Widget Configuration
+---
+
+This widget reads the number of active users in the system, as well as logins for the last 24 hours.
+
+You will need to generate an API token for an existing user. To do so follow these steps:
+
+1. Navigate to the Authentik Admin Portal
+2. Expand Directory, the click Tokens & App passwords
+3. Click the Create button
+4. Fill out the dialog making sure to set Intent to API Token
+5. Click the Create button on the dialog
+6. Click the copy button on the far right of the newly created API Token
+
+Allowed fields: `["users", "loginsLast24H", "failedLoginsLast24H"]`.
+
+```yaml
+widget:
+  type: authentik
+  url: http://authentik.host.or.ip:22070
+  key: api_token
+```

docs/widgets/services/autobrr.md

@@ -0,0 +1,15 @@
+---
+title: Autobrr
+description: Autobrr Widget Configuration
+---
+
+Find your API key under `Settings > API Keys`.
+
+Allowed fields: `["approvedPushes", "rejectedPushes", "filters", "indexers"]`.
+
+```yaml
+widget:
+  type: autobrr
+  url: http://autobrr.host.or.ip
+  key: apikeyapikeyapikeyapikeyapikey
+```

docs/widgets/services/azuredevops.md

@@ -0,0 +1,26 @@
+---
+title: Azure DevOps
+description: Azure DevOps Widget Configuration
+---
+
+This widget has 2 functions:
+
+1. Pipelines: checks if the relevant pipeline is running or not, and if not, reports the last status.\
+   Allowed fields: `["result", "status"]`.
+
+2. Pull Requests: returns the amount of open PRs, the amount of the PRs you have open, and how many PRs that you open are marked as 'Approved' by atleast 1 person and not yet completed.\
+   Allowed fields: `["totalPrs", "myPrs", "approved"]`.
+
+You will need to generate a personal access token for an existing user, see the [azure documentation](https://learn.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=azure-devops&tabs=Windows#create-a-pat)
+
+```yaml
+widget:
+  type: azuredevops
+  organization: myOrganization
+  project: myProject
+  definitionId: pipelineDefinitionId # required for pipelines
+  branchName: branchName # optional for pipelines, leave empty for all
+  userEmail: email # required for pull requests
+  repositoryId: prRepositoryId # required for pull requests
+  key: personalaccesstoken
+```

docs/widgets/services/bazarr.md

@@ -0,0 +1,15 @@
+---
+title: Bazarr
+description: Bazarr Widget Configuration
+---
+
+Find your API key under `Settings > General`.
+
+Allowed fields: `["missingEpisodes", "missingMovies"]`.
+
+```yaml
+widget:
+  type: bazarr
+  url: http://bazarr.host.or.ip
+  key: apikeyapikeyapikeyapikeyapikey
+```

docs/widgets/services/caddy.md

@@ -0,0 +1,12 @@
+---
+title: Caddy
+description: Caddy Widget Configuration
+---
+
+Allowed fields: `["upstreams", "requests", "requests_failed"]`.
+
+```yaml
+widget:
+  type: caddy
+  url: http://caddy.host.or.ip:adminport # default admin port is 2019
+```

docs/widgets/services/calendar.md

@@ -0,0 +1,25 @@
+---
+title: Calendar
+description: Calendar widget
+---
+
+<img alt="calendar" src="https://user-images.githubusercontent.com/5442891/271131282-6767a3ea-573e-4005-aeb9-6e14ee01e845.png">
+
+This widget shows monthly calendar, with optional integrations to show events from supported widgets.
+
+```yaml
+widget:
+  type: calendar
+  firstDayInWeek: sunday # optional - defaults to monday
+  integrations: # optional
+    - type: sonarr # active widget type that is currently enabled on homepage - possible values: radarr, sonarr, lidarr, readarr
+      service_group: Media # group name where widget exists
+      service_name: Sonarr # service name for that widget
+      color: teal # optional - defaults to pre-defined color for the service (teal for sonarr)
+      params: # optional - additional params for the service
+        unmonitored: true # optional - defaults to false, used with *arr stack
+```
+
+Currently integrated widgets are [sonarr](sonarr.md), [radarr](radarr.md), [lidarr](lidarr.md) and [readarr](readarr.md).
+
+Supported colors can be found on [color palette](../../configs/settings.md#color-palette).

docs/widgets/services/calibre-web.md

@@ -0,0 +1,16 @@
+---
+title: Calibre-web
+description: Calibre-web Widget Configuration
+---
+
+**Note: this widget requires a feature of calibre-web that has not yet been distributed in versioned release. The code is contained in ["nightly" lsio builds after 25/8/23](https://hub.docker.com/layers/linuxserver/calibre-web/nightly/images/sha256-b27cbe5d17503de38135d925e226eb3e5ba04c558dbc865dc85d77824d35d7e2) or running the calibre-web source code including commit [0499e57](https://github.com/janeczku/calibre-web/commit/0499e578cdd45db656da34cd2d7152c8d88ceb23).**
+
+Allowed fields: `["books", "authors", "categories", "series"]`.
+
+```yaml
+widget:
+  type: calibreweb
+  url: http://your.calibreweb.host:port
+  username: username
+  password: password
+```

docs/widgets/services/changedetectionio.md

@@ -0,0 +1,13 @@
+---
+title: Changedetection.io
+description: Changedetection.io Widget Configuration
+---
+
+Find your API key under `Settings > API`.
+
+```yaml
+widget:
+  type: changedetectionio
+  url: http://changedetection.host.or.ip:port
+  key: apikeyapikeyapikeyapikeyapikey
+```

docs/widgets/services/channelsdvrserver.md

@@ -0,0 +1,10 @@
+---
+title: Channels DVR Server
+description: Channels DVR Server Widget Configuration
+---
+
+```yaml
+widget:
+  type: channelsdvrserver
+  url: http://192.168.1.55:8089
+```

docs/widgets/services/cloudflared.md

@@ -0,0 +1,16 @@
+---
+title: Cloudflare Tunnels
+description: Cloudflare Tunnels Widget Configuration
+---
+
+_As of v0.6.10 this widget no longer accepts a Cloudflare global API key (or account email) due to security concerns. Instead, you should setup an API token which only requires the permissions `Account.Cloudflare Tunnel:Read`._
+
+Allowed fields: `["status", "origin_ip"]`.
+
+```yaml
+widget:
+  type: cloudflared
+  accountid: accountid # from zero trust dashboard url e.g. https://one.dash.cloudflare.com/<accountid>/home/quick-start
+  tunnelid: tunnelid # found in tunnels dashboard under the tunnel name
+  key: cloudflareapitoken # api token with `Account.Cloudflare Tunnel:Read` https://dash.cloudflare.com/profile/api-tokens
+```

docs/widgets/services/coin-market-cap.md

@@ -0,0 +1,26 @@
+---
+title: Coin Market Cap
+description: Coin Market Cap Widget Configuration
+---
+
+Get your API key from your [CoinMarketCap Pro Dashboard](https://pro.coinmarketcap.com/account).
+
+Allowed fields: no configurable fields for this widget.
+
+```yaml
+widget:
+  type: coinmarketcap
+  currency: GBP # Optional
+  symbols: [BTC, LTC, ETH]
+  key: apikeyapikeyapikeyapikeyapikey
+  defaultinterval: 7d # Optional
+```
+
+You can also specify slugs instead of symbols (since symbols aren't garaunteed to be unique). If you supply both, slugs will be used. For example:
+
+```yaml
+widget:
+  type: coinmarketcap
+  slugs: [chia-network, uniswap]
+  key: apikeyapikeyapikeyapikeyapikey
+```

docs/widgets/services/customapi.md

@@ -0,0 +1,109 @@
+---
+title: Custom API
+description: Custom Widget Configuration from the API
+---
+
+This widget can show information from custom self-hosted or third party API.
+
+Fields need to be defined in the `mappings` section YAML object to correlate with the value in the APIs JSON object. Final field definition needs to be the key with the desired value information.
+
+```yaml
+widget:
+  type: customapi
+  url: http://custom.api.host.or.ip:port/path/to/exact/api/endpoint
+  refreshInterval: 10000 # optional - in milliseconds, defaults to 10s
+  username: username # auth - optional
+  password: password # auth - optional
+  method: GET # optional, e.g. POST
+  headers: # optional, must be object, see below
+  mappings:
+    - field: key # needs to be YAML string or object
+      label: Field 1
+      format: text # optional - defaults to text
+    - field: # needs to be YAML string or object
+        path:
+          to: key2
+      format: number # optional - defaults to text
+      label: Field 2
+    - field: # needs to be YAML string or object
+        path:
+          to:
+            another: key3
+      label: Field 3
+      format: percent # optional - defaults to text
+```
+
+Supported formats for the values are `text`, `number`, `float`, `percent`, `bytes` and `bitrate`.
+
+## Example
+
+For the following JSON object from the API:
+
+```json
+{
+  "id": 1,
+  "name": "Rick Sanchez",
+  "status": "Alive",
+  "species": "Human",
+  "gender": "Male",
+  "origin": {
+    "name": "Earth (C-137)"
+  },
+  "locations": [
+    {
+      "name": "Earth (C-137)"
+    },
+    {
+      "name": "Citadel of Ricks"
+    }
+  ]
+}
+```
+
+Define the `mappings` section as an aray, for example:
+
+```yaml
+mappings:
+  - field: name # Rick Sanchez
+    label: Name
+  - field: status # Alive
+    label: Status
+  - field:
+      origin: name # Earth (C-137)
+    label: Origin
+  - field:
+      locations:
+        1: name # Citadel of Ricks
+    label: Location
+```
+
+## Data Transformation
+
+You can manipulate data with the following tools `remap`, `scale` and `suffix`, for example:
+
+```yaml
+- field: key4
+  label: Field 4
+  format: text
+  remap:
+    - value: 0
+      to: None
+    - value: 1
+      to: Connected
+    - any: true # will map all other values
+      to: Unknown
+- field: key5
+  label: Power
+  format: float
+  scale: 0.001 # can be number or string e.g. 1/16
+  suffix: kW
+```
+
+## Custom Headers
+
+Pass custom headers using the `headers` option, for example:
+
+```yaml
+headers:
+  X-API-Token: token
+```

docs/widgets/services/deluge.md

@@ -0,0 +1,15 @@
+---
+title: Deluge
+description: Deluge Widget Configuration
+---
+
+Uses the same password used to login to the webui, see [the deluge FAQ](https://dev.deluge-torrent.org/wiki/Faq#Whatisthedefaultpassword).
+
+Allowed fields: `["leech", "download", "seed", "upload"]`.
+
+```yaml
+widget:
+  type: deluge
+  url: http://deluge.host.or.ip
+  password: password # webui password
+```

docs/widgets/services/diskstation.md

@@ -0,0 +1,36 @@
+---
+title: Synology Disk Station
+description: Synology Disk Station Widget Configuration
+---
+
+Note: the widget is not compatible with 2FA.
+
+An optional 'volume' parameter can be supplied to specify which volume's free space to display when more than one volume exists. The value of the parameter must be in form of `volume_N`, e.g. to display free space for volume2, `volume_2` should be set as 'volume' value. If omitted, first returned volume's free space will be shown (not guaranteed to be volume1).
+
+Allowed fields: `["uptime", "volumeAvailable", "resources.cpu", "resources.mem"]`.
+
+To access these system metrics you need to connect to the DiskStation with an account that is a member of the default `Administrators` group. That is because these metrics are requested from the API's `SYNO.Core.System` part that is only available to admin users. In order to keep the security impact as small as possible we can set the account in DSM up to limit the user's permissions inside the Synology system. In DSM 7.x, for instance, follow these steps:
+
+1. Create a new user, i.e. `remote_stats`.
+2. Set up a strong password for the new user
+3. Under the `User Groups` tab of the user config dialogue check the box for `Administrators`.
+4. On the `Permissions` tab check the top box for `No Access`, effectively prohibiting the user from accessing anything in the shared folders.
+5. Under `Applications` check the box next to `Deny` in the header to explicitly prohibit login to all applications.
+6. Now _only_ allow login to the `Download Station` application, either by
+   - unchecking `Deny` in the respective row, or (if inheriting permission doesn't work because of other group settings)
+   - checking `Allow` for this app, or
+   - checking `By IP` for this app to limit the source of login attempts to one or more IP addresses/subnets.
+7. When the `Preview` column shows `Allow` in the `Download Station` row, click `Save`.
+
+Now configure the widget with the correct login information and test it.
+
+If you encounter issues during testing, make sure to uncheck the option for automatic blocking due to invalid logins under `Control Panel > Security > Protection`. If desired, this setting can be reactivated once the login is established working.
+
+```yaml
+widget:
+  type: diskstation
+  url: http://diskstation.host.or.ip:port
+  username: username
+  password: password
+  volume: volume_N # optional
+```

docs/widgets/services/downloadstation.md

@@ -0,0 +1,16 @@
+---
+title: Synology Download Station
+description: Synology Download Station Widget Configuration
+---
+
+Note: the widget is not compatible with 2FA.
+
+Allowed fields: `["leech", "download", "seed", "upload"]`.
+
+```yaml
+widget:
+  type: downloadstation
+  url: http://downloadstation.host.or.ip:port
+  username: username
+  password: password
+```

docs/widgets/services/emby.md

@@ -0,0 +1,17 @@
+---
+title: Emby
+description: Emby Widget Configuration
+---
+
+You can create an API key from inside Emby at `Settings > Advanced > Api Keys`.
+
+As of v0.6.11 the widget supports fields `["movies", "series", "episodes", "songs"]`. These blocks are disabled by default but can be enabled with the `enableBlocks` option, and the "Now Playing" feature (enabled by default) can be disabled with the `enableNowPlaying` option.
+
+```yaml
+widget:
+  type: emby
+  url: http://emby.host.or.ip
+  key: apikeyapikeyapikeyapikeyapikey
+  enableBlocks: true # optional, defaults to false
+  enableNowPlaying: true # optional, defaults to true
+```

docs/widgets/services/evcc.md

@@ -0,0 +1,12 @@
+---
+title: EVCC
+description: EVCC Widget Configuration
+---
+
+Allowed fields: `["pv_power", "grid_power", "home_power", "charge_power]`.
+
+```yaml
+widget:
+  type: evcc
+  url: http://evcc.host.or.ip:port
+```

docs/widgets/services/fileflows.md

@@ -0,0 +1,12 @@
+---
+title: Fileflows
+description: Fileflows Widget Configuration
+---
+
+Allowed fields: `["queue", "processing", "processed", "time"]`.
+
+```yaml
+widget:
+  type: fileflows
+  url: http://your.fileflows.host:port
+```

docs/widgets/services/flood.md

@@ -0,0 +1,14 @@
+---
+title: Flood
+description: Flood Widget Configuration
+---
+
+Allowed fields: `["leech", "download", "seed", "upload"]`.
+
+```yaml
+widget:
+  type: flood
+  url: http://flood.host.or.ip
+  username: username # if set
+  password: password # if set
+```

docs/widgets/services/freshrss.md

@@ -0,0 +1,16 @@
+---
+title: FreshRSS
+description: FreshRSS Widget Configuration
+---
+
+Please refer to [Enable the API in FreshRSS](https://freshrss.github.io/FreshRSS/en/users/06_Mobile_access.html#enable-the-api-in-freshrss) for the "API password" to be entered in the password field.
+
+Allowed fields: `["subscriptions", "unread"]`.
+
+```yaml
+widget:
+  type: freshrss
+  url: http://freshrss.host.or.ip:port
+  username: username
+  password: password
+```

docs/widgets/services/gamedig.md

@@ -0,0 +1,15 @@
+---
+title: GameDig
+description: GameDig Widget Configuration
+---
+
+Uses the [GameDig](https://www.npmjs.com/package/gamedig) library to get game server information for any supported server type.
+
+Allowed fields (limited to a max of 4): `["status", "name", "map", "currentPlayers", "players", "maxPlayers", "bots", "ping"]`.
+
+```yaml
+widget:
+  type: gamedig
+  serverType: csgo # see https://github.com/gamedig/node-gamedig#games-list
+  url: udp://server.host.or.ip:port
+```

docs/widgets/services/ghostfolio.md

@@ -0,0 +1,23 @@
+---
+title: Ghostfolio
+description: Ghostfolio Widget Configuration
+---
+
+Authentication requires manually obtaining a Bearer token which can be obtained by make a POST request to the API e.g.
+
+```
+curl -X POST http://localhost:3333/api/v1/auth/anonymous -H 'Content-Type: application/json' -d '{ "accessToken": "SECURITY_TOKEN_OF_ACCOUNT" }'
+```
+
+See the [official docs](https://github.com/ghostfolio/ghostfolio#authorization-bearer-token).
+
+_Note that the Bearer token is valid for 6 months, after which a new one must be generated._
+
+Allowed fields: `["gross_percent_today", "gross_percent_1y", "gross_percent_max"]`
+
+```yaml
+widget:
+  type: ghostfolio
+  url: http://ghostfoliohost:port
+  key: ghostfoliobearertoken
+```

docs/widgets/services/glances.md

@@ -0,0 +1,73 @@
+---
+title: Glances
+description: Glances Widget Configuration
+---
+
+<img width="1614" alt="glances" src="https://github-production-user-asset-6210df.s3.amazonaws.com/82196/257382012-25648c97-2c1b-4db0-b5a5-f1509806079c.png">
+
+_(Find the Glances information widget [here](../info/glances.md))_
+
+The Glances widget allows you to monitor the resources (cpu, memory, diskio, sensors & processes) of host or another machine. You can have multiple instances by adding another service block.
+
+```yaml
+widget:
+  type: glances
+  url: http://glances.host.or.ip:port
+  username: user # optional if auth enabled in Glances
+  password: pass # optional if auth enabled in Glances
+  metric: cpu
+```
+
+_Please note, this widget does not need an `href`, `icon` or `description` on its parent service. To achive the same effect as the examples above, see as an example:_
+
+```yaml
+- CPU Usage:
+    widget:
+      type: glances
+      url: http://glances.host.or.ip:port
+      metric: cpu
+- Network Usage:
+    widget:
+      type: glances
+      url: http://glances.host.or.ip:port
+      metric: network:enp0s25
+```
+
+## Metrics
+
+The metric field in the configuration determines the type of system monitoring data to be displayed. Here are the supported metrics:
+
+`info`: System information. Shows the system's hostname, OS, kernel version, CPU type, CPU usage, RAM usage and SWAP usage.
+
+`cpu`: CPU usage. Shows how much of the system's computational resources are currently being used.
+
+`memory`: Memory usage. Shows how much of the system's RAM is currently being used.
+
+`process`: Top 5 processes based on CPU usage. Gives an overview of which processes are consuming the most resources.
+
+`network:<interface_name>`: Network data usage for the specified interface. Replace `<interface_name>` with the name of your network interface, e.g., `network:enp0s25`, as specificed in glances.
+
+`sensor:<sensor_id>`: Temperature of the specified sensor, typically used to monitor CPU temperature. Replace `<sensor_id>` with the name of your sensor, e.g., `sensor:Package id 0` as specificed in glances.
+
+`disk:<disk_id>`: Disk I/O data for the specified disk. Replace `<disk_id>` with the id of your disk, e.g., `disk:sdb`, as specificed in glances.
+
+`gpu:<gpu_id>`: GPU usage for the specified GPU. Replace `<gpu_id>` with the id of your GPU, e.g., `gpu:0`, as specificed in glances.
+
+`fs:<mnt_point>`: Disk usage for the specified mount point. Replace `<mnt_point>` with the path of your disk, e.g., `/mnt/storage`, as specificed in glances.
+
+## Views
+
+All widgets offer an alternative to the full or "graph" view, which is the compact, or "graphless" view.
+
+<img width="970" alt="Screenshot 2023-09-06 at 1 51 48 PM" src="https://github-production-user-asset-6210df.s3.amazonaws.com/82196/265985295-cc6b9adc-4218-4274-96ca-36c3e64de5d0.png">
+
+To switch to the alternative "graphless" view, simply passs `chart: false` as an option to the widget, like so:
+
+```yaml
+- Network Usage:
+    widget:
+      type: glances
+      url: http://glances.host.or.ip:port
+      metric: network:enp0s25
+      chart: false
+```

docs/widgets/services/gluetun.md

@@ -0,0 +1,14 @@
+---
+title: Gluetun
+description: Gluetun Widget Configuration
+---
+
+Requires [HTTP control server options](https://github.com/qdm12/gluetun-wiki/blob/main/setup/advanced/control-server.md) to be enabled.
+
+Allowed fields: `["public_ip", "region", "country"]`.
+
+```yaml
+widget:
+  type: gluetun
+  url: http://gluetun.host.or.ip
+```

docs/widgets/services/gotify.md

@@ -0,0 +1,15 @@
+---
+title: Gotify
+description: Gotify Widget Configuration
+---
+
+Get a Gotify client token from an existing client or create a new one on your Gotify admin page.
+
+Allowed fields: `["apps", "clients", "messages"]`.
+
+```yaml
+widget:
+  type: gotify
+  url: http://gotify.host.or.ip
+  key: clientoken
+```

docs/widgets/services/grafana.md

@@ -0,0 +1,14 @@
+---
+title: Grafana
+description: Grafana Widget Configuration
+---
+
+Allowed fields: `["dashboards", "datasources", "totalalerts", "alertstriggered"]`.
+
+```yaml
+widget:
+  type: grafana
+  url: http://grafana.host.or.ip:port
+  username: username
+  password: password
+```

docs/widgets/services/hdhomerun.md

@@ -0,0 +1,12 @@
+---
+title: HDHomerun
+description: HDHomerun Widget Configuration
+---
+
+Allowed fields: `["channels", "hd"]`.
+
+```yaml
+widget:
+  type: hdhomerun
+  url: http://hdhomerun.host.or.ip
+```

docs/widgets/services/healthchecks.md

@@ -0,0 +1,20 @@
+---
+title: Health checks
+description: Health checks Widget Configuration
+---
+
+To use the Health Checks widget, you first need to generate an API key. To do this, follow these steps:
+
+1. Go to Settings in your check dashboard.
+2. Click on API key (read-only) and then click _Create_.
+3. Copy the API key that is generated for you.
+
+Allowed fields: `["status", "last_ping"]`.
+
+```yaml
+widget:
+  type: healthchecks
+  url: http://healthchecks.host.or.ip:port
+  key: <YOUR_API_KEY>
+  uuid: <YOUR_CHECK_UUID>
+```

docs/widgets/services/homeassistant.md

@@ -0,0 +1,36 @@
+---
+title: Home Assistant
+description: Home Assistant Widget Configuration
+---
+
+You will need to generate a long-lived access token for an existing Home Assistant user in its profile.
+
+Allowed fields: `["people_home", "lights_on", "switches_on"]`.
+
+---
+
+Up to a maximum of four custom states and/or templates can be queried via the `custom` property like in the example below.
+The `custom` property will have no effect as long as the `fields` property is defined.
+
+- `state` will query the state of the specified `entity_id`
+  - state labels and values can be user defined and may reference entity attributes in curly brackets
+  - if no state label is defined it will default to `"{attributes.friendly_name}"`
+  - if no state value is defined it will default to `"{state} {attributes.unit_of_measurement}"`
+- `template` will query the specified template, see (Home Assistant Templating)[https://www.home-assistant.io/docs/configuration/templating]
+  - if no template label is defined it will be empty
+
+```yaml
+widget:
+  type: homeassistant
+  url: http://homeassistant.host.or.ip:port
+  key: access_token
+  custom:
+    - state: sensor.total_power
+    - state: sensor.total_energy_today
+      label: energy today
+    - template: "{{ states.switch|selectattr('state','equalto','on')|list|length }}"
+      label: switches on
+    - state: weather.forecast_home
+      label: wind speed
+      value: "{attributes.wind_speed} {attributes.wind_speed_unit}"
+```

docs/widgets/services/homebridge.md

@@ -0,0 +1,16 @@
+---
+title: Homebridge
+description: Homebridge
+---
+
+The Homebridge API is actually provided by the Config UI X plugin that has been included with Homebridge for a while, still it is required to be installed for this widget to work.
+
+Allowed fields: `["updates", "child_bridges"]`.
+
+```yaml
+widget:
+  type: homebridge
+  url: http://homebridge.host.or.ip:port
+  username: username
+  password: password
+```

docs/widgets/services/immich.md

@@ -0,0 +1,15 @@
+---
+title: Immich
+description: Immich Widget Configuration
+---
+
+Allowed fields: `["users" ,"photos", "videos", "storage"]`.
+
+Note that API key must be from admin user.
+
+```yaml
+widget:
+  type: immich
+  url: http://immich.host.or.ip
+  key: adminapikeyadminapikeyadminapikey
+```

docs/widgets/services/index.md

@@ -0,0 +1,4 @@
+---
+title: Service Widgets
+description: Homepage service widgets.
+---

docs/widgets/services/jackett.md

@@ -0,0 +1,14 @@
+---
+title: Jackett
+description: Jackett Widget Configuration
+---
+
+Jackett must not have any authentication for the widget to work.
+
+Allowed fields: `["configured", "errored"]`.
+
+```yaml
+widget:
+  type: jackett
+  url: http://jackett.host.or.ip
+```

docs/widgets/services/jdownloader.md

@@ -0,0 +1,16 @@
+---
+title: JDownloader
+description: NextPVR Widget Configuration
+---
+
+Basic widget to show number of items in download queue, along with the queue size and current download speed.
+
+Allowed fields: `["downloadCount", "downloadTotalBytes","downloadBytesRemaining", "downloadSpeed"]`.
+
+```yaml
+widget:
+  type: jdownloader
+  username: JDownloader Username
+  password: JDownloader Password
+  client: Name of JDownloader Instance
+```

docs/widgets/services/jellyfin.md

@@ -0,0 +1,17 @@
+---
+title: Jellyfin
+description: Jellyfin Widget Configuration
+---
+
+You can create an API key from inside Jellyfin at `Settings > Advanced > Api Keys`.
+
+As of v0.6.11 the widget supports fields `["movies", "series", "episodes", "songs"]`. These blocks are disabled by default but can be enabled with the `enableBlocks` option, and the "Now Playing" feature (enabled by default) can be disabled with the `enableNowPlaying` option.
+
+```yaml
+widget:
+  type: jellyfin
+  url: http://jellyfin.host.or.ip
+  key: apikeyapikeyapikeyapikeyapikey
+  enableBlocks: true # optional, defaults to false
+  enableNowPlaying: true # optional, defaults to true
+```

docs/widgets/services/jellyseerr.md

@@ -0,0 +1,15 @@
+---
+title: Jellyseerr
+description: Jellyseerr Widget Configuration
+---
+
+Find your API key under `Settings > General > API Key`.
+
+Allowed fields: `["pending", "approved", "available"]`.
+
+```yaml
+widget:
+  type: jellyseerr
+  url: http://jellyseerr.host.or.ip
+  key: apikeyapikeyapikeyapikeyapikey
+```

docs/widgets/services/kavita.md

@@ -0,0 +1,16 @@
+---
+title: Kavita
+description: Kavita Widget Configuration
+---
+
+Uses the same username and password used to login from the web.
+
+Allowed fields: `["seriesCount", "totalFiles"]`.
+
+```yaml
+widget:
+  type: kavita
+  url: http://kavita.host.or.ip:port
+  username: username
+  password: password
+```

docs/widgets/services/komga.md

@@ -0,0 +1,16 @@
+---
+title: Komga
+description: Komga Widget Configuration
+---
+
+Uses the same username and password used to login from the web.
+
+Allowed fields: `["libraries", "series", "books"]`.
+
+```yaml
+widget:
+  type: komga
+  url: http://komga.host.or.ip:port
+  username: username
+  password: password
+```

docs/widgets/services/kopia.md

@@ -0,0 +1,18 @@
+---
+title: Kopia
+description: Kopia Widget Configuration
+---
+
+Allowed fields: `["status", "size", "lastrun", "nextrun"]`.
+
+You may optionally pass values for `snapshotHost` and / or `snapshotPath` to select a specific backup source for the widget.
+
+```yaml
+widget:
+  type: kopia
+  url: http://kopia.host.or.ip:port
+  username: username
+  password: password
+  snapshotHost: hostname # optional
+  snapshotPath: path # optional
+```