Fix: jsonrpchandler requires mappings (#3970)

Co-authored-by: Crowdin Bot <support+bot@crowdin.com>

.devcontainer/Dockerfile

@@ -3,4 +3,10 @@ FROM mcr.microsoft.com/vscode/devcontainers/javascript-node:${VARIANT}
 
 RUN npm install -g pnpm
 
+RUN apt-get update \
+   && apt-get -y install --no-install-recommends \
+        python3-pip \
+        && apt-get clean -y \
+        && rm -rf /var/lib/apt/lists/*
+
 ENV PATH="${PATH}:./node_modules/.bin"

.devcontainer/devcontainer.json

@@ -1,27 +1,26 @@
 {
-	"name": "homepage",
-	"build": {
-		"dockerfile": "Dockerfile",
-		"args": {
-			"VARIANT": "18-bullseye"
-		}
-	},
-	"customizations": {
-		"vscode": {
-			"extensions": [
-				"dbaeumer.vscode-eslint",
-				"mhutchie.git-graph",
-				"streetsidesoftware.code-spell-checker",
-			],
-			"settings": {
-				"eslint.format.enable": true,
-				"eslint.lintTask.enable": true,
-				"eslint.packageManager": "pnpm"
-			}
-		}
-	},
-	"postCreateCommand": ".devcontainer/setup.sh",
-	"forwardPorts": [
-		3000
-	]
+  "name": "homepage",
+  "build": {
+    "dockerfile": "Dockerfile",
+    "args": {
+      "VARIANT": "18-bullseye",
+    },
+  },
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "dbaeumer.vscode-eslint",
+        "mhutchie.git-graph",
+        "streetsidesoftware.code-spell-checker",
+        "esbenp.prettier-vscode",
+      ],
+      "settings": {
+        "eslint.format.enable": true,
+        "eslint.lintTask.enable": true,
+        "eslint.packageManager": "pnpm",
+      },
+    },
+  },
+  "postCreateCommand": ".devcontainer/setup.sh",
+  "forwardPorts": [3000],
 }

.devcontainer/setup.sh

@@ -3,6 +3,8 @@
 # Install Node packages
 pnpm install
 
+python3 -m pip install -r requirements.txt
+
 # Copy in skeleton configuration if there is no existing configuration
 if [ ! -d "config/" ]; then
   echo "Adding skeleton config"

.editorconfig

@@ -11,3 +11,6 @@ charset = utf-8
 trim_trailing_whitespace = true
 insert_final_newline = true
 max_line_length = 120
+
+[*.md]
+trim_trailing_whitespace = false

.eslintrc.json

@@ -13,6 +13,12 @@
       {
         "newlines-between": "always"
       }
+    ],
+    "no-else-return": [
+      "error",
+      {
+        "allowElseIf": true
+      }
     ]
   },
   "settings": {

.github/DISCUSSION_TEMPLATE/support.yml

@@ -0,0 +1,56 @@
+body:
+  - type: markdown
+    attributes:
+      value: |
+        ### ⚠️ Before opening a discussion:
+
+        - [Check the troubleshooting guide](https://gethomepage.dev/latest/troubleshooting/).
+        - [Search 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:
+      label: Description
+      description: A clear and concise description of the issue or question. If applicable, add screenshots to help explain your problem.
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: homepage version
+      placeholder: e.g. v0.4.18 (4ea2798)
+    validations:
+      required: true
+  - type: dropdown
+    id: install-method
+    attributes:
+      label: Installation method
+      options:
+        - Docker
+        - Unraid
+        - Source
+        - Other (please describe above)
+    validations:
+      required: true
+  - type: textarea
+    id: config
+    attributes:
+      label: Configuration
+      description: Please provide any relevant service, widget or otherwise related configuration here
+      render: yaml
+  - type: textarea
+    id: container-logs
+    attributes:
+      label: Container Logs
+      description: Please review and provide any logs from the container, if relevant
+  - type: textarea
+    id: browser-logs
+    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 relevant.
+    validations:
+      required: true

.github/FUNDING.yml

@@ -1,3 +1,3 @@
-github: benphelps
-ko_fi: benphelps
-custom: ["https://paypal.me/phelpsben"]
+github: [gethomepage]
+open_collective: homepage
+patreon: gethomepage

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -1,99 +1,33 @@
-name: Bug report
-description: Create a report to help us improve
-title: "[Bug] Concise description of the issue"
-labels: ["bug, unconfirmed"]
+name: 🐛 Bug report
+description: Please only raise an issue if you've been advised to do so in a GitHub discussion. Thanks! 🙏
+labels: ["bug"]
 body:
   - type: markdown
     attributes:
       value: |
-        ## ⚠️ 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/benphelps/homepage/discussions/new) or [ask in chat](https://discord.gg/SaPGSzrEZC).
-
-        Before opening an issue, please double check:
-
-        - [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).
-  - type: textarea
-    id: description
-    attributes:
-      label: Description
-      description: A clear and concise description of what the bug is. If applicable, add screenshots to help explain your problem.
-      placeholder: |
-        Currently homepage does not work when...
-
-        [Screenshot if applicable]
-    validations:
-      required: true
-  - type: textarea
-    id: reproduction
-    attributes:
-      label: Steps to reproduce
-      description: Steps to reproduce the behavior.
-      placeholder: |
-        1. Go to '...'
-        2. Click on '....'
-        3. See error
-    validations:
-      required: true
-  - type: input
-    id: version
-    attributes:
-      label: homepage version
-      placeholder: e.g. v0.4.18 (4ea2798)
-    validations:
-      required: true
-  - type: dropdown
-    id: install-method
-    attributes:
-      label: Installation method
-      options:
-        - Docker
-        - Unraid
-        - Source
-        - Other (please describe above)
-    validations:
-      required: true
-  - type: textarea
-    id: config
-    attributes:
-      label: Configuration
-      description: Please provide any relevant service, widget or otherwise related configuration here
-      render: yaml
-  - type: textarea
-    id: container-logs
-    attributes:
-      label: Container Logs
-      description: Please review and provide any logs from the container, if relevant
-  - type: textarea
-    id: browser-logs
-    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: Include any other relevant details. E.g. service version or API version, docker version, etc.
+        ## ⚠️ Please note
+        The starting point for a bug report should always be a [GitHub discussion](https://github.com/gethomepage/homepage/discussions/new?category=support)
+        Thank you for contributing to homepage! ✊
   - type: checkboxes
     id: pre-flight
     attributes:
-      label: Before submitting, I have made sure to
+      label: Before submitting, please confirm the following
       options:
-        - label: Check [the documentation](https://gethomepage.dev/)
+        - label: I confirm this was discussed, and the maintainers asked that I open an issue.
           required: true
-        - 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: I am aware that if I create this issue without a discussion, it will be removed without a response.
           required: true
+  - type: input
+    id: discussion
+    attributes:
+      label: Discussion Link
+      description: |
+        Please link to the GitHub discussion that led to this issue.
+    validations:
+      required: true
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional context
+      description: Optional
+      render: Text

.github/ISSUE_TEMPLATE/config.yml

@@ -1,11 +1,11 @@
 blank_issues_enabled: false
 contact_links:
   - name: 🤔 Questions and Help
-    url: https://github.com/benphelps/homepage/discussions
-    about: This issue tracker is for bugs only, not general support questions. Please refer to our Discussions.
+    url: https://github.com/gethomepage/homepage/discussions
+    about: For support, possible bug reports or general questions.
   - 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/benphelps/homepage/discussions/new?category=feature-requests
+    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

@@ -1,12 +1,12 @@
 ## Proposed change
 
 <!--
-Please include a summary of the change. Screenshots and / or videos can also be helpful if appropriate.
+Please include a summary of the change. Screenshots and/or videos can also be helpful if appropriate.
 
 *** 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.
+New service widgets should include example(s) of relevant API output as well as updates to the docs for the new widget.
 -->
 
 Closes # (issue)
@@ -25,7 +25,7 @@ What type of change does your PR introduce to Homepage?
 
 ## Checklist:
 
-- [ ] 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).
-- [ ] If applicable, I have checked that all tests pass with e.g. `pnpm lint`.
+- [ ] If applicable, I have added corresponding documentation changes.
+- [ ] If applicable, I have reviewed the [feature](https://gethomepage.dev/latest/more/development/#new-feature-guidelines) and / or [service widget guidelines](https://gethomepage.dev/latest/more/development/#service-widget-guidelines).
+- [ ] I have checked that all code style checks pass using [pre-commit hooks](https://gethomepage.dev/latest/more/development/#code-formatting-with-pre-commit-hooks) and [linting checks](https://gethomepage.dev/latest/more/development/#code-linting).
 - [ ] If applicable, I have tested my code for new features & regressions on both mobile & desktop devices, using the latest version of major browsers.

.github/dependabot.yml

@@ -5,7 +5,11 @@
 
 version: 2
 updates:
-  - package-ecosystem: "github-actions" # Maintain dependencies for GitHub Actions
+  - package-ecosystem: "github-actions"
     directory: "/"
     schedule:
       interval: "daily"
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "monthly"

.github/workflows/crowdin.yml

@@ -0,0 +1,31 @@
+name: Crowdin Action
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: '2 */12 * * *'
+  push:
+    paths: [
+      '/public/locales/en/**',
+    ]
+    branches: [ main ]
+
+jobs:
+  synchronize-with-crowdin:
+    name: Crowdin Sync
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v4
+    - name: crowdin action
+      uses: crowdin/github-action@v2
+      with:
+        upload_translations: false
+        download_translations: true
+        crowdin_branch_name: main
+        localization_branch_name: l10n_main
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        CROWDIN_PROJECT_ID: ${{ secrets.CROWDIN_PROJECT_ID }}
+        CROWDIN_PERSONAL_TOKEN: ${{ secrets.CROWDIN_PERSONAL_TOKEN }}

.github/workflows/docker-publish.yml

@@ -9,7 +9,9 @@ on:
   schedule:
     - cron: '20 0 * * *'
   push:
-    branches: [ "main" ]
+    branches:
+      - main
+      - feature/**
     # Publish semver tags as releases.
     tags: [ 'v*.*.*' ]
     paths-ignore:
@@ -20,6 +22,7 @@ on:
     paths-ignore:
       - 'docs/**'
       - 'mkdocs.yml'
+  merge_group:
 
 env:
   # Use docker.io for Docker Hub if empty
@@ -29,10 +32,28 @@ env:
 
 
 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@v5
+        with:
+          python-version: 3.x
+      -
+        name: Check files
+        uses: pre-commit/action@v3.0.1
+
   build:
     name: Docker Build & Push
-    if:  github.repository == 'benphelps/homepage'
+    if:  github.repository == 'gethomepage/homepage'
     runs-on: self-hosted
+    needs:
+      - pre-commit
     permissions:
       contents: read
       packages: write
@@ -47,7 +68,7 @@ jobs:
       # Install the cosign tool except on PR
       # https://github.com/sigstore/cosign-installer
       - name: Install cosign
-        if: github.event_name != 'pull_request' 
+        if: github.event_name != 'pull_request'
         uses: sigstore/cosign-installer@main
         with:
           cosign-release: 'v1.13.1' # optional
@@ -56,11 +77,11 @@ jobs:
       # https://github.com/marketplace/actions/docker-setup-buildx#with-qemu
       - name: Setup QEMU
         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@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
@@ -95,17 +116,16 @@ jobs:
       # https://github.com/docker/build-push-action
       - name: Build and push Docker image
         id: build-and-push
-        uses: docker/build-push-action@v5
+        uses: docker/build-push-action@v6
         with:
           context: .
-          push: ${{ github.event_name != 'pull_request' }}
+          push: ${{ github.event_name != 'pull_request' && !(github.event_name == 'push' && startsWith(github.ref, 'refs/heads/feature')) }}
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
           build-args: |
             BUILDTIME=${{ fromJSON(steps.meta.outputs.json).labels['org.opencontainers.image.created'] }}
             VERSION=${{ fromJSON(steps.meta.outputs.json).labels['org.opencontainers.image.version'] }}
             REVISION=${{ fromJSON(steps.meta.outputs.json).labels['org.opencontainers.image.revision'] }}
-            DEPRECATED_REPO=${{ fromJSON(steps.meta.outputs.json).labels['org.opencontainers.image.source'] == 'https://github.com/benphelps/homepage' }}
           # https://github.com/docker/setup-qemu-action#about
           # platforms: linux/amd64,linux/arm64,linux/riscv64,linux/ppc64le,linux/s390x,linux/386,linux/mips64le,linux/mips64,linux/arm/v7,linux/arm/v6
           platforms: linux/amd64,linux/arm64,linux/arm/v7,linux/arm/v6

.github/workflows/docs-publish.yml

@@ -2,32 +2,48 @@ name: Docs
 
 on:
   push:
-    tags: [ 'v*.*.*' ]
-    branches: ['main']
+    tags: ["v*.*.*"]
+    branches: ["main"]
     paths:
-      - 'docs/**'
-      - 'mkdocs.yml'
+      - "docs/**"
+      - "mkdocs.yml"
   pull_request:
     paths:
-      - 'docs/**'
-      - 'mkdocs.yml'
+      - "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@v5
+        with:
+          python-version: 3.x
+      - name: Check files
+        uses: pre-commit/action@v3.0.1
+
   test:
     name: Test Build
-    if: github.repository == 'benphelps/homepage' && github.event_name == 'pull_request'
+    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
+      - uses: actions/setup-python@v5
         with:
           python-version: 3.x
       - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
-      - uses: actions/cache@v3
+      - uses: actions/cache@v4
         with:
           key: mkdocs-material-${{ env.cache_id }}
           path: .cache
@@ -35,30 +51,33 @@ jobs:
             mkdocs-material-
       - run: sudo apt-get install pngquant
       - run: pip install mike
-      - run: pip install mkdocs-material
+      - run: pip install mkdocs-material mkdocs-redirects "mkdocs-material[imaging]"
       - name: Test Docs Build
         run: MKINSIDERS=false mkdocs build
   deploy:
-    name: Build & Deploy 
-    if: github.repository == 'benphelps/homepage' && github.event_name != 'pull_request'
+    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
+      - uses: actions/setup-python@v5
         with:
           python-version: 3.x
-      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
-      - uses: actions/cache@v3
+      - run: echo "cache_id=${{github.sha}}" >> $GITHUB_ENV
+      - uses: actions/cache@v4
         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 mike==2.0.0
       - run: pip install git+https://${GH_TOKEN}@github.com/benphelps/mkdocs-material-insiders.git
+      - run: pip install mkdocs-redirects "mkdocs-material[imaging]"
       - name: Set Git config
         run: |
           git config --global user.name "GitHub Action"

.github/workflows/repo-maintenance.yml

@@ -0,0 +1,280 @@
+name: 'Repository Maintenance'
+
+on:
+  schedule:
+    - cron: '0 3 * * *'
+  workflow_dispatch:
+
+permissions:
+  issues: write
+  pull-requests: write
+  discussions: write
+
+concurrency:
+  group: lock
+
+jobs:
+  stale:
+    name: 'Stale'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/stale@v9
+        with:
+          days-before-stale: 7
+          days-before-close: 14
+          stale-issue-label: stale
+          stale-pr-label: stale
+          stale-issue-message: >
+            This issue has been automatically marked as stale because it has not had
+            recent activity. It will be closed if no further activity occurs. Thank you
+            for your contributions. See our [contributing guidelines](https://github.com/gethomepage/homepage/blob/main/CONTRIBUTING.md#automatic-respoistory-maintenance) for more details.
+  lock-threads:
+    name: 'Lock Old Threads'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: dessant/lock-threads@v5
+        with:
+          issue-inactive-days: '30'
+          pr-inactive-days: '30'
+          discussion-inactive-days: '30'
+          log-output: true
+          issue-comment: >
+            This issue has been automatically locked since there
+            has not been any recent activity after it was closed.
+            Please open a new discussion for related concerns.
+            See our [contributing guidelines](https://github.com/gethomepage/homepage/blob/main/CONTRIBUTING.md#automatic-repository-maintenance) for more details.
+          pr-comment: >
+            This pull request has been automatically locked since there
+            has not been any recent activity after it was closed.
+            Please open a new discussion for related concerns.
+            See our [contributing guidelines](https://github.com/gethomepage/homepage/blob/main/CONTRIBUTING.md#automatic-repository-maintenance) for more details.
+          discussion-comment: >
+            This discussion has been automatically locked since there
+            has not been any recent activity after it was closed.
+            Please open a new discussion for related concerns.
+            See our [contributing guidelines](https://github.com/gethomepage/homepage/blob/main/CONTRIBUTING.md#automatic-repository-maintenance) for more details.
+  close-answered-discussions:
+    name: 'Close Answered Discussions'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/github-script@v7
+        with:
+          script: |
+            function sleep(ms) {
+              return new Promise(resolve => setTimeout(resolve, ms));
+            }
+
+            const query = `query($owner:String!, $name:String!) {
+              repository(owner:$owner, name:$name){
+                discussions(first:100, answered:true, states:[OPEN]) {
+                  nodes {
+                    id,
+                    number
+                  }
+                }
+              }
+            }`;
+            const variables = {
+              owner: context.repo.owner,
+              name: context.repo.repo,
+            }
+            const result = await github.graphql(query, variables)
+
+            console.log(`Found ${result.repository.discussions.nodes.length} open answered discussions`)
+
+            for (const discussion of result.repository.discussions.nodes) {
+              console.log(`Closing discussion #${discussion.number} (${discussion.id})`)
+
+              const addCommentMutation = `mutation($discussion:ID!, $body:String!) {
+                addDiscussionComment(input:{discussionId:$discussion, body:$body}) {
+                  clientMutationId
+                }
+              }`;
+              const commentVariables = {
+                discussion: discussion.id,
+                body: 'This discussion has been automatically closed because it was marked as answered. See our [contributing guidelines](https://github.com/gethomepage/homepage/blob/main/CONTRIBUTING.md#automatic-repository-maintenance) for more details.',
+              }
+              await github.graphql(addCommentMutation, commentVariables)
+
+              const closeDiscussionMutation = `mutation($discussion:ID!, $reason:DiscussionCloseReason!) {
+                closeDiscussion(input:{discussionId:$discussion, reason:$reason}) {
+                  clientMutationId
+                }
+              }`;
+              const closeVariables = {
+                discussion: discussion.id,
+                reason: "RESOLVED",
+              }
+              await github.graphql(closeDiscussionMutation, closeVariables)
+
+              await sleep(1000)
+            }
+  close-outdated-discussions:
+    name: 'Close Outdated Discussions'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/github-script@v7
+        with:
+          script: |
+            function sleep(ms) {
+              return new Promise(resolve => setTimeout(resolve, ms));
+            }
+
+            const CUTOFF_DAYS = 180;
+            const cutoff = new Date();
+            cutoff.setDate(cutoff.getDate() - CUTOFF_DAYS);
+
+            const query = `query(
+                $owner:String!,
+                $name:String!,
+                $supportCategory:ID!,
+                $generalCategory:ID!,
+              ) {
+              supportDiscussions: repository(owner:$owner, name:$name){
+                discussions(
+                  categoryId:$supportCategory,
+                  last:50,
+                  answered:false,
+                  states:[OPEN],
+                ) {
+                  nodes {
+                    id,
+                    number,
+                    updatedAt
+                  }
+                },
+              },
+              generalDiscussions: repository(owner:$owner, name:$name){
+                discussions(
+                  categoryId:$generalCategory,
+                  last:50,
+                  states:[OPEN],
+                ) {
+                  nodes {
+                    id,
+                    number,
+                    updatedAt
+                  }
+                }
+              }
+            }`;
+            const variables = {
+              owner: context.repo.owner,
+              name: context.repo.repo,
+              supportCategory: "DIC_kwDOH31rQM4CRErR",
+              generalCategory: "DIC_kwDOH31rQM4CRErQ"
+            }
+            const result = await github.graphql(query, variables);
+            const combinedDiscussions = [
+              ...result.supportDiscussions.discussions.nodes,
+              ...result.generalDiscussions.discussions.nodes,
+            ]
+
+            console.log(`Checking ${combinedDiscussions.length} open discussions`);
+
+            for (const discussion of combinedDiscussions) {
+              if (new Date(discussion.updatedAt) < cutoff) {
+                console.log(`Closing outdated discussion #${discussion.number} (${discussion.id}), last updated at ${discussion.updatedAt}`);
+                const addCommentMutation = `mutation($discussion:ID!, $body:String!) {
+                  addDiscussionComment(input:{discussionId:$discussion, body:$body}) {
+                    clientMutationId
+                  }
+                }`;
+                const commentVariables = {
+                  discussion: discussion.id,
+                  body: 'This discussion has been automatically closed due to inactivity. See our [contributing guidelines](https://github.com/gethomepage/homepage/blob/main/CONTRIBUTING.md#automatic-repository-maintenance) for more details.',
+                }
+                await github.graphql(addCommentMutation, commentVariables);
+
+                const closeDiscussionMutation = `mutation($discussion:ID!, $reason:DiscussionCloseReason!) {
+                  closeDiscussion(input:{discussionId:$discussion, reason:$reason}) {
+                    clientMutationId
+                  }
+                }`;
+                const closeVariables = {
+                  discussion: discussion.id,
+                  reason: "OUTDATED",
+                }
+                await github.graphql(closeDiscussionMutation, closeVariables);
+
+                await sleep(1000);
+              }
+            }
+  close-unsupported-feature-requests:
+    name: 'Close Unsupported Feature Requests'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/github-script@v7
+        with:
+          script: |
+            function sleep(ms) {
+              return new Promise(resolve => setTimeout(resolve, ms));
+            }
+
+            const CUTOFF_1_DAYS = 180;
+            const CUTOFF_1_COUNT = 5;
+            const CUTOFF_2_DAYS = 365;
+            const CUTOFF_2_COUNT = 10;
+
+            const cutoff1Date = new Date();
+            cutoff1Date.setDate(cutoff1Date.getDate() - CUTOFF_1_DAYS);
+            const cutoff2Date = new Date();
+            cutoff2Date.setDate(cutoff2Date.getDate() - CUTOFF_2_DAYS);
+
+            const query = `query(
+                $owner:String!,
+                $name:String!,
+                $featureRequestsCategory:ID!,
+              ) {
+              repository(owner:$owner, name:$name){
+                discussions(
+                  categoryId:$featureRequestsCategory,
+                  last:100,
+                  states:[OPEN],
+                ) {
+                  nodes {
+                    id,
+                    number,
+                    updatedAt,
+                    upvoteCount,
+                  }
+                },
+              }
+            }`;
+            const variables = {
+              owner: context.repo.owner,
+              name: context.repo.repo,
+              featureRequestsCategory: "DIC_kwDOH31rQM4CRErS"
+            }
+            const result = await github.graphql(query, variables);
+
+            for (const discussion of result.repository.discussions.nodes) {
+              const discussionDate = new Date(discussion.updatedAt);
+              if ((discussionDate < cutoff1Date && discussion.upvoteCount < CUTOFF_1_COUNT) ||
+                  (discussionDate < cutoff2Date && discussion.upvoteCount < CUTOFF_2_COUNT)) {
+                console.log(`Closing discussion #${discussion.number} (${discussion.id}), last updated at ${discussion.updatedAt} with votes ${discussion.upvoteCount}`);
+                const addCommentMutation = `mutation($discussion:ID!, $body:String!) {
+                  addDiscussionComment(input:{discussionId:$discussion, body:$body}) {
+                    clientMutationId
+                  }
+                }`;
+                const commentVariables = {
+                  discussion: discussion.id,
+                  body: 'This discussion has been automatically closed due to lack of community support. See our [contributing guidelines](https://github.com/gethomepage/homepage/blob/main/CONTRIBUTING.md#automatic-repository-maintenance) for more details.',
+                }
+                await github.graphql(addCommentMutation, commentVariables);
+
+                const closeDiscussionMutation = `mutation($discussion:ID!, $reason:DiscussionCloseReason!) {
+                  closeDiscussion(input:{discussionId:$discussion, reason:$reason}) {
+                    clientMutationId
+                  }
+                }`;
+                const closeVariables = {
+                  discussion: discussion.id,
+                  reason: "OUTDATED",
+                }
+                await github.graphql(closeDiscussionMutation, closeVariables);
+
+                await sleep(1000);
+              }
+            }

.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 @@
+{}

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 [discussions](https://github.com/gethomepage/homepage/discussions)
+
+We use GitHub discussions to triage bugs. Report a bug by [opening a new discussion](https://github.com/gethomepage/homepage/discussions/new?category=support); it's that easy! Please do not open an issue unless instructed to do so by a project maintainer.
 
 ## 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,16 +34,38 @@ 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/#code-formatting-with-pre-commit-hooks).
 
 ## License
+
 By contributing, you agree that your contributions will be licensed under its GNU General Public License.
 
+## Use of AI for pull requests
+
+In general, homepage does not accept "AI-generated" PRs. If you choose to use something like that to aid the development process to generate a significant proportion of the pull request, please make sure this is explicitly stated in the PR itself.
+
 ## 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)
+
+## Automatic Respository Maintenance
+
+The homepage team appreciates all effort and interest from the community in filing bug reports, creating feature requests, sharing ideas and helping other community members. That said, in an effort to keep the repository organized and managebale the project uses automatic handling of certain areas:
+
+- Issues, pull requests and discussions that are closed will be locked after 30 days of inactivity.
+- Discussions with a marked answer will be automatically closed.
+- Discussions in the 'General' or 'Support' categories will be closed after 180 days of inactivity.
+- Feature requests that do not meet the following thresholds will be closed: 5 "up-votes" after 180 days of inactivity or 10 "up-votes" after 365 days.
+
+In all cases, threads can be re-opened by project maintainers and, of course, users can always create a new discussion for related concerns.
+Finally, remember that all information remains searchable and 'closed' feature requests can still serve as inspiration for new features.
+
+Thank you all for your contributions.

Dockerfile

@@ -23,7 +23,6 @@ WORKDIR /app
 ARG BUILDTIME
 ARG VERSION
 ARG REVISION
-ARG DEPRECATED_REPO
 
 COPY --link --from=deps /app/node_modules ./node_modules/
 COPY . .
@@ -31,15 +30,15 @@ COPY . .
 SHELL ["/bin/ash", "-xeo", "pipefail", "-c"]
 RUN npm run telemetry \
  && mkdir config \
- && NEXT_PUBLIC_BUILDTIME=$BUILDTIME NEXT_PUBLIC_VERSION=$VERSION NEXT_PUBLIC_REVISION=$REVISION NEXT_PUBLIC_DEPRECATED_REPO=$DEPRECATED_REPO npm run build
+ && 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

@@ -14,15 +14,24 @@
 </p>
 
 <p align="center">
-  <a href="https://github.com/benphelps/homepage/actions/workflows/docker-publish.yml"><img alt="GitHub Workflow Status (with event)" src="https://img.shields.io/github/actions/workflow/status/benphelps/homepage/docker-publish.yml"></a>
+  <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://hosted.weblate.org/engage/homepage/"><img src="https://hosted.weblate.org/widgets/homepage/-/homepage/svg-badge.svg" alt="Weblate"></a>
+  <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://www.digitalocean.com/?refcode=df14bcb7c016&utm_campaign=Referral_Invite&utm_medium=Referral_Program&utm_source=badge"><img src="https://web-platforms.sfo2.cdn.digitaloceanspaces.com/WWW/Badge%201.svg" alt="DigitalOcean Referral Badge" /></a>
+</p>
+<p align="center">
+<em>Homepage builds are kindly powered by DigitalOcean.</em>
+</p>
+
 # Features
 
 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.
@@ -39,15 +48,15 @@ With features like quick search, bookmarks, weather support, a wide range of int
 
 ## Docker Integration
 
-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.
+Homepage has built-in support for Docker, and can automatically discover and add services to the homepage based on labels. See the [Docker Service Discovery](https://gethomepage.dev/latest/configs/docker/#automatic-service-discovery) page for more information.
 
 ## Service Widgets
 
-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.
+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/widgets/) page for more information.
 
 ## Information Widgets
 
-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.
+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/widgets/) page for more information.
 
 ## Customization
 
@@ -57,19 +66,22 @@ Homepage is highly customizable, with support for custom themes, custom CSS & JS
 
 For configuration options, examples and more, [please check out the homepage documentation](http://gethomepage.dev).
 
+## Security Notice 🔒
+
+Please note that when using features such as widgets, Homepage can access personal information (for example from your home automation system) and Homepage currently does not (and is not planned to) include any authentication layer itself. Thus, we recommend homepage be deployed behind a reverse proxy including authentication, SSL etc, and / or behind a VPN.
+
 ## With Docker
 
 Using docker compose:
 
 ```yaml
-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
+      PUID: 1000 # optional, your user id
+      PGID: 1000 # optional, your group id
     ports:
       - 3000:3000
     volumes:
@@ -88,15 +100,15 @@ docker run --name homepage \
   -v /path/to/config:/app/config \
   -v /var/run/docker.sock:/var/run/docker.sock:ro \
   --restart unless-stopped \
-  ghcr.io/benphelps/homepage:latest
+  ghcr.io/gethomepage/homepage:latest
 ```
 
-## With Node
+## From Source
 
 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):
@@ -114,15 +126,9 @@ Finally, run the server in production mode:
 pnpm start
 ```
 
-or development mode:
-
-```bash
-pnpm dev
-```
-
 # Configuration
 
-Please refere 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.
+Please refer to the [homepage documentation website](https://gethomepage.dev/) 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
 
@@ -144,6 +150,8 @@ This is a [Next.js](https://nextjs.org/) application, see their documentation fo
 
 # Documentation
 
+The homepage documentation is available at [https://gethomepage.dev/](https://gethomepage.dev/).
+
 Homepage uses Material for MkDocs for documentation. To run the documentation locally, first install the dependencies:
 
 ```bash
@@ -158,11 +166,13 @@ mkdocs serve # or build, to build the static site
 
 # Support & Suggestions
 
-If you have any questions, suggestions, or general issues, please start a discussion on the [Discussions](https://github.com/benphelps/homepage/discussions) page.
+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/benphelps/homepage/issues) page.
+## Troubleshooting
 
-## Contributing & Contributers
+In addition to the docs, the [troubleshooting guide](https://gethomepage.dev/latest/troubleshooting/) can help reveal many basic config or network issues. If you're having a problem, it's a good place to start.
+
+## Contributing & Contributors
 
 Contributions are welcome! Please see the [CONTRIBUTING.md](CONTRIBUTING.md) file for more information.
 

crowdin.yml

@@ -0,0 +1,6 @@
+project_id_env: CROWDIN_PROJECT_ID
+api_token_env: CROWDIN_PERSONAL_TOKEN
+preserve_hierarchy: true
+files:
+  - source: /public/locales/en/*.json
+    translation: /public/locales/%osx_locale%/%original_file_name%

docs/configs/bookmarks.md

@@ -3,7 +3,7 @@ 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.
+Bookmarks are configured in the `bookmarks.yaml` file. They 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.
 
@@ -12,21 +12,26 @@ You can also use an icon for bookmarks similar to the [options for service icons
 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/
+    - Github:
+        - abbr: GH
+          href: https://github.com/
 
 - Social:
-      - Reddit:
-            - icon: reddit.png
-              href: https://reddit.com/
-              description: The front page of the internet
+    - Reddit:
+        - icon: reddit.png
+          href: https://reddit.com/
+          description: The front page of the internet
 
 - Entertainment:
-      - YouTube:
-            - abbr: YT
-              href: https://youtube.com/
+    - YouTube:
+        - abbr: YT
+          href: https://youtube.com/
 ```
 
+which renders to (depending on your theme, etc.):
+
 <img width="1000" alt="Bookmarks" src="https://user-images.githubusercontent.com/19408/269307009-d7e45885-230f-4e07-b421-9822017ae878.png">
+
+The default [bookmarks.yaml](https://github.com/gethomepage/homepage/blob/main/src/skeleton/bookmarks.yaml) is a working example.

docs/configs/docker.md

@@ -9,8 +9,8 @@ For IP:PORT, simply make sure your Docker instance [has been configured](https:/
 
 ```yaml
 my-remote-docker:
-    host: 192.168.0.101
-    port: 2375
+  host: 192.168.0.101
+  port: 2375
 ```
 
 ## Using Docker TLS
@@ -19,12 +19,12 @@ Since Docker supports connecting with TLS and client certificate authentication,
 
 ```yaml
 my-remote-docker:
-    host: 192.168.0.101
-    port: 275
-    tls:
-        keyFile: tls/key.pem
-        caFile: tls/ca.pem
-        certFile: tls/cert.pem
+  host: 192.168.0.101
+  port: 275
+  tls:
+    keyFile: tls/key.pem
+    caFile: tls/ca.pem
+    certFile: tls/cert.pem
 ```
 
 ## Using Docker Socket Proxy
@@ -35,35 +35,35 @@ Here is an example docker-compose file that will expose the docker socket, and t
 
 ```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
+  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/benphelps/homepage:latest
-    container_name: homepage
-    volumes:
-        - /path/to/config:/app/config
-    ports:
-        - 3000:3000
-    restart: unless-stopped
+  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
+  host: dockerproxy
+  port: 2375
 ```
 
 ## Using Socket Directly
@@ -76,14 +76,14 @@ If you'd rather use the socket directly, first make sure that you're passing the
 
 ```yaml
 homepage:
-    image: ghcr.io/benphelps/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
+  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`.
@@ -92,7 +92,7 @@ Then, inside of your `docker.yaml` settings file, you'd configure the docker ins
 
 ```yaml
 my-docker:
-    socket: /var/run/docker.sock
+  socket: /var/run/docker.sock
 ```
 
 ## Services
@@ -118,18 +118,18 @@ 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
+  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.**
@@ -142,15 +142,32 @@ You may also configure widgets, along with the standard service entry, again, us
 
 ```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
+  - 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.md) 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.mappings[0].label=Deployed Version
+  - homepage.widget.mappings[0].field.status=deployed_version
+  - homepage.widget.mappings[1].label=Latest Version
+  - homepage.widget.mappings[1].field.status=latest_version
 ```
 
 ## Docker Swarm
@@ -159,8 +176,8 @@ Docker swarm is supported and Docker services are specified with the same `serve
 
 ```yaml
 my-docker:
-    socket: /var/run/docker.sock
-    swarm: true
+  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.
@@ -184,13 +201,29 @@ In order to detect every service within the Docker swarm it is necessary that se
 ...
 ```
 
+## Multiple Homepage Instances
+
+The optional field `instanceName` can be configured in [settings.yaml](settings.md#instance-name) to differentiate between multiple homepage instances.
+
+To limit a label to an instance, insert `.instance.{{instanceName}}` after the `homepage` prefix.
+
+```yaml
+labels:
+  - homepage.group=Media
+  - homepage.name=Emby
+  - homepage.icon=emby.png
+  - homepage.instance.internal.href=http://emby.lan/
+  - homepage.instance.public.href=https://emby.mydomain.com/
+  - homepage.description=Media server
+```
+
 ## 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
+- 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
 
@@ -202,4 +235,4 @@ You can show the docker stats by clicking the status indicator but this can also
   showStats: true
 ```
 
-Also see the settings for [show docker stats](docker.md#show-docker-stats).
+Also see the settings for [show docker stats](settings.md#show-docker-stats).

docs/configs/index.md

@@ -1,6 +1,7 @@
 ---
 title: Configuration
 description: Homepage Configuration
+icon: material/cog
 ---
 
 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.

docs/configs/kubernetes.md

@@ -5,15 +5,15 @@ description: Kubernetes Configuration
 
 The Kubernetes connectivity has the following requirements:
 
--   Kubernetes 1.19+
--   Metrics Service
--   An Ingress controller
+- 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
+- **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
@@ -42,18 +42,18 @@ For instance, it can be utilized to roll multiple underlying deployments under o
 
 ```yaml
 - Element Chat:
-      icon: matrix-light.png
-      href: https://chat.example.com
-      description: Matrix Synapse Powered Chat
-      app: matrix-element
-      namespace: comms
-      podSelector: >-
-          app.kubernetes.io/instance in (
-              matrix-element,
-              matrix-media-repo,
-              matrix-media-repo-postgresql,
-              matrix-synapse
-          )
+    icon: matrix-light.png
+    href: https://chat.example.com
+    description: Matrix Synapse Powered Chat
+    app: matrix-element
+    namespace: comms
+    podSelector: >-
+      app.kubernetes.io/instance in (
+          matrix-element,
+          matrix-media-repo,
+          matrix-media-repo-postgresql,
+          matrix-synapse
+      )
 ```
 
 !!! note
@@ -68,33 +68,38 @@ Homepage features automatic service discovery by Ingress annotations. All config
 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/podSelector: ""
-        gethomepage.dev/weight: 10 # optional
+  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
+    gethomepage.dev/instance: "public" # optional
 spec:
-    rules:
-        - host: emby.example.com
-          http:
-              paths:
-                  - backend:
-                        service:
-                            name: emby
-                            port:
-                                number: 8080
-                    path: /
-                    pathType: Prefix
+  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.**
 
+If you are using multiple instances of homepage, an `instance` annotation can be specified to limit services to a specific instance. If no instance is provided, the service will be visible on all instances.
+
+If you have a single service that needs to be shown on multiple specific instances of homepage (but not on all of them), the service can be annotated by multiple `instance.name` annotations, where `name` can be the names of your specific multiple homepage instances. For example, a service that is annotated with `gethomepage.dev/instance.public: ""` and `gethomepage.dev/instance.internal: ""` will be shown on `public` and `internal` homepage instances.
+
 ### 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:
@@ -103,32 +108,34 @@ Homepage can also read ingresses defined using the Traefik IngressRoute custom r
 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/name: Emby
-        gethomepage.dev/widget.type: "emby"
-        gethomepage.dev/widget.url: "https://emby.example.com"
-        gethomepage.dev/podSelector: ""
-        gethomepage.dev/weight: 10 # optional
+  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
+    gethomepage.dev/instance: "public" # 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
+  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.

docs/configs/service-widgets.md

@@ -5,7 +5,7 @@ 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).
+Each service can have one widget attached to it (often matching the service type, but that's 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.
 
@@ -13,13 +13,13 @@ 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
+    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
@@ -30,11 +30,11 @@ Each widget can optionally provide a list of which fields should be visible via
 
 ```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
+    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

@@ -101,30 +101,50 @@ To use a local icon, first create a Docker mount to `/app/public/icons` and then
 
 ## 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.
+Services may have an optional `ping` property that allows you to monitor the availability of an external host. As of v0.8.0, the ping feature attempts to use a true (ICMP) ping command on the underlying host. Currently, only IPv4 is supported.
 
 ```yaml
 - Group A:
     - Sonarr:
         icon: sonarr.png
         href: http://sonarr.host/
-        ping: http://sonarr.host/
+        ping: sonarr.host
 
 - Group B:
     - Radarr:
         icon: radarr.png
         href: http://radarr.host/
-        ping: http://some.other.host/
+        ping: some.other.host
 ```
 
-<img width="1038" alt="Ping" src="https://github.com/benphelps/homepage/assets/88257202/7bc13bd3-0d0b-44e3-888c-a20e069a3233">
+<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).
 
+## Site Monitor
+
+Services may have an optional `siteMonitor` property (formerly `ping`) that allows you to monitor the availability of a URL you chose and have the response time displayed. You do not need to set your monitor URL equal to your href or ping URL.
+
+!!! note
+
+    The site monitor 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 site monitor feature correctly display status.
+
+```yaml
+- Group A:
+    - Sonarr:
+        icon: sonarr.png
+        href: http://sonarr.host/
+        siteMonitor: http://sonarr.host/
+
+- Group B:
+    - Radarr:
+        icon: radarr.png
+        href: http://radarr.host/
+        siteMonitor: http://some.other.host/
+```
+
+You can also apply different styles to the site monitor 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.
@@ -145,7 +165,7 @@ Services may be connected to a Docker container, either running on the local mac
         container: other-container
 ```
 
-<img width="1038" alt="Service Containers" src="https://github.com/benphelps/homepage/assets/88257202/4c685783-52c6-4e55-afb3-affe9baac09b">
+<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.**
 
@@ -153,13 +173,13 @@ Services may be connected to a Docker container, either running on the local mac
 
       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/benphelps/homepage/assets/88257202/f95fd595-449e-48ae-af67-fd89618904ec">
+<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.
+You can find information and configuration for each of the supported integrations on the [Widgets](../widgets/index.md) page.
 
 Here is an example of a Radarr & Sonarr service, with their respective integrations.
 

docs/configs/settings.md

@@ -67,7 +67,7 @@ background:
 
 ### 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.
+You can apply a blur filter to the service & bookmark cards. Note this option is incompatible with the background blur, saturate and brightness filters.
 
 ```yaml
 cardBlur: sm # sm, "", md, etc... see https://tailwindcss.com/docs/backdrop-blur
@@ -85,7 +85,7 @@ Or you may pass the path to a local image relative to the `/app/public` director
 
 ## Theme
 
-You can configure a fixed them (and disable the theme switcher) by passing the `theme` option, like so:
+You can configure a fixed theme (and disable the theme switcher) by passing the `theme` option, like so:
 
 ```yaml
 theme: dark # or light
@@ -211,13 +211,13 @@ layout:
 
 ### Five Columns
 
-You can add a fifth column (when `style: columns` which is default) by adding:
+You can add a fifth column to services (when `style: columns` which is default) by adding:
 
 ```yaml
 fiveColumns: true
 ```
 
-By default homepage will max out at 4 columns for column style
+By default homepage will max out at 4 columns for services with `columns` style
 
 ### Collapsible sections
 
@@ -229,6 +229,48 @@ disableCollapse: true
 
 By default the feature is enabled.
 
+### Initially collapsed sections
+
+You can initially collapse sections by adding the `initiallyCollapsed` option to the layout group.
+
+```yaml
+layout:
+  Section A:
+    initiallyCollapsed: true
+```
+
+This can also be set globaly using the `groupsInitiallyCollapsed` option.
+
+```yaml
+groupsInitiallyCollapsed: true
+```
+
+The value set on a group will overwrite the global setting.
+
+By default the feature is disabled.
+
+### Use Equal Height Cards
+
+You can enable equal height cards for groups of services, this will make all cards in a row the same height.
+
+Global setting in `settings.yaml`:
+
+```yaml
+useEqualHeights: true
+```
+
+Per layout group in `settings.yaml`:
+
+```yaml
+useEqualHeights: false
+layout:
+  ...
+  Group Name:
+    useEqualHeights: true # overrides global setting
+```
+
+By default the feature is disabled
+
 ## Header Style
 
 There are currently 4 options for header styles, you can see each one below.
@@ -321,7 +363,7 @@ providers:
 You can then pass `provider` instead of `apiKey` in your widget configuration.
 
 ```yaml
-- weather:
+- weatherapi:
     latitude: 50.449684
     longitude: 30.525026
     provider: weatherapi
@@ -329,21 +371,35 @@ You can then pass `provider` instead of `apiKey` in your widget configuration.
 
 ## 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).
+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 doesn't 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.
+- `searchDescriptions`: which lets you control whether item descriptions are included in searches. This is false 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.
+- `showSearchSuggestions`: show search suggestions for the internet search. If this is not specified then the setting will be inherited from the search widget. If it is not specified there either, it will default to false. For custom providers the `suggestionUrl` needs to be set in order for this to work.
+- `provider`: search engine provider. If none is specified it will try to use the provider set for the Search Widget, if neither are present then internet search will be disabled.
 - `hideVisitURL`: disable detecting and offering an option to open URLs. This is false by default, enabling the feature.
 
 ```yaml
 quicklaunch:
   searchDescriptions: true
   hideInternetSearch: true
+  showSearchSuggestions: true
   hideVisitURL: true
+  provider: google # google, duckduckgo, bing, baidu, brave or custom
+```
+
+or for a custom search:
+
+```yaml
+quicklaunch:
+  provider: custom
+  url: https://www.ecosia.org/search?q=
+  target: _blank
+  suggestionUrl: https://ac.ecosia.org/autocomplete?type=list&q=
 ```
 
 ## Homepage Version
@@ -362,6 +418,8 @@ By default the homepage logfile is written to the a `logs` subdirectory of the `
 logpath: /logfile/path
 ```
 
+By default, logs are sent both to `stdout` and to a file at the path specified. This can be changed by setting the `LOG_TARGETS` environment variable to one of `both` (default), `stdout` or `file`.
+
 ## Show Docker Stats
 
 You can show all docker stats expanded in `settings.yaml`:
@@ -382,16 +440,16 @@ 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`
+You can choose from the following styles for docker or k8s status, site monitor 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
+- The default is no value, and displays the monitor and ping response time in ms and the docker / k8s container status
+- `dot` shows a green dot for a successful monitor ping or healthy status.
+- `basic` shows either UP or DOWN for monitor & ping
 
 For example:
 
 ```yaml
-statusStyle: 'dot'
+statusStyle: "dot"
 ```
 
 or per-service (`services.yaml`) with:
@@ -404,6 +462,16 @@ or per-service (`services.yaml`) with:
 
 If you have both set, the per-service settings take precedence.
 
+## Instance Name
+
+Name used by automatic docker service discovery to differentiate between multiple homepage instances.
+
+For example:
+
+```yaml
+instanceName: public
+```
+
 ## Hide Widget Error Messages
 
 Hide the visible API error messages either globally in `settings.yaml`:
@@ -422,4 +490,4 @@ or per service widget (`services.yaml`) with:
         hideErrors: true
 ```
 
-If either value is set to true, the errror message will be hidden.
+If either value is set to true, the error message will be hidden.

docs/index.md

@@ -1,5 +1,7 @@
 ---
 title: Home
+description: A modern, fully static, fast, secure, fully proxied, highly customizable application dashboard with integrations for over 100 services and translations into multiple languages.
+icon: material/home
 hide:
   - navigation
   - toc
@@ -10,10 +12,21 @@ hide:
 
 <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)
+<div style="max-width: 70%; margin: 0 auto; display: block;">
 
-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.
+<img src="assets/banner_light@2x.webp" alt="homepage" style="max-width: 100%; max-height: 175px; margin: 0 auto; display: block;" />
 
-![Alt text](assets/homepage_demo.png)
+<img src="assets/homepage_demo_clip.webp" alt="homepage" style="max-width: 100%; margin: 0 auto; display: block;" />
+
+<p style="margin: 0 0 30px;">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>
+
+</div>
+
+<style>
+  .md-header__source {
+    display: none;
+  }
+  .md-typeset img, .md-typeset svg, .md-typeset video {
+    box-shadow: none;
+  }
+</style>

docs/installation/docker.md

@@ -6,16 +6,15 @@ description: Install and run homepage from Docker
 Using docker compose:
 
 ```yaml
-version: "3.3"
 services:
-    homepage:
-        image: ghcr.io/benphelps/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
+  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
@@ -27,31 +26,30 @@ _Using the docker socket directly is not the recommended method of integration a
 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/benphelps/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
+  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/benphelps/homepage:latest
+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
+- 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

@@ -1,12 +1,17 @@
 ---
 title: Installation
 description: Docs intro
+icon: simple/docker
 ---
 
 <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>
 
+!!! danger
+
+    Please note that when using features such as widgets, Homepage can access personal information (for example from your home automation system) and Homepage currently does not (and is not planned to) include any authentication layer itself. Thus, we recommend homepage be deployed behind a reverse proxy including authentication, SSL etc, and / or behind a VPN.
+
 <br>
 
 <div class="grid cards" style="margin: 0 auto;" markdown>

docs/installation/k8s.md

@@ -16,70 +16,70 @@ The helm chart allows for all the configurations to be inlined directly in your
 
 ```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
+  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 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:
+    - 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
+  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
+  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
@@ -94,12 +94,12 @@ Here's a working example of the resources you need:
 apiVersion: v1
 kind: ServiceAccount
 metadata:
-    name: homepage
-    namespace: default
-    labels:
-        app.kubernetes.io/name: homepage
+  name: homepage
+  namespace: default
+  labels:
+    app.kubernetes.io/name: homepage
 secrets:
-    - name: homepage
+  - name: homepage
 ```
 
 #### Secret
@@ -109,12 +109,12 @@ 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
+  name: homepage
+  namespace: default
+  labels:
+    app.kubernetes.io/name: homepage
+  annotations:
+    kubernetes.io/service-account.name: homepage
 ```
 
 #### ConfigMap
@@ -123,62 +123,62 @@ metadata:
 apiVersion: v1
 kind: ConfigMap
 metadata:
-    name: homepage
-    namespace: default
-    labels:
-        app.kubernetes.io/name: homepage
+  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
+  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 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: ""
+    - 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
@@ -187,57 +187,57 @@ data:
 apiVersion: rbac.authorization.k8s.io/v1
 kind: ClusterRole
 metadata:
-    name: homepage
-    labels:
-        app.kubernetes.io/name: homepage
+  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
+  - 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
+  name: homepage
+  labels:
+    app.kubernetes.io/name: homepage
 roleRef:
-    apiGroup: rbac.authorization.k8s.io
-    kind: ClusterRole
-    name: homepage
+  apiGroup: rbac.authorization.k8s.io
+  kind: ClusterRole
+  name: homepage
 subjects:
-    - kind: ServiceAccount
-      name: homepage
-      namespace: default
+  - kind: ServiceAccount
+    name: homepage
+    namespace: default
 ```
 
 #### Service
@@ -246,20 +246,20 @@ subjects:
 apiVersion: v1
 kind: Service
 metadata:
-    name: homepage
-    namespace: default
-    labels:
-        app.kubernetes.io/name: homepage
-    annotations:
+  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
+  type: ClusterIP
+  ports:
+    - port: 3000
+      targetPort: http
+      protocol: TCP
+      name: http
+  selector:
+    app.kubernetes.io/name: homepage
 ```
 
 #### Deployment
@@ -268,46 +268,68 @@ spec:
 apiVersion: apps/v1
 kind: Deployment
 metadata:
-    name: homepage
-    namespace: default
-    labels:
-        app.kubernetes.io/name: homepage
+  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/benphelps/homepage:latest"
-                  imagePullPolicy: Always
-                  ports:
-                      - name: http
-                        containerPort: 3000
-                        protocol: TCP
-                  volumeMounts:
-                      - name: homepage-config
-                        mountPath: /app/config
-                      - name: logs
-                        mountPath: /app/config/logs
-            volumes:
-                - name: homepage-config
-                  configMap:
-                      name: homepage
-                - name: logs
-                  emptyDir: {}
+  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
@@ -316,26 +338,56 @@ spec:
 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
+  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
+  rules:
+    - host: "homepage.my.network"
+      http:
+        paths:
+          - path: "/"
+            pathType: Prefix
+            backend:
+              service:
+                name: homepage
+                port:
+                  number: 3000
+```
+
+### Multiple Replicas
+
+If you plan to deploy homepage with a replica count greater than 1, you may
+want to consider enabling sticky sessions on the homepage route. This will
+prevent unnecessary re-renders on page loads and window / tab focusing. The
+procedure for enabling sticky sessions depends on your Ingress controller. Below
+is an example using Traefik as the Ingress controller.
+
+```
+apiVersion: traefik.io/v1alpha1
+kind: IngressRoute
+metadata:
+  name: homepage.example.com
+spec:
+  entryPoints:
+    - websecure
+  routes:
+    - kind: Rule
+      match: Host(`homepage.example.com`)
+      services:
+        - kind: Service
+          name: homepage
+          port: 3000
+          sticky:
+            cookie:
+              httpOnly: true
+              secure: true
+              sameSite: none
 ```

docs/installation/source.md

@@ -6,7 +6,7 @@ description: Install and run homepage from source
 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):

docs/installation/unraid.md

@@ -7,39 +7,39 @@ Homepage has an UNRAID community package that you may use to install homepage. T
 
 ## 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**.
+- 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.
+- 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**.
+- 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.
+- 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
+  !!! 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
-    ```
+  ```
+      - 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.
+- 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/layouts/custom.yml

@@ -0,0 +1,252 @@
+# Copyright (c) 2016-2024 Martin Donath <martin.donath@squidfunk.com>
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to
+# deal in the Software without restriction, including without limitation the
+# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+# sell copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+# IN THE SOFTWARE.
+
+# -----------------------------------------------------------------------------
+# Configuration
+# -----------------------------------------------------------------------------
+
+# Definitions
+definitions:
+  # Background image
+  - &background_image >-
+    {{ layout.background_image | x }}
+
+  # Background color (default: indigo)
+  - &background_color >-
+    {%- if layout.background_color -%}
+      {{ layout.background_color }}
+    {%- else -%}
+      {%- set palette = config.theme.palette or {} -%}
+      {%- if not palette is mapping -%}
+        {%- set list = palette | selectattr("primary") | list + palette -%}
+        {%- set palette = list | first -%}
+      {%- endif -%}
+      {%- set primary = palette.get("primary", "indigo") -%}
+      {%- set primary = primary.replace(" ", "-") -%}
+      {{ {
+        "red":         "#ef5552",
+        "pink":        "#e92063",
+        "purple":      "#ab47bd",
+        "deep-purple": "#7e56c2",
+        "indigo":      "#4051b5",
+        "blue":        "#2094f3",
+        "light-blue":  "#02a6f2",
+        "cyan":        "#00bdd6",
+        "teal":        "#009485",
+        "green":       "#4cae4f",
+        "light-green": "#8bc34b",
+        "lime":        "#cbdc38",
+        "yellow":      "#ffec3d",
+        "amber":       "#ffc105",
+        "orange":      "#ffa724",
+        "deep-orange": "#ff6e42",
+        "brown":       "#795649",
+        "grey":        "#757575",
+        "blue-grey":   "#546d78",
+        "black":       "#000000",
+        "white":       "#ffffff"
+      }[primary] or "#4051b5" }}
+    {%- endif -%}
+
+  # Text color (default: white)
+  - &color >-
+    {%- if layout.color -%}
+      {{ layout.color }}
+    {%- else -%}
+      {%- set palette = config.theme.palette or {} -%}
+      {%- if not palette is mapping -%}
+        {%- set list = palette | selectattr("primary") | list + palette -%}
+        {%- set palette = list | first -%}
+      {%- endif -%}
+      {%- set primary = palette.get("primary", "indigo") -%}
+      {%- set primary = primary.replace(" ", "-") -%}
+      {{ {
+        "red":         "#ffffff",
+        "pink":        "#ffffff",
+        "purple":      "#ffffff",
+        "deep-purple": "#ffffff",
+        "indigo":      "#ffffff",
+        "blue":        "#ffffff",
+        "light-blue":  "#ffffff",
+        "cyan":        "#ffffff",
+        "teal":        "#ffffff",
+        "green":       "#ffffff",
+        "light-green": "#ffffff",
+        "lime":        "#000000",
+        "yellow":      "#000000",
+        "amber":       "#000000",
+        "orange":      "#000000",
+        "deep-orange": "#ffffff",
+        "brown":       "#ffffff",
+        "grey":        "#ffffff",
+        "blue-grey":   "#ffffff",
+        "black":       "#ffffff",
+        "white":       "#000000"
+      }[primary] or "#ffffff" }}
+    {%- endif -%}
+
+  # Font family (default: Roboto)
+  - &font_family >-
+    {%- if layout.font_family -%}
+      {{ layout.font_family }}
+    {%- elif config.theme.font is mapping -%}
+      {{ config.theme.font.get("text", "Roboto") }}
+    {%- else -%}
+      Roboto
+    {%- endif -%}
+
+  # Font variant
+  - &font_variant >-
+    {%- if layout.font_variant -%}
+      {{ layout.font_variant }}
+    {%- endif -%}
+
+  # Site name
+  - &site_name >-
+    {{ config.site_name }}
+
+  # Page title
+  - &page_title >-
+    {%- if layout.title -%}
+      {{ layout.title }}
+    {%- else -%}
+      {{ page.meta.get("title", page.title) }}
+    {%- endif -%}
+
+  # Page title with site name
+  - &page_title_with_site_name >-
+    {%- if not page.is_homepage -%}
+      {{ page.meta.get("title", page.title) }} - {{ config.site_name }}
+    {%- else -%}
+      {{ page.meta.get("title", page.title) }}
+    {%- endif -%}
+
+  # Page description
+  - &page_description >-
+    {%- if layout.description -%}
+      {{ layout.description }}
+    {%- else -%}
+      {{ page.meta.get("description", config.site_description) | x }}
+    {%- endif -%}
+
+  # Page icon
+  - &page_icon >-
+    {{ page.meta.icon | x }}
+
+  # Logo
+  - &logo >-
+    {%- if layout.logo -%}
+      {{ layout.logo }}
+    {%- elif config.theme.logo -%}
+      {{ config.docs_dir }}/{{ config.theme.logo }}
+    {%- endif -%}
+
+  # Logo (icon)
+  - &logo_icon >-
+    {%- if not layout.logo and config.theme.icon -%}
+      {{ config.theme.icon.logo | x }}
+    {%- endif -%}
+
+# Meta tags
+tags:
+  # Open Graph
+  og:type: website
+  og:title: *page_title_with_site_name
+  og:description: *page_description
+  og:image: "{{ image.url }}"
+  og:image:type: "{{ image.type }}"
+  og:image:width: "{{ image.width }}"
+  og:image:height: "{{ image.height }}"
+  og:url: "{{ page.canonical_url }}"
+
+  # Twitter
+  twitter:card: summary_large_image
+  twitter:title: *page_title_with_site_name
+  twitter:description: *page_description
+  twitter:image: "{{ image.url }}"
+
+# -----------------------------------------------------------------------------
+# Specification
+# -----------------------------------------------------------------------------
+
+# Card size and layers
+size: { width: 1200, height: 630 }
+layers:
+  # Background
+  - background:
+      image: *background_image
+      color: *background_color
+
+  # Page icon
+  - size: { width: 630, height: 630 }
+    offset: { x: 800, y: 0 }
+    icon:
+      value: *page_icon
+      color: "#FFFFFF20"
+
+  # Logo
+  - size: { width: 64, height: 64 }
+    offset: { x: 64, y: 64 }
+    background:
+      image: *logo
+    icon:
+      value: *logo_icon
+      color: *color
+
+  # Site name
+  - size: { width: 768, height: 42 }
+    offset: { x: 160, y: 74 }
+    typography:
+      content: *site_name
+      color: *color
+      font:
+        family: *font_family
+        variant: *font_variant
+        style: Bold
+
+  # Page title
+  - size: { width: 864, height: 256 }
+    offset: { x: 62, y: 192 }
+    typography:
+      content: *page_title
+      align: start
+      color: *color
+      line:
+        amount: 3
+        height: 1.25
+      font:
+        family: *font_family
+        variant: *font_variant
+        style: Bold
+
+  # Page description
+  - size: { width: 864, height: 64 }
+    offset: { x: 64, y: 512 }
+    typography:
+      content: *page_description
+      align: start
+      color: *color
+      line:
+        amount: 2
+        height: 1.5
+      font:
+        family: *font_family
+        variant: *font_variant
+        style: Regular

docs/more/coverage.md

@@ -0,0 +1,57 @@
+---
+title: Community Coverage
+description: Homepage has been covered by quite a few YouTube channels, here are some of them.
+---
+
+Homepage has been covered by quite a few YouTube channels, here are some of them. If you have a video you'd like to add, please open a PR!
+
+## English
+
+<div class="grid" markdown>
+
+[![Youtube Video](https://img.youtube.com/vi/mC3tjysJ01E/maxresdefault.jpg)](https://www.youtube.com/watch?v=mC3tjysJ01E)
+
+[![Youtube Video](https://img.youtube.com/vi/o9SLve4wBPY/maxresdefault.jpg)](https://www.youtube.com/watch?v=o9SLve4wBPY)
+
+[![Youtube Video](https://img.youtube.com/vi/j9kbQucNwlc/maxresdefault.jpg)](https://www.youtube.com/watch?v=j9kbQucNwlc)
+
+[![Youtube Video](https://img.youtube.com/vi/3Ux7zfCCM1A/maxresdefault.jpg)](https://www.youtube.com/watch?v=3Ux7zfCCM1A)
+
+[![Youtube Video](https://img.youtube.com/vi/4AwUNy2eztA/maxresdefault.jpg)](https://www.youtube.com/watch?v=4AwUNy2eztA)
+
+[![Youtube Video](https://img.youtube.com/vi/7mUUCB3kP0E/maxresdefault.jpg)](https://www.youtube.com/watch?v=7mUUCB3kP0E)
+
+[![Youtube Video](https://img.youtube.com/vi/a5-4u0qFKaE/maxresdefault.jpg)](https://www.youtube.com/watch?v=a5-4u0qFKaE)
+
+[![Youtube Video](https://img.youtube.com/vi/tV7-06FU4gQ/maxresdefault.jpg)](https://www.youtube.com/watch?v=tV7-06FU4gQ)
+
+[![Youtube Video](https://img.youtube.com/vi/X2ycbT7rPu4/maxresdefault.jpg)](https://www.youtube.com/watch?v=X2ycbT7rPu4)
+
+[![Youtube Video](https://img.youtube.com/vi/1jEWUJqL-eo/maxresdefault.jpg)](https://www.youtube.com/watch?v=1jEWUJqL-eo)
+
+</div>
+
+<div class="grid" markdown>
+
+<div markdown>
+## French
+[![Youtube Video](https://img.youtube.com/vi/aGztk8you6o/maxresdefault.jpg)](https://www.youtube.com/watch?v=aGztk8you6o)
+[![Youtube Video](https://img.youtube.com/vi/pQfhWqZh7YE/maxresdefault.jpg)](https://www.youtube.com/watch?v=pQfhWqZh7YE)
+</div>
+
+<div markdown>
+## German
+[![Youtube Video](https://img.youtube.com/vi/DrDgg-WRA2g/maxresdefault.jpg)](https://www.youtube.com/watch?v=DrDgg-WRA2g)
+</div>
+
+<div markdown>
+## Chinese
+[![Youtube Video](https://img.youtube.com/vi/DAW15ckt4n4/mqdefault.jpg){: style="width: 100%"}](https://www.youtube.com/watch?v=DAW15ckt4n4)
+</div>
+
+<div markdown>
+## Russian
+[![Youtube Video](https://img.youtube.com/vi/dk3Cp5ck8mY/maxresdefault.jpg)](https://www.youtube.com/watch?v=dk3Cp5ck8mY)
+</div>
+
+</div>

docs/more/development.md

@@ -1,42 +0,0 @@
----
-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
-```
-
-## 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

@@ -3,6 +3,6 @@ title: Homepage Move
 description: Homepage Container Deprecation
 ---
 
-As of v0.7.1 homepage migrated from benphelps/homepage to an "orgnization" located at gethomepage/homepage. The reason for this is to setup the project for longevity and allow for community maintenance.
+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`.
+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

@@ -1,6 +1,7 @@
 ---
 title: More
 description: More homepage resources and guides.
+icon: material/information-slab-circle
 ---
 
 Here you'll find resources and guides for Homepage, troubleshooting tips, and more.

docs/more/sponsors.md

@@ -0,0 +1,58 @@
+---
+title: Sponsors
+description: Homepage is supported by these awesome people and companies.
+---
+
+If you would like to support the Homepage project, you can do so by becoming a sponsor. Your sponsorship helps to keep the project running and growing.
+
+<div class="grid" markdown>
+
+[:simple-github: GitHub Sponsors](https://github.com/sponsors/gethomepage){ .md-button }
+
+[:simple-opencollective: OpenCollective](https://opencollective.com/homepage){ .md-button }
+
+[:simple-patreon: Patreon](https://www.patreon.com/gethomepage){ .md-button .w-full }
+
+</div>
+
+<hr style="margin-top: 48px;" />
+
+These companies help the Homepage project by providing services, tools, and resources.
+
+<div class="grid" markdown>
+  <div style="margin-bottom: 16px;">
+    <a href="https://www.digitalocean.com/?refcode=df14bcb7c016&utm_campaign=Referral_Invite&utm_medium=Referral_Program&utm_source=badge"><img src="https://web-platforms.sfo2.cdn.digitaloceanspaces.com/WWW/Badge%202.svg" alt="DigitalOcean" style="max-width: 100%; height: 64px; display: block;" /></a>
+    <p>
+      DigitalOcean provides the GitHub Actions runner for the project.  Dramatically speeding up the CI/CD process.
+    </p>
+  </div>
+
+  <div style="margin-bottom: 16px;">
+    <a href="https://crowdin.com/project/homepage"><img src="https://support.crowdin.com/assets/logos/core-logo/png/crowdin-core-logo-cWhite.png" alt="Crowdin" style="max-width: 100%; height: 64px; display: block;" /></a>
+    <p>
+      Crowdin provides the translation platform for the project.  Making it easy to translate the project into multiple languages.
+    </p>
+  </div>
+
+  <div style="margin-bottom: 16px;">
+    <a href="https://www.jetbrains.com/"><img src="https://resources.jetbrains.com/storage/products/company/brand/logos/jetbrains.png" alt="JetBrains" style="max-width: 100%; height: 64px; display: block;" /></a>
+    <p>
+      JetBrains provides the project with free licenses for their awesome tools.
+    </p>
+  </div>
+
+  <div style="margin-bottom: 16px;">
+    <a href="https://www.buysellads.com/"><img src="https://www.buysellads.com/hubfs/raw_assets/public/BSA-2023/images/logo.svg" alt="BuySellAds" style="max-width: 100%; height: 64px; display: block; filter: invert();" /></a>
+    <p>
+      BuySellAds provides the project with the ability to monetize the website, with high quality ads from the CarbonAds network.  All earnings are sent directly to the projects OpenCollective.
+    </p>
+  </div>
+</div>
+
+<style>
+.md-typeset img,
+.md-typeset svg,
+.md-typeset video {
+  box-shadow: none;
+}
+</style>

docs/more/translations.md

@@ -3,12 +3,17 @@ title: Translations
 description: Contributing Translations
 ---
 
-Homepage is developed in English, most other supported languages are provided via Google Translate. When a i18n key is not found, the fallback language is English.
+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.
+If you'd like to lend a hand in translating Homepage into more languages, or to improve existing translations, the process is very simple:
 
-Everything can be done from a simple to use web interface here: https://hosted.weblate.org/projects/homepage/homepage/
+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!
 
-When creating a new language, it can take 5 to 10 minutes before you'll see translatable strings added, but the process _is_ automatic. Once the strings are added, you can then start translating them.
+## 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

@@ -1,64 +0,0 @@
----
-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/overrides/main.html

@@ -0,0 +1,52 @@
+{% extends "base.html" %}
+
+{% block header %}
+  <div id="blur-overlay" class="blur-overlay"></div>
+  {% include "partials/header.html" %}
+{% endblock %}
+
+{% block site_nav %}
+  <!-- Navigation -->
+  {% if nav %}
+    {% if page.meta and page.meta.hide %}
+      {% set hidden = "hidden" if "navigation" in page.meta.hide %}
+    {% endif %}
+    <div
+      class="md-sidebar md-sidebar--primary"
+      data-md-component="sidebar"
+      data-md-type="navigation"
+      {{ hidden }}
+    >
+      <div class="md-sidebar__scrollwrap">
+        <div class="md-sidebar__inner">
+          {% include "partials/nav.html" %}
+          {% if 'widgets/' not in page.url and 'more/' not in page.url %}
+            <script async type="text/javascript" src="//cdn.carbonads.com/carbon.js?serve=CWYIL2JU&placement=gethomepagedev&format=cover" id="_carbonads_js"></script>
+          {% endif %}
+        </div>
+      </div>
+    </div>
+  {% endif %}
+
+  <!-- Table of contents -->
+  {% if "toc.integrate" not in features %}
+    {% if page.meta and page.meta.hide %}
+      {% set hidden = "hidden" if "toc" in page.meta.hide %}
+    {% endif %}
+    <div
+      class="md-sidebar md-sidebar--secondary"
+      data-md-component="sidebar"
+      data-md-type="toc"
+      {{ hidden }}
+    >
+      <div class="md-sidebar__scrollwrap" style="height: 200px;">
+        <div class="md-sidebar__inner">
+          {% include "partials/toc.html" %}
+          {% if 'widgets/' in page.url or 'more/' in page.url %}
+            <script async type="text/javascript" src="//cdn.carbonads.com/carbon.js?serve=CWYIL2JU&placement=gethomepagedev&format=cover" id="_carbonads_js"></script>
+          {% endif %}
+        </div>
+      </div>
+    </div>
+  {% endif %}
+{% endblock %}

docs/stylesheets/extra.css

@@ -1,20 +1,283 @@
+[data-md-color-scheme="slate"] {
+  --md-hue: 220;
+  --md-default-bg-color: hsla(0, 0%, 14%, 0.6);
+  --md-code-bg-color: hsla(0, 0%, 0%, 0.2);
+}
+
+[data-md-color-scheme="default"] {
+  --md-hue: 220;
+  --md-default-fg-color--light: white;
+  --md-default-fg-color--lighter: hsla(0, 0%, 100%, 0.6);
+  --md-default-bg-color: hsla(0, 0%, 100%, 0.8);
+  --md-code-bg-color: hsla(0, 0%, 100%, 0.6);
+  --md-code-bg-color--lighter: hsla(0, 0%, 100%, 0.6);
+  --md-default-fg-color: white;
+}
+
+[data-md-color-scheme="default"] .md-search__inner {
+  --md-default-fg-color--light: gray;
+  --md-default-fg-color--lighter: black;
+  --md-default-bg-color: hsla(0, 0%, 100%, 0.9);
+}
+
+[data-md-color-scheme="default"] .md-search__inner .md-search__input {
+  color: var(--md-default-fg-color--light);
+}
+
 [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: "/";
-  }
+  position: absolute;
+  top: 0.3rem;
+  right: 0.3rem;
+  display: block;
+  padding: 0.1rem 0.4rem;
+  color: var(--md-default-fg-color--lighter);
+  font-weight: bold;
+  font-size: 0.8rem;
+  border: 0.05rem solid var(--md-default-fg-color--lighter);
+  border-radius: 0.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);
-    }
-}
+  [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);
+  }
+}
+
+#carbonads {
+  margin-top: 10px;
+}
+
+#carbon-responsive {
+  --carbon-padding: 1em;
+  --carbon-max-char: 20ch;
+  --carbon-bg-primary: var(--md-default-bg-color) !important;
+  --carbon-bg-secondary: var(--md-default-fg-color--lightest) !important;
+  --carbon-text-color: var(--md-typeset-color) !important;
+}
+
+.md-typeset__table {
+  width: 100%;
+}
+
+.md-typeset table:not([class]) {
+  display: table;
+}
+
+/* less than 1440px wide */
+@media (max-width: 1440px) {
+  .md-footer-meta__inner {
+    justify-content: center;
+  }
+}
+
+/* less than 740px wide */
+@media (max-width: 740px) {
+  .md-footer-meta__inner {
+    justify-content: left;
+    flex-direction: column;
+  }
+  .md-social {
+    padding-top: 0;
+  }
+}
+
+.md-header__button.md-logo {
+  padding: 0;
+  margin: 0;
+}
+
+.md-header__button.md-logo img,
+.md-header__button.md-logo svg {
+  height: 2rem;
+}
+
+.md-header__topic .md-ellipsis {
+  display: none;
+}
+
+body {
+  background-color: transparent !important;
+  background-image: url("https://raw.githubusercontent.com/gethomepage/homepage/main/docs/assets/blossom_valley.jpg");
+  background-size: cover;
+  background-attachment: fixed;
+  background-position: center;
+  color: rgba(255, 255, 255, 0.8);
+}
+
+.md-typeset h1 {
+  color: #fff;
+}
+
+body[data-md-color-scheme="default"] {
+  color: rgba(255, 255, 255, 1);
+}
+
+.blur-overlay {
+  z-index: -1;
+  position: fixed;
+  width: 100%;
+  height: 100%;
+  background: hsl(0deg 0% 0% / 10%);
+  backdrop-filter: blur(128px);
+  -webkit-backdrop-filter: blur(128px);
+}
+
+[data-md-color-scheme="default"] .blur-overlay {
+  background: hsla(0, 0%, 0%, 0);
+}
+
+.md-nav--lifted > .md-nav__list > .md-nav__item--active > .md-nav__link,
+.md-nav--secondary .md-nav__title {
+  background: none;
+  box-shadow: none;
+}
+
+[data-md-color-scheme="slate"] .md-main,
+[data-md-color-scheme="slate"] .md-tabs,
+[data-md-color-scheme="slate"] .md-footer {
+  background-color: hsla(0, 0%, 0%, 0.3);
+}
+
+[data-md-color-scheme="default"] .md-main,
+[data-md-color-scheme="default"] .md-tabs,
+[data-md-color-scheme="default"] .md-footer {
+  background-color: hsla(0, 0%, 100%, 0.1);
+}
+
+[data-md-color-scheme="slate"] .md-header {
+  background-color: hsla(0, 0%, 0%, 0.3);
+  backdrop-filter: blur(16px);
+  -webkit-backdrop-filter: blur(16px);
+}
+
+[data-md-color-scheme="default"] .md-header {
+  background-color: hsla(0, 0%, 100%, 0.1);
+  backdrop-filter: blur(16px);
+  -webkit-backdrop-filter: blur(16px);
+}
+
+.md-header:has(.md-search-result__item),
+.md-header:has(.md-search__input.focus-visible) {
+  backdrop-filter: none !important;
+  -webkit-backdrop-filter: none !important;
+}
+
+.md-footer-meta {
+  background-color: transparent;
+}
+
+[data-md-color-scheme="slate"][data-md-color-primary="black"],
+[data-md-color-scheme="default"][data-md-color-primary="black"] {
+  --md-typeset-a-color: #ffffff;
+}
+
+.md-content__inner a {
+  text-decoration: underline;
+  font-weight: bolder;
+}
+
+[data-md-color-scheme="default"] .highlight .p,
+[data-md-color-scheme="default"] .highlight .o,
+[data-md-color-scheme="default"] .highlight .ow,
+[data-md-color-scheme="default"] .highlight .c,
+[data-md-color-scheme="default"] .highlight .c1,
+[data-md-color-scheme="default"] .highlight .ch,
+[data-md-color-scheme="default"] .highlight .cm,
+[data-md-color-scheme="default"] .highlight .cs,
+[data-md-color-scheme="default"] .highlight .sd {
+  color: #36464eaa;
+}
+
+[data-md-color-scheme="default"] .md-annotation__index:after {
+  background-color: #36464ecc;
+}
+
+/* I know this is a farce, but I want it to look nice. */
+.css-9if7bc {
+  background-color: hsla(0, 0%, 0%, 0.3);
+  backdrop-filter: blur(16px);
+  -webkit-backdrop-filter: blur(16px);
+}
+
+@media screen and (max-width: 76.234375em) {
+  .md-nav--primary,
+  .md-nav--primary .md-nav {
+    background-color: hsla(0, 0%, 0%, 0.8);
+  }
+}
+
+@media screen and (max-width: 76.234375em) {
+  .md-nav--primary .md-nav__title ~ .md-nav__list {
+    background-color: hsla(0, 0%, 0%, 0.8);
+    backdrop-filter: blur(16px);
+    -webkit-backdrop-filter: blur(16px);
+  }
+}
+
+@media screen and (max-width: 76.234375em) {
+  .md-nav--primary .md-nav__title {
+    background-color: hsla(0, 0%, 0%, 0.8);
+    backdrop-filter: blur(16px);
+  }
+}
+
+.md-search__scrollwrap {
+  background-color: hsla(0, 0%, 0%, 0.8);
+  backdrop-filter: blur(16px);
+  -webkit-backdrop-filter: blur(16px);
+}
+
+.md-search-result .md-typeset h1 {
+  color: #fff;
+}
+
+[data-md-color-scheme="default"] .highlight span.filename,
+[data-md-color-scheme="default"] .linenodiv a {
+  color: #36464e;
+  font-weight: light;
+}
+
+.linenodiv a {
+  text-decoration: none;
+}
+
+.md-typeset .admonition,
+.md-typeset details {
+  background-color: transparent;
+}
+
+.md-typeset img,
+.md-typeset svg,
+.md-typeset video {
+  box-shadow: 0 0 1rem 0.25rem hsla(0, 0%, 0%, 0.1);
+}
+
+.highlight {
+  box-shadow: 0 0 1rem 0.25rem hsla(0, 0%, 0%, 0.1);
+}
+
+.md-typeset .admonition.tip,
+.md-typeset details.tip {
+  box-shadow: 0 0 1rem 0.25rem hsl(171.83deg 100% 37.45% / 20%);
+}
+
+.md-typeset .admonition.note,
+.md-typeset details.note {
+  box-shadow: 0 0 1rem 0.25rem hsl(214.29deg 100% 37.45% / 20%);
+}
+
+.md-typeset .admonition.warning,
+.md-typeset details.warning {
+  box-shadow: 0 0 1rem 0.25rem hsl(40.91deg 100% 37.45% / 20%);
+}
+
+.md-typeset .admonition.danger,
+.md-typeset details.danger {
+  box-shadow: 0 0 1rem 0.25rem hsl(0deg 100% 37.45% / 20%);
+}
+
+.md-tabs__link {
+  transform: translateZ(0);
+}

docs/troubleshooting/index.md

@@ -0,0 +1,66 @@
+---
+title: Troubleshooting
+description: Basic Troubleshooting
+icon: material/message-question
+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/widgets/authoring/api.md

@@ -0,0 +1,50 @@
+---
+title: API Guide
+description: Get comfortable with making API calls from inside your widget.
+---
+
+Homepage provides the `useWidgetAPI` hook to help you fetch data from an API. This hook insures that the data is fetched using a proxy, and is critical for security.
+
+Here is an example of how the `useWidgetAPI` hook looks:
+
+```js title="Fetch data from the stats endpoint"
+import useWidgetAPI from "utils/proxy/use-widget-api";
+
+export default function Component({ service }) {
+  const { data, error } = useWidgetAPI(widget, "stats");
+}
+```
+
+## `useWidgetAPI`
+
+`useWidgetAPI` takes three possible arguments:
+
+- `widget`: The widget metadata object.
+- `endpoint`: The name of the endpoint to fetch data from.
+- `params`: An optional object containing query parameters to pass to the API.
+
+### `widget`
+
+The `widget` argument is the metadata object for the widget. It contains information about the API endpoint, proxy handler, and mappings. This object is used by the `useWidgetAPI` hook to fetch data from the API. This is generally passed in as a prop from the parent component.
+
+### `endpoint`
+
+The `endpoint` argument is the name of the endpoint to fetch data from. This is [defined in the widget metadata object](metadata.md#endpoint). The `useWidgetAPI` hook uses this argument to determine which endpoint to fetch data from.
+
+If no endpoint is provided, the `useWidgetAPI` hook will call the API endpoint defined in the widget metadata object directly.
+
+### `params`
+
+The `params` argument is an optional object containing query parameters to pass to the API. This is useful for filtering data or passing additional information to the API. This object is passed directly to the API endpoint as query parameters.
+
+Here is an example of how to use the `params` argument:
+
+```js title="Fetch data from the stats endpoint with query parameters"
+import useWidgetAPI from "utils/proxy/use-widget-api";
+
+export default function Component({ service }) {
+  const { data, error } = useWidgetAPI(widget, "stats", { start: "2021-01-01", end: "2021-12-31" });
+}
+```
+
+The `params` must be [whitelisted in the widget metadata object](metadata.md#params). This is done to prevent arbitrary query parameters from being passed to the API.

docs/widgets/authoring/component.md

@@ -0,0 +1,102 @@
+---
+title: Component Guide
+description: Learn more about the widget component in Homepage, and how to build your widget UI.
+---
+
+Homepage widgets are built using React components. These components are responsible for fetching data from the API and rendering the widget UI. Homepage provides a set of hooks and utilities to help you build your widget component.
+
+## A Basic Widget Component
+
+Here is an example of a basic widget component:
+
+```js
+import { useTranslation } from "next-i18next";
+
+import Container from "components/services/widget/container";
+import Block from "components/services/widget/block";
+import useWidgetAPI from "utils/proxy/use-widget-api";
+
+export default function Component({ service }) {
+  const { t } = useTranslation();
+  const { widget } = service;
+  const { data, error } = useWidgetAPI(widget, "info");
+
+  if (error) {
+    return <Container service={service} error={error} />;
+  }
+
+  if (!data) {
+    return (
+      <Container service={service}>
+        <Block label="yourwidget.key1" />
+        <Block label="yourwidget.key2" />
+        <Block label="yourwidget.key3" />
+      </Container>
+    );
+  }
+
+  return (
+    <Container service={service}>
+      <Block label="yourwidget.key1" value={t("common.number", { value: data.key1 })} />
+      <Block label="yourwidget.key2" value={t("common.number", { value: data.key2 })} />
+      <Block label="yourwidget.key3" value={t("common.number", { value: data.key3 })} />
+    </Container>
+  );
+}
+```
+
+### Breakdown
+
+We'll cover two sections of the widget component: hooks and components.
+
+#### Hooks
+
+**`useTranslation`**
+
+This hook is used to translate text and numerical content in widgets. Homepage provides a set of helpers to help you localize your widgets. You can learn more about translations in the [Translations Guide](translations.md).
+
+**`useWidgetAPI`**
+
+This hook is used to fetch data from the API. We cover this hook in more detail in the [API Guide](api.md).
+
+#### Components
+
+Homepage provides a set of components to help you build your widget UI. These components are designed to provide a consistent layout, and all widgets are expected to use these components.
+
+![Component Sections](../../assets/sections.webp)
+
+**`<Container>`**
+
+This component is a wrapper for the widget. It provides a consistent layout for all widgets.
+
+```js
+<Container service={service}></Container>
+```
+
+`service` is a prop that is passed to the widget component. It contains information about the service that the widget is displaying.
+
+If there is an error fetching data from the API, the `error` prop can be passed to the `Container` component.
+
+```js
+<Container service={service} error={error}></Container>
+```
+
+**`<Block>`**
+
+This component is used to display a key-value pair. It takes a label and value as props.
+
+```js
+<Block label="yourwidget.key1" value={t("common.number", { value: data.key1 })} />
+```
+
+The `label` prop is used to look up the translation key in the translation files. The `value` prop is used to display the value of the block. To learn more about translations, please refer to the [Translations Guide](translations.md).
+
+If there is no data available, the `Block` component can be used to display a placeholder layout.
+
+```js
+<Container service={service}>
+  <Block label="yourwidget.key1" />
+  <Block label="yourwidget.key2" />
+  <Block label="yourwidget.key3" />
+</Container>
+```

docs/widgets/authoring/getting-started.md

@@ -0,0 +1,65 @@
+---
+title: Getting Started
+description: Get started developing for Homepage.
+---
+
+We'll cover getting homepage up and running on your local machine for development, as well as some guidelines for developing new features and widgets.
+
+## Development
+
+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.
+
+Once installed, hooks will run when you commit. If the formatting isn't quite right, the commit will be rejected and you'll need to look at the output and fix the issue. Most hooks will automatically format failing files, so all you need to do is `git add` those files again and retry your commit.
+
+See the [pre-commit documentation](https://pre-commit.com/#install) to get started.
+
+## Preferring self-hosted open-source software
+
+In general, homepage is meant to be a dashboard for 'self-hosted' services and we believe it is a small way we can help showcase this kind of software. While exceptions are made, mostly when there is no viable
+self-hosted / open-source alternative, we ask that any widgets, etc. are developed primarily for a self-hosted tool.
+
+## New Feature Guidelines
+
+- New features should be linked to an existing feature request with at least 10 'up-votes'. The purpose of this requirement is to avoid the addition (and maintenance) of features that might only benefit a small number of users.
+- If you have ideas for a larger feature, please open a discussion first.
+- Please note that though it is a requirement, a discussion with 10 'up-votes' in no way guarantees that a PR will be merged.
+
+## 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 10 'up-votes'. The purpose of this requirement is to avoid the addition (and maintenance) of service widgets that might only benefit a small number of users.
+- Note that we reserve the right to decline widgets for projects that are very young (eg < ~1y) or those with a small reach (eg low GitHub stars). Again, this is in an effort to keep overall widget maintenance under control.
+- Widgets should be only one row of blocks
+- Widgets should be no more than 4 blocks wide and generally conform to the styling / design choices of other widgets
+- Minimize the number of API calls
+- Avoid the use of custom proxy unless absolutely necessary
+- Widgets should be 'read-only', as in they should not make write changes using the relevant tool's API. Homepage widgets are designed to surface information, not to be a (usually worse) replacement for the tool itself.

docs/widgets/authoring/index.md

@@ -0,0 +1,33 @@
+---
+title: Guides & Tutorials
+description: Learn how to create and customize widgets in Homepage. Explore translations, widget components, widget metadata, proxy handlers, and making API calls.
+icon: fontawesome/solid/graduation-cap
+---
+
+Widgets are a core component of Homepage. They are used to display information about your system, services, and environment.
+
+## Overview
+
+If you are new to Homepage widgets, and are looking to create a new widget, please follow along with the guide here: [Widget Tutorial](tutorial.md).
+
+### Translations
+
+All text and numerical content in widgets should be translated and localized. English is the default language, and other languages can be added via [Crowdin](https://crowdin.com/project/gethomepage).
+
+To learn more about translations, please refer to the guide here: [Translations Guide](translations.md).
+
+### Widget Component
+
+The widget component is the core of the widget. It is responsible for [fetching data from the API](api.md) and rendering the widget UI. Homepage provides a set of hooks and utilities to help you build your widget component.
+
+To learn more about widget components, please refer to the guide here: [Component Guide](component.md).
+
+### Widget Metadata
+
+Widget metadata defines the configuration of the widget. It defines the API endpoint to fetch data from, the proxy handler to use, and any data mappings.
+
+To learn more about widget metadata, endpoint and data mapping, please refer to the guide here: [Metadata Guide](metadata.md).
+
+To learn more about proxy handlers, please refer to the guide here: [Proxies Guide](proxies.md).
+
+To learn more about making API calls from inside your widget, please refer to the guide here: [API Guide](api.md).

docs/widgets/authoring/metadata.md

@@ -0,0 +1,310 @@
+---
+title: Metadata Guide
+description: Explore all the metadata properties that can be used to configure a widget in Homepage.
+---
+
+Here, we will go over how to create and configure Homepage widget metadata. Metadata is a JS object that contains information about the widget, such as the API endpoint, proxy handler, and mappings. This metadata is used by Homepage to fetch data from the API and pass it to the widget.
+
+## Widgets Configuration
+
+Here are some examples of how to configure a widget's metadata object.
+
+=== "Basic Example"
+
+    ```js
+    import genericProxyHandler from "utils/proxy/handlers/generic";
+
+    const widgetExample = {
+      api: "{url}/api/{endpoint}",
+      proxyHandler: genericProxyHandler,
+
+      mappings: {
+        stats: { endpoint: "stats" }
+      },
+    };
+    ```
+
+=== "Advanced Example"
+
+    ```js
+    import credentialedProxyHandler from "utils/proxy/handlers/credentialed";
+    import { asJson, jsonArrayFilter } from "utils/proxy/api-helpers";
+
+    const widgetExample = {
+      api: "{url}/api/{endpoint}",
+      proxyHandler: credentialedProxyHandler,
+
+      mappings: {
+        stats: {
+          endpoint: "stats",
+          validate: ["total", "average"],
+          params: ["start", "end"],
+        },
+        notices: {
+          endpoint: "notices",
+          map: (data) => {
+            total: asJson(data).length;
+          },
+        },
+        warnings: {
+          endpoint: "notices",
+          map: (data) => {
+            total: jsonArrayFilter(data, (alert) => alert.type === "warning").length;
+          },
+        },
+      },
+    };
+    ```
+
+A widget's metadata is quite powerful and can be configured in many different ways.
+
+## Configuration Properties
+
+### `api`
+
+The `api` property is a string that represents the URL of the API endpoint that the widget will use to fetch data. The URL can contain placeholders that will be replaced with actual values at runtime. For example, the `{url}` placeholder will be replaced with the URL of the configured widget, and the `{endpoint}` placeholder will be replaced with the value of the `endpoint` property in the `mappings` object.
+
+```js
+const widgetExample = {
+  api: "{url}/api/{endpoint}",
+};
+```
+
+### `proxyHandler`
+
+The `proxyHandler` property is a function that will be used to make the API request. Homepage includes some built-in proxy handlers that can be used out of the box:
+
+Here is an example of the generic proxy handler that makes unauthenticated requests to the specified API endpoint.
+
+=== "widget.js"
+
+    ```js
+    const widgetExample = {
+      api: "{url}/api/{endpoint}",
+      proxyHandler: genericProxyHandler,
+    };
+    ```
+
+=== "services.yaml"
+
+    ```yaml
+    - Services:
+        - Your Widget:
+            icon: yourwidget.svg
+            href: https://example.com/
+            widget:
+              type: yourwidget
+              url: http://127.0.0.1:1337
+    ```
+
+If you are looking to learn more about proxy handlers, please refer to the guide here: [Proxies Guide](proxies.md).
+
+### `mappings`
+
+The `mappings` property is an object that contains information about the API endpoint, such as the endpoint name, validation rules, and parameter names. The `mappings` object can contain multiple endpoints, each with its own configuration.
+
+!!! note "Security Note"
+
+    The `mappings` or `allowedEndpoints` property is required for the widget to fetch data from more than a static URL. Homepage uses a whitelist approach to ensure that widgets only access allowed endpoints.
+
+```js
+import { asJson } from "utils/proxy/api-helpers";
+
+const widgetExample = {
+  api: "{url}/api/{endpoint}",
+  mappings: {
+    // `/api/stats?start=...&end=...`
+    stats: {
+      endpoint: "stats",
+      validate: ["total", "average"],
+      params: ["start", "end"],
+    },
+    // `/api/notices`
+    notices: {
+      endpoint: "notices",
+      map: (data) => {
+        total: asJson(data).length;
+      },
+    },
+  },
+};
+```
+
+#### `endpoint`
+
+The `endpoint` property is a string that represents the name of the API endpoint that the widget will use to fetch data. This value will be used to replace the `{endpoint}` placeholder in the `api` property.
+
+```js
+const widgetExample = {
+  api: "{url}/api/{endpoint}",
+  mappings: {
+    // `/api/stats`
+    stats: {
+      endpoint: "stats",
+    },
+  },
+};
+```
+
+#### `validate`
+
+The `validate` property is an array of strings that represent the keys that should be validated in the API response. If the response does not contain all of the specified keys, the widget will not render.
+
+```js
+const widgetExample = {
+  api: "{url}/api/{endpoint}",
+  mappings: {
+    // `/api/stats`
+    stats: {
+      endpoint: "stats",
+      validate: ["total", "average"],
+    },
+  },
+};
+```
+
+This configuration will ensure that the API response contains the `total` and `average` keys before the widget is rendered.
+
+#### `params`
+
+The `params` property is an array of strings that represent the keys that should be passed as parameters to the API endpoint. These keys will be replaced with the actual values at runtime.
+
+=== "widget.js"
+
+    ```js
+    const widgetExample = {
+      api: "{url}/api/{endpoint}",
+      mappings: {
+        // `/api/stats?start=...&end=...`
+        stats: {
+          endpoint: "stats",
+          params: ["start", "end"],
+        },
+      },
+    };
+    ```
+
+=== "component.jsx"
+
+      ```js
+      const { data: statsData, error: statsError } = useWidgetAPI(widget, "stats", {
+        start: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000),
+        end: new Date(),
+      });
+      ```
+
+This configuration will pass the `start` and `end` keys as parameters to the API endpoint. The values are passed as an object to the `useWidgetAPI` hook.
+
+#### `map`
+
+The `map` property is a function that will be used to transform the API response before it is passed to the widget. This function is passed the raw API response and should return the transformed data.
+
+```js
+import { asJson } from "utils/proxy/api-helpers";
+
+const widgetExample = {
+  api: "{url}/api/{endpoint}",
+  mappings: {
+    // `/api/notices`
+    notices: {
+      endpoint: "notices",
+      map: (data) => {
+        total: asJson(data).length;
+      },
+    },
+    // `/api/notices`
+    warnings: {
+      endpoint: "notices",
+      map: (data) => {
+        total: asJson(data).filter((alert) => alert.type === "warning").length;
+      },
+    },
+  },
+};
+```
+
+#### `method`
+
+The `method` property is a string that represents the HTTP method that should be used to make the API request. The default value is `GET`.
+
+```js
+const widgetExample = {
+  api: "{url}/api/{endpoint}",
+  mappings: {
+    // `/api/stats`
+    stats: {
+      endpoint: "stats",
+      method: "POST",
+    },
+  },
+};
+```
+
+#### `headers`
+
+The `headers` property is an object that contains additional headers that should be included in the API request. If your endpoint requires specific headers, you can include them here.
+
+```js
+const widgetExample = {
+  api: "{url}/api/{endpoint}",
+  mappings: {
+    // `/api/stats`
+    stats: {
+      endpoint: "stats",
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+      },
+    },
+  },
+};
+```
+
+#### `body`
+
+The `body` property is an object that contains the data that should be sent in the request body. This property is only used when the `method` property is set to `POST` or `PUT`.
+
+```js
+const widgetExample = {
+  api: "{url}/api/{endpoint}",
+  mappings: {
+    // `/api/graphql`
+    stats: {
+      endpoint: "graphql",
+      method: "POST",
+      body: {
+        query: `
+          query {
+            stats {
+              total
+              average
+            }
+          }
+        `,
+      },
+      headers: {
+        "Content-Type": "application/json",
+      },
+    },
+  },
+};
+```
+
+### `allowedEndpoints`
+
+The `allowedEndpoints` property is a RegExp that represents the allowed endpoints that the widget can use. If the widget tries to access an endpoint that is not allowed, the request will be blocked.
+
+`allowedEndpoints` can be used when endpoint validation is simple and can be done using a regular expression, and more control is not required.
+
+!!! note "Security Note"
+
+    The `mappings` or `allowedEndpoints` property is required for the widget to fetch data from more than a static URL. Homepage uses a whitelist approach to ensure that widgets only access allowed endpoints.
+
+```js
+const widgetExample = {
+  api: "{url}/api/{endpoint}",
+  allowedEndpoints: /^stats|notices$/,
+};
+```
+
+This configuration will only allow the widget to access the `stats` and `notices` endpoints.

docs/widgets/authoring/proxies.md

@@ -0,0 +1,203 @@
+---
+title: Proxies Guide
+description: Learn about proxy handlers in Homepage, and how to securely fetch data from an API.
+---
+
+Homepage includes a set of built-in proxy handlers that can be used to fetch data from an API. We will go over how to use these proxy handlers and briefly cover how to create your own.
+
+## Available Proxy Handlers
+
+Homepage comes with a few built-in proxy handlers that can be used to fetch data from an API. These handlers are located in the `utils/proxy/handlers` directory.
+
+### `genericProxyHandler`
+
+A proxy handler that makes generally unauthenticated requests to the specified API endpoint.
+
+```js
+import genericProxyHandler from "utils/proxy/handlers/generic";
+
+const widgetExample = {
+  api: "{url}/api/{endpoint}",
+  proxyHandler: genericProxyHandler,
+};
+```
+
+You can also pass API keys from the widget configuration to the proxy handler, for authenticated requests.
+
+=== "widget.js"
+
+    ```js
+    import genericProxyHandler from "utils/proxy/handlers/generic";
+
+    const widgetExample = {
+      api: "{url}/api/{endpoint}?key={key}",
+      proxyHandler: genericProxyHandler,
+    };
+    ```
+
+=== "services.yaml"
+
+    ```yaml
+    # Widget Configuration
+    - Your Widget:
+        icon: yourwidget.svg
+        href: https://example.com/
+        widget:
+          type: yourwidget
+          url: http://example.com
+          key: your-api-key
+    ```
+
+### `credentialedProxyHandler`
+
+A proxy handler that makes authenticated by setting request headers. Credentials are pulled from the widgets configuration.
+
+By default the key is passed as an `X-API-Key` header. If you need to pass the key as something else, either add a case to the credentialedProxyHandler or create a new proxy handler.
+
+=== "widget.js"
+
+    ```js
+    import credentialedProxyHandler from "utils/proxy/handlers/credentialed";
+
+    const widgetExample = {
+      api: "{url}/api/{endpoint}?key={key}",
+      proxyHandler: credentialedProxyHandler,
+    };
+    ```
+
+=== "services.yaml"
+
+    ```yaml
+    - Your Widget:
+        icon: yourwidget.svg
+        href: https://example.com/
+        widget:
+          type: yourwidget
+          url: http://127.0.0.1:1337
+          key: your-api-key
+    ```
+
+### `jsonrpcProxyHandler`
+
+A proxy handler that makes authenticated JSON-RPC requests to the specified API endpoint, either using username + password or an API token.
+The endpoint is the method to call and queryParams are used as the parameters.
+
+=== "component.js"
+
+    ```js
+    import Container from "components/services/widget/container";
+    import useWidgetAPI from "utils/proxy/use-widget-api";
+
+    export default function Component({ service }) {
+      const { widget } = service;
+
+      const { data, error } = useWidgetAPI(widget, 'trigger', { "triggerids": "14062", "output": "extend", "selectFunctions": "extend" });
+    }
+    ```
+
+=== "widget.js"
+
+    ```js
+    import jsonrpcProxyHandler from "utils/proxy/handlers/jsonrpc";
+
+    const widgetExample = {
+      api: "{url}/api/jsonrpc",
+      proxyHandler: jsonrpcProxyHandler,
+
+      mappings: {
+        total: { endpoint: "total" },
+        average: { endpoint: "average" },
+        trigger: { endpoint: "trigger.get" },
+      },
+    };
+    ```
+
+=== "services.yaml"
+
+    ```yaml
+    - Your Widget:
+        icon: yourwidget.svg
+        href: https://example.com/
+        widget:
+          type: yourwidget
+          url: http://127.0.0.1:1337
+          username: your-username
+          password: your-password
+    ```
+
+    ```yaml
+    - Your Widget:
+        icon: yourwidget.svg
+        href: https://example.com/
+        widget:
+          type: yourwidget
+          url: http://127.0.0.1:1337
+          key: your-api-token
+    ```
+
+### `synologyProxyHandler`
+
+A proxy handler that makes authenticated requests to the specified Synology API endpoint. This is used exclusively for Synology DSM services.
+
+=== "widget.js"
+
+    ```js
+    import synologyProxyHandler from "utils/proxy/handlers/synology";
+
+    const widgetExample = {
+      api: "{url}/webapi/{cgiPath}?api={apiName}&version={maxVersion}&method={apiMethod}",
+      proxyHandler: synologyProxyHandler,
+
+      mappings: {
+        system_storage: {
+          apiName: "SYNO.Core.System",
+          apiMethod: 'info&type="storage"',
+          endpoint: "system_storage",
+        }
+      },
+    };
+    ```
+
+=== "services.yaml"
+
+    ```yaml
+    - Your Widget:
+        icon: yourwidget.svg
+        href: https://example.com/
+        widget:
+          type: yourwidget
+          url: http://127.0.0.1:1337
+          username: your-username
+          password: your-password
+    ```
+
+## Creating a Custom Proxy Handler
+
+You can create your own proxy handler to fetch data from an API. A proxy handler is a function that takes a configuration object and returns a function that makes the API request.
+
+The proxy handler function takes three arguments:
+
+- `req`: The request object.
+- `res`: The response object.
+- `map`: A function that maps the API response to the widget data.
+
+The proxy handler function should return a promise that resolves to the API response.
+
+Here is an example of a simple proxy handler that fetches data from an API and passes it to the widget:
+
+```js
+import createLogger from "utils/logger";
+import { httpProxy } from "utils/proxy/http";
+
+const logger = createLogger("customProxyHandler");
+
+export default async function customProxyHandler(req, res, map) {
+  const { url } = req.query;
+
+  const [status, contentType, data] = await httpProxy(url);
+
+  return res.status(status).send(data);
+}
+```
+
+Proxy handlers are a complex topic and require a good understanding of JavaScript and the Homepage codebase. If you are new to Homepage, we recommend using the built-in proxy handlers.

docs/widgets/authoring/translations.md

@@ -0,0 +1,88 @@
+---
+title: Translations Guide
+description: Tips and tricks for translating and localizing Homepage widgets.
+---
+
+All text and numerical content in widgets should be translated and localized. English is the default language, and other languages can be added via [Crowdin](https://crowdin.com/project/gethomepage).
+
+## Translations
+
+Homepage uses the [next-i18next](https://github.com/i18next/next-i18next) library to handle translations. This library provides a set of hooks and utilities to help you localize your widgets, and Homepage has extended this library to support additional features.
+
+=== "component.jsx"
+
+    ```js
+    import { useTranslation } from "next-i18next";
+
+    import Container from "components/services/widget/container";
+    import Block from "components/services/widget/block";
+
+    export default function Component() {
+      const { t } = useTranslation();
+
+      return (
+        <Container service={service}>
+          <Block label="yourwidget.key1" />
+          <Block label="yourwidget.key2" />
+          <Block label="yourwidget.key3" />
+        </Container>
+      );
+    }
+    ```
+
+## Set up translation strings
+
+Homepage uses translated and localized strings for **all text and numerical content** in widgets. English is the default language, and other languages can be added via [Crowdin](https://crowdin.com/project/gethomepage). To add the English translations for your widget, follow these steps:
+
+Open the `public/locales/en/common.js` file.
+
+Add a new object for your widget to the bottom of the list, like this:
+
+```json
+"yourwidget": {
+  "key1": "Value 1",
+  "key2": "Value 2",
+  "key3": "Value 3"
+}
+```
+
+!!! note
+
+    Even if you natively speak another language, you should only add English translations. You can then add translations in your native language via [Crowdin](https://crowdin.com/project/gethomepage), once your widget is merged.
+
+## Common Translations
+
+Homepage provides a set of common translations that you can use in your widgets. These translations are used to format numerical content, dates, and other common elements.
+
+### Numbers
+
+| Key                   | Translation     | Description                      |
+| --------------------- | --------------- | -------------------------------- |
+| `common.bytes`        | `1,000 B`       | Format a number in bytes.        |
+| `common.bits`         | `1,000 bit`     | Format a number in bits.         |
+| `common.bbytes`       | `1 KiB`         | Format a number in binary bytes. |
+| `common.bbits`        | `1 Kibit`       | Format a number in binary bits.  |
+| `common.byterate`     | `1,000 B/s`     | Format a byte rate.              |
+| `common.bibyterate`   | `1 KiB/s`       | Format a binary byte rate.       |
+| `common.bitrate`      | `1,000 bit/s`   | Format a bit rate.               |
+| `common.bibitrate`    | `1 Kibit/s`     | Format a binary bit rate.        |
+| `common.percent`      | `50%`           | Format a percentage.             |
+| `common.number`       | `1,000`         | Format a number.                 |
+| `common.ms`           | `1,000 ms`      | Format a number in milliseconds. |
+| `common.date`         | `2024-01-01`    | Format a date.                   |
+| `common.relativeDate` | `1 day ago`     | Format a relative date.          |
+| `common.uptime`       | `1 day, 1 hour` | Format an uptime.                |
+
+### Text
+
+| Key                | Translation | Description        |
+| ------------------ | ----------- | ------------------ |
+| `resources.cpu`    | `CPU`       | CPU usage.         |
+| `resources.mem`    | `MEM`       | Memory usage.      |
+| `resources.total`  | `Total`     | Total resource.    |
+| `resources.free`   | `Free`      | Free resource.     |
+| `resources.used`   | `Used`      | Used resource.     |
+| `resources.load`   | `Load`      | Load value.        |
+| `resources.temp`   | `TEMP`      | Temperature value. |
+| `resources.max`    | `Max`       | Maximum value.     |
+| `resources.uptime` | `UP`        | Uptime.            |

docs/widgets/authoring/tutorial.md

@@ -0,0 +1,273 @@
+---
+title: Widget Tutorial
+description: Follow along with this guide to learn how to create a custom widget for Homepage. We'll cover the basic structure of a widget, how to use translations, and how to fetch data from an API.
+---
+
+In this guide, we'll walk through the process of creating a custom widget for Homepage. We'll cover the basic structure of a widget, how to use translations, and how to fetch data from an API. By the end of this guide, you'll have a solid understanding of how to build your own custom widget.
+
+**Prerequisites:**
+
+- Basic knowledge of React and JavaScript
+- Familiarity with the Homepage platform
+- Understanding of JSON and API interactions
+
+Throughout this guide, we'll use `yourwidget` as a placeholder for the unique name of your custom widget. Replace `yourwidget` with the actual name of your widget. It should contain only lowercase letters and no spaces.
+
+This guide makes use of a fake API, which would return a JSON response as such, when called with the `v1/info` endpoint:
+
+```json
+{ "key1": 123, "key2": 456, "key3": 789 }
+```
+
+## Set up the widget definition
+
+Create a new folder for your widget in the `src/widgets` directory. Name the folder `yourwidget`.
+
+Inside the `yourwidget` folder, create a new file named `widget.js`. This file will contain the metadata for your widget.
+
+Open the `widget.js` file and add the following code:
+
+```js title="src/widgets/yourwidget/widget.js"
+import genericProxyHandler from "utils/proxy/handlers/generic"; // (1)!
+
+const widget = /* (2)! */ {
+  api: "{url}/{endpoint}" /* (3)! */,
+  proxyHandler: genericProxyHandler /* (1)! */,
+
+  mappings: /* (4)! */ {
+    info: /* (5)! */ {
+      endpoint: "v1/info" /* (6)! */,
+    },
+  },
+};
+
+export default widget;
+```
+
+1. We import the `genericProxyHandler` from the `utils/proxy/handlers/generic` module. The `genericProxyHandler` is a generic handler that can be used to fetch data from an API. We then assign the `genericProxyHandler` to the `proxyHandler` property of the `widget` object. There are other handlers available that you can use depending on your requirements. You can also create custom handlers if needed.
+2. We define a `widget` object that contains the metadata for the widget.
+3. The API endpoint to fetch data from. You can use placeholders like `{url}` and `{endpoint}` to dynamically generate the API endpoint based on the widget configuration.
+4. An object that contains mappings for different endpoints. Each mapping should have an `endpoint` property that specifies the endpoint to fetch data from.
+5. A mapping named `info` that specifies the `v1/info` endpoint to fetch data from. This would be called from the component as such: `#!js useWidgetAPI(widget, "info");`
+6. The `endpoint` property of the `info` mapping specifies the endpoint to fetch data from. There are other properties you can pass to the mapping, such as `method`, `headers`, and `body`.
+
+!!! warning "Important"
+
+    All widgets that fetch data from dynamic endpoints should have either `mappings` or an `allowedEndpoints` property.
+
+## Including translation strings in your widget
+
+Refer to the [translations guide](translations.md) for more details. The Homepage community prides itself on being multilingual, and we strongly encourage you to add translations for your widgets.
+
+## Create the widget component
+
+Create a new file for your widgets component, named `component.jsx`, in the `src/widgets/yourwidget` directory. We'll build the contents of the `component.jsx` file step by step.
+
+First, we'll import the necessary dependencies:
+
+```js title="src/widgets/yourwidget/component.jsx" linenums="1"
+import { useTranslation } from "next-i18next"; // (1)!
+
+import Container from "components/services/widget/container"; // (2)!
+import Block from "components/services/widget/block"; // (3)!
+import useWidgetAPI from "utils/proxy/use-widget-api"; // (4)!
+```
+
+1. `#!js useTranslation()` is a hook provided by `next-i18next` that allows us to access the translation strings
+2. `#!jsx <Container>` and `#!jsx <Block>` are custom components that we'll use to structure our widget.
+3. `#!jsx <Container>` and `#!jsx <Block>` are custom components that we'll use to structure our widget.
+4. `#!js useWidgetAPI(widget, endpoint)` is a custom hook that we'll use to fetch data from an API.
+
+---
+
+Next, we'll define a functional component named `Component` that takes a `service` prop.
+
+```js title="src/widgets/yourwidget/component.jsx" linenums="7"
+export default function Component({ service }) {}
+```
+
+---
+
+We grab the helper functions from the `useTranslation` hook.
+
+```js title="src/widgets/yourwidget/component.jsx" linenums="8"
+const { t } = useTranslation();
+```
+
+---
+
+We destructure the `widget` object from the `service` prop. The `widget` object contains the metadata for the widget, such as the API endpoint to fetch data from.
+
+```js title="src/widgets/yourwidget/component.jsx" linenums="9"
+const { widget } = service;
+```
+
+---
+
+Now, the fun part! We use the `useWidgetAPI` hook to fetch data from an API. The `useWidgetAPI` hook takes two arguments: the `widget` object and the API endpoint to fetch data from. The `useWidgetAPI` hook returns an object with `data` and `error` properties.
+
+```js title="src/widgets/yourwidget/component.jsx" linenums="10"
+const { data, error } = useWidgetAPI(widget, "info");
+```
+
+!!! tip "API Tips"
+
+    You'll see here how part of the API url is built using the `url` and `endpoint` properties from the widget definition.
+
+    In this case, we're fetching data from the `info` endpoint.  The `info` endpoint is defined in the `mappings` object.  So the full API endpoint will be `"{url}/v1/info"`.
+
+    The mapping and endpoint are often the same, but must be defined regardless.
+
+---
+
+Next, we check if there's an error or no data.
+
+If there's an error, we return a `Container` and pass it the `service` and `error` as props. The `Container` component will handle displaying the error message.
+
+```js title="src/widgets/yourwidget/component.jsx" linenums="12"
+if (error) {
+  return <Container service={service} error={error} />;
+}
+```
+
+---
+
+If there's no data, we return a `Container` component with three `Block` components, each with a `label`.
+
+```js title="src/widgets/yourwidget/component.jsx" linenums="16"
+if (!data) {
+  return (
+    <Container service={service}>
+      <Block label="yourwidget.key1" />
+      <Block label="yourwidget.key2" />
+      <Block label="yourwidget.key3" />
+    </Container>
+  );
+}
+```
+
+This will render the widget with placeholders for the data, i.e., a skeleton view.
+
+!!! tip "Translation Tips"
+
+      The `label` prop in the `Block` component corresponds to the translation key we defined earlier in the `common.js` file.  All text and numerical content should be translated.
+
+---
+
+If there is data, we return a `Container` component with three `Block` components, each with a `label` and a `value`.
+
+Here we use the `t` function from the `useTranslation` hook to translate the data values. The `t` function takes the translation key and an object with variables to interpolate into the translation string.
+
+We're using the `common.number` translation key to format the data values as numbers. This allows for easy localization of numbers, such as using commas or periods as decimal separators.
+
+There are a large number of `common` numerical translation keys available, which you can learn more about in the [Translation Guide](translations.md).
+
+```js title="src/widgets/yourwidget/component.jsx" linenums="26"
+return (
+  <Container service={service}>
+    <Block label="yourwidget.key1" value={t("common.number", { value: data.key1 })} />
+    <Block label="yourwidget.key2" value={t("common.number", { value: data.key2 })} />
+    <Block label="yourwidget.key3" value={t("common.number", { value: data.key3 })} />
+  </Container>
+);
+```
+
+---
+
+Here's the complete `component.jsx` file:
+
+```js title="src/widgets/yourwidget/component.jsx" linenums="1"
+import { useTranslation } from "next-i18next";
+
+import Container from "components/services/widget/container";
+import Block from "components/services/widget/block";
+import useWidgetAPI from "utils/proxy/use-widget-api";
+
+export default function Component({ service }) {
+  const { t } = useTranslation();
+  const { widget } = service;
+  const { data, error } = useWidgetAPI(widget, "info");
+
+  if (error) {
+    return <Container service={service} error={error} />;
+  }
+
+  if (!data) {
+    return (
+      <Container service={service}>
+        <Block label="yourwidget.key1" />
+        <Block label="yourwidget.key2" />
+        <Block label="yourwidget.key3" />
+      </Container>
+    );
+  }
+
+  return (
+    <Container service={service}>
+      <Block label="yourwidget.key1" value={t("common.number", { value: data.key1 })} />
+      <Block label="yourwidget.key2" value={t("common.number", { value: data.key2 })} />
+      <Block label="yourwidget.key3" value={t("common.number", { value: data.key3 })} />
+    </Container>
+  );
+}
+```
+
+## Add the widget to the Homepage
+
+To add your widget to the Homepage, you need to register it in the `src/widgets/widgets.js` file.
+
+Open the `src/widgets/widgets.js` file and import the `Component` from your widget's `component.jsx` file. Please keep the alphabetical order.
+
+```js
+// ...
+import yourwidget from "./yourwidget/widget";
+// ...
+```
+
+Add `yourwidget` to the `widgets` object. Please keep the alphabetical order.
+
+```js
+const widgets = {
+  // ...
+  yourwidget: yourwidget,
+  // ...
+};
+```
+
+You also need to add the widget to the `components` object in the `src/widgets/components.js` file.
+
+Open the `src/widgets/components.js` file and import the `Component` from your widget's `component.jsx` file.
+
+Please keep the alphabetical order.
+
+```js
+const components = {
+  // ...
+  yourwidget: dynamic(() => import("./yourwidget/component")),
+  // ...
+};
+```
+
+## Using the widget
+
+You can now use your custom widget in your Homepage. Open your `services.yaml` file and add a new service with the `yourwidget` widget.
+
+```yaml
+- Services:
+    - Your Widget:
+        icon: yourwidget.svg
+        href: https://example.com/
+        widget:
+          type: yourwidget
+          url: http://127.0.0.1:1337
+```
+
+!!! tip "API Tips"
+
+    You'll see here how part of the API url is built using the `url` and `endpoint` properties from the widget definition.
+
+    We defined the api endpoint as `"{url}/{endpoint}"`.  This is where the `url` is defined.  So the full API endpoint will be `http://127.0.0.1:1337/{endpoint}`.
+
+---
+
+That's it! You've successfully created a custom widget for Homepage. If you have any questions or need help, feel free to reach out to the Homepage community for assistance. Happy coding!

docs/widgets/index.md

@@ -1,13 +1,16 @@
 ---
 title: Widgets
-description: Homepage info and status widgets.
+description: Find information on how to configure specific widgets in Homepage.
+icon: material/widgets
 ---
 
 Homepage has two types of widgets: info and service. Below we'll cover each type and how to configure them.
 
+The left navigation of this site contains links to all available widgets.
+
 ## 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:
+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.yaml` file. Here's an example:
 
 ```yaml
 - Plex:
@@ -24,7 +27,7 @@ Service widgets are used to display the status of a service, often a web service
 
 ## 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:
+Info widgets are used to display information in the header, often about your system or environment. Info widgets are defined your `widgets.yaml` file. Here's an example:
 
 ```yaml
 - openmeteo:

docs/widgets/info/datetime.md

@@ -9,9 +9,9 @@ Formatting is locale aware and will present your date in the regional format you
 
 ```yaml
 - datetime:
-      text_size: xl
-      format:
-          timeStyle: short
+    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.
@@ -23,29 +23,29 @@ A few examples,
 ```yaml
 # 13:37
 format:
-    timeStyle: short
-    hourCycle: h23
+  timeStyle: short
+  hourCycle: h23
 ```
 
 ```yaml
 # 1:37 PM
 format:
-    timeStyle: short
-    hour12: true
+  timeStyle: short
+  hour12: true
 ```
 
 ```yaml
 # 1/23/22, 1:37 PM
 format:
-    dateStyle: short
-    timeStyle: short
-    hour12: true
+  dateStyle: short
+  timeStyle: short
+  hour12: true
 ```
 
 ```yaml
 # 4 januari 2023 om 13:51:25 PST
 locale: nl
 format:
-    dateStyle: long
-    timeStyle: long
+  dateStyle: long
+  timeStyle: long
 ```

docs/widgets/info/glances.md

@@ -9,16 +9,18 @@ The Glances widget allows you to monitor the resources (CPU, memory, storage, te
 
 ```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
+    url: http://host.or.ip:port
+    username: user # optional if auth enabled in Glances
+    password: pass # optional if auth enabled in Glances
+    version: 4 # required only if running glances v4 or higher, defaults to 3
+    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)
+    diskUnits: bytes # optional, bytes (default) or bbytes. Only applies to disk
+    expanded: true # show the expanded view
+    label: MyMachine # optional
 ```
 
 Multiple disks can be specified as:

docs/widgets/info/greeting.md

@@ -7,8 +7,8 @@ This allows you to display simple text, can be configured like so:
 
 ```yaml
 - greeting:
-      text_size: xl
-      text: Greeting Text
+    text_size: xl
+    text: Greeting Text
 ```
 
 Valid text sizes are `4xl`, `3xl`, `2xl`, `xl`, `md`, `sm`, `xs`.

docs/widgets/info/index.md

@@ -1,4 +1,21 @@
 ---
 title: Info Widgets
 description: Homepage info widgets.
+search:
+  exclude: true
 ---
+
+You can also find a list of all available info widgets in the sidebar navigation.
+
+- [Date & Time](datetime.md)
+- [Glances](glances.md)
+- [Greeting](greeting.md)
+- [Kubernetes](kubernetes.md)
+- [Logo](logo.md)
+- [Longhorn](longhorn.md)
+- [OpenMeteo](openmeteo.md)
+- [OpenWeatherMap](openweathermap.md)
+- [Resources](resources.md)
+- [Search](search.md)
+- [Stocks](stocks.md)
+- [UniFi Controller](unifi_controller.md)

docs/widgets/info/kubernetes.md

@@ -9,23 +9,23 @@ 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
+    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/longhorn.md

@@ -12,18 +12,26 @@ 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
+    # 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`.
+The Longhorn URL and credentials are stored in the `providers` section of the `settings.yaml`. e.g.:
+
+```yaml
+providers:
+  longhorn:
+    username: "longhorn-username" # optional
+    password: "very-secret-longhorn-password" # optional
+    url: https://longhorn.aesop.network
+```

docs/widgets/info/openmeteo.md

@@ -7,12 +7,14 @@ No registration is required at all! See [https://open-meteo.com/en/docs](https:/
 
 ```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
+    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
+    format: # optional, Intl.NumberFormat options
+      maximumFractionDigits: 1
 ```
 
 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

@@ -3,17 +3,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.
+The free tier "One Call API" is all that's 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
+    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
+    format: # optional, Intl.NumberFormat options
+      maximumFractionDigits: 1
 ```
 
 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

@@ -9,32 +9,37 @@ The disk path is the path reported by `df` (Mounted On), or the mount point of t
 
 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._
+The resources widget primarily relies on a popular tool called [systeminformation](https://systeminformation.io). Thus, any limitiations of that software apply, for example, BRTFS RAID is not supported for the disk usage. In this case users may want to use the [glances widget](glances.md) instead.
+
+_Note: unfortunately, the package used for getting CPU temp ([systeminformation](https://systeminformation.io)) is not compatible 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
+    cpu: true
+    memory: true
+    disk: /disk/mount/path
+    cputemp: true
+    tempmin: 0 # optional, minimum cpu temp
+    tempmax: 100 # optional, maximum cpu temp
+    uptime: true
+    units: imperial # only used by cpu temp
+    refresh: 3000 # optional, in ms
+    diskUnits: bytes # optional, bytes (default) or bbytes. Only applies to disk
 ```
 
 You can also pass a `label` option, which allows you to group resources under named sections,
 
 ```yaml
 - resources:
-      label: System
-      cpu: true
-      memory: true
+    label: System
+    cpu: true
+    memory: true
 
 - resources:
-      label: Storage
-      disk: /mnt/storage
+    label: Storage
+    disk: /mnt/storage
 ```
 
 Which produces something like this,
@@ -45,11 +50,11 @@ If you have more than a single disk and would like to group them together under
 
 ```yaml
 - resources:
-      label: Storage
-      disk:
-          - /mnt/storage
-          - /mnt/backup
-          - /mnt/media
+    label: Storage
+    disk:
+      - /mnt/storage
+      - /mnt/backup
+      - /mnt/media
 ```
 
 To produce something like this,
@@ -60,12 +65,12 @@ You can additionally supply an optional `expanded` property set to true in order
 
 ```yaml
 - resources:
-      label: Array Disks
-      expanded: true
-      disk:
-          - /disk1
-          - /disk2
-          - /disk3
+    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

@@ -7,25 +7,49 @@ You can add a search bar to your top widget area that can search using Google, D
 
 ```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
+    provider: google # google, duckduckgo, bing, baidu, brave or custom
+    focus: true # Optional, will set focus to the search bar on page load
+    showSearchSuggestions: true # Optional, will show search suggestions. Defaults to false
+    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
+    provider: custom
+    url: https://www.ecosia.org/search?q=
+    target: _blank
+    suggestionUrl: https://ac.ecosia.org/autocomplete?type=list&q= # Optional
+    showSearchSuggestions: true # Optional
 ```
 
 multiple providers is also supported via a dropdown (excluding custom):
 
 ```yaml
 - search:
-      provider: [brave, google, duckduckgo]
+    provider: [brave, google, duckduckgo]
 ```
 
+The response body for the URL provided with the `suggestionUrl` option should look like this:
+
+```json
+[
+  "home",
+  [
+    "home depot",
+    "home depot near me",
+    "home equity loan",
+    "homeworkify",
+    "homedepot.com",
+    "homebase login",
+    "home depot credit card",
+    "home goods"
+  ]
+]
+```
+
+The first entry of the array contains the search query, the second one is an array of the suggestions.
+In the example above, the search query was **home**.
+
 _Added in v0.1.6, updated in 0.6.0_

docs/widgets/info/stocks.md

@@ -0,0 +1,48 @@
+---
+title: Stocks
+description: Stocks Information Widget Configuration
+---
+
+_(Find the Stocks service widget [here](../services/stocks.md))_
+
+The Stocks Information Widget allows you to include basic stock market data in
+your Homepage header. The widget includes the current price of a stock, and the
+change in price for the day.
+
+Finnhub.io is currently the only supported provider for the stocks widget.
+You can sign up for a free api key at [finnhub.io](https://finnhub.io).
+You are encouraged to read finnhub.io's
+[terms of service/privacy policy](https://finnhub.io/terms-of-service) before
+signing up. The documentation for the endpoint that is utilized can be viewed
+[here](https://finnhub.io/docs/api/quote).
+
+You must set `finnhub` as a provider in your `settings.yaml` like below:
+
+```yaml
+providers:
+  finnhub: yourfinnhubapikeyhere
+```
+
+Next, configure the stocks widget in your `widgets.yaml`:
+
+The information widget allows for up to 8 items in the watchlist.
+
+```yaml
+- stocks:
+    provider: finnhub
+    color: true # optional, defaults to true
+    cache: 1 # optional, default caches results for 1 minute
+    watchlist:
+      - GME
+      - AMC
+      - NVDA
+      - AMD
+      - TSM
+      - MSFT
+      - AAPL
+      - BRK.A
+```
+
+The above configuration would result in something like this:
+
+![Example of Stocks Widget](../../assets/widget_stocks_demo.png)

docs/widgets/info/unifi_controller.md

@@ -9,7 +9,9 @@ You can display general connectivity status from your Unifi (Network) Controller
 
 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._
+!!! hint
+
+    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">
 

docs/widgets/info/weather.md

@@ -5,16 +5,18 @@ 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.
+The free tier is all that's 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
+    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
+    format: # optional, Intl.NumberFormat options
+      maximumFractionDigits: 1
 ```
 
 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

@@ -3,14 +3,16 @@ title: Adguard Home
 description: Adguard Home Widget Configuration
 ---
 
+Learn more about [Adguard Home](https://github.com/AdguardTeam/AdGuardHome).
+
 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
+  type: adguard
+  url: http://adguard.host.or.ip
+  username: admin
+  password: password
 ```

docs/widgets/services/atsumeru.md

@@ -3,14 +3,16 @@ title: Atsumeru
 description: Atsumeru Widget Configuration
 ---
 
+Learn more about [Atsumeru](https://github.com/AtsumeruDev/Atsumeru).
+
 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
+  type: atsumeru
+  url: http://atsumeru.host.or.ip:port
+  username: username
+  password: password
 ```

docs/widgets/services/audiobookshelf.md

@@ -3,13 +3,15 @@ title: Audiobookshelf
 description: Audiobookshelf Widget Configuration
 ---
 
+Learn more about [Audiobookshelf](https://github.com/advplyr/audiobookshelf).
+
 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
+  type: audiobookshelf
+  url: http://audiobookshelf.host.or.ip:port
+  key: audiobookshelflapikey
 ```

docs/widgets/services/authentik.md

@@ -3,22 +3,23 @@ title: Authentik
 description: Authentik Widget Configuration
 ---
 
+Learn more about [Authentik](https://github.com/goauthentik/authentik).
+
 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:
+You will need to generate an API token for an existing user under `Admin Portal` > `Directory` > `Tokens & App passwords`.
+Make sure to set Intent to "API Token".
 
-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
+The account you made the API token for also needs the following **Assigned global permissions** in Authentik:
+
+- authentik Core -> Can view User (Model: User)
+- authentik Events -> Can view Event (Model: Event)
 
 Allowed fields: `["users", "loginsLast24H", "failedLoginsLast24H"]`.
 
 ```yaml
 widget:
-    type: authentik
-    url: http://authentik.host.or.ip:22070
-    key: api_token
+  type: authentik
+  url: http://authentik.host.or.ip:22070
+  key: api_token
 ```

docs/widgets/services/autobrr.md

@@ -3,13 +3,15 @@ title: Autobrr
 description: Autobrr Widget Configuration
 ---
 
+Learn more about [Autobrr](https://github.com/autobrr/autobrr).
+
 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
+  type: autobrr
+  url: http://autobrr.host.or.ip
+  key: apikeyapikeyapikeyapikeyapikey
 ```

docs/widgets/services/azuredevops.md

@@ -3,24 +3,26 @@ title: Azure DevOps
 description: Azure DevOps Widget Configuration
 ---
 
+Learn more about [Azure DevOps](https://azure.microsoft.com/en-us/products/devops).
+
 This widget has 2 functions:
 
-1. Pipelines: checks if the relevant pipeline is running or not, and if not, reports the last status.\
+1. Pipelines: checks if the relevant pipeline is running or not, and if not, reports the last status.<br>
    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.\
+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 at least 1 person and not yet completed.<br>
    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
+  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

@@ -3,13 +3,15 @@ title: Bazarr
 description: Bazarr Widget Configuration
 ---
 
+Learn more about [Bazarr](https://github.com/morpheus65535/bazarr).
+
 Find your API key under `Settings > General`.
 
 Allowed fields: `["missingEpisodes", "missingMovies"]`.
 
 ```yaml
 widget:
-    type: bazarr
-    url: http://bazarr.host.or.ip
-    key: apikeyapikeyapikeyapikeyapikey
+  type: bazarr
+  url: http://bazarr.host.or.ip
+  key: apikeyapikeyapikeyapikeyapikey
 ```

docs/widgets/services/caddy.md

@@ -3,10 +3,12 @@ title: Caddy
 description: Caddy Widget Configuration
 ---
 
+Learn more about [Caddy](https://github.com/caddyserver/caddy).
+
 Allowed fields: `["upstreams", "requests", "requests_failed"]`.
 
 ```yaml
 widget:
-    type: caddy
-    url: http://caddy.host.or.ip:adminport # default admin port is 2019
+  type: caddy
+  url: http://caddy.host.or.ip:adminport # default admin port is 2019
 ```

docs/widgets/services/calendar.md

@@ -3,6 +3,8 @@ title: Calendar
 description: Calendar widget
 ---
 
+## Monthly view
+
 <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.
@@ -11,15 +13,45 @@ This widget shows monthly calendar, with optional integrations to show events fr
 widget:
   type: calendar
   firstDayInWeek: sunday # optional - defaults to monday
+  view: monthly # optional - possible values monthly, agenda
+  maxEvents: 10 # optional - defaults to 10
+  showTime: true # optional - show time for event happening today - defaults to false
+  timezone: America/Los_Angeles # optional and only when timezone is not detected properly (slightly slower performance) - force timezone for ical events (if it's the same - no change, if missing or different in ical - will be converted to this timezone)
   integrations: # optional
-    - type: sonarr # active widget type that is currently enabled on homepage - possible values: radarr, sonarr, lidarr, readarr
+    - type: sonarr # active widget type that is currently enabled on homepage - possible values: radarr, sonarr, lidarr, readarr, ical
       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
+    - type: ical # Show calendar events from another service
+      url: https://domain.url/with/link/to.ics # URL with calendar events
+      name: My Events # required - name for these calendar events
+      color: zinc # optional - defaults to pre-defined color for the service (zinc for ical)
+      params: # optional - additional params for the service
+        showName: true # optional - show name before event title in event line - defaults to false
 ```
 
+## Agenda
+
+This view shows only list of events from configured integrations
+
+```yaml
+widget:
+  type: calendar
+  view: agenda
+  maxEvents: 10 # optional - defaults to 10
+  showTime: true # optional - show time for event happening today - defaults to false
+  previousDays: 3 # optional - shows events since three days ago - defaults to 0
+  integrations: # same as in Monthly view example
+```
+
+## Integrations
+
 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).
+
+### iCal
+
+This custom integration allows you to show events from any calendar that supports iCal format, for example, Google Calendar (go to `Settings`, select specific calendar, go to `Integrate calendar`, copy URL from `Public Address in iCal format`).

docs/widgets/services/calibre-web.md

@@ -3,14 +3,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).**
+Learn more about [Calibre-web](https://github.com/janeczku/calibre-web).
+
+**Note: widget requires calibre-web ≥ v0.6.21.**
 
 Allowed fields: `["books", "authors", "categories", "series"]`.
 
 ```yaml
 widget:
-    type: calibreweb
-    url: http://your.calibreweb.host:port
-    username: username
-    password: password
+  type: calibreweb
+  url: http://your.calibreweb.host:port
+  username: username
+  password: password
 ```

docs/widgets/services/changedetectionio.md

@@ -3,11 +3,13 @@ title: Changedetection.io
 description: Changedetection.io Widget Configuration
 ---
 
+Learn more about [Changedetection.io](https://github.com/dgtlmoon/changedetection.io).
+
 Find your API key under `Settings > API`.
 
 ```yaml
 widget:
-    type: changedetectionio
-    url: http://changedetection.host.or.ip:port
-    key: apikeyapikeyapikeyapikeyapikey
+  type: changedetectionio
+  url: http://changedetection.host.or.ip:port
+  key: apikeyapikeyapikeyapikeyapikey
 ```

docs/widgets/services/channelsdvrserver.md

@@ -3,8 +3,10 @@ title: Channels DVR Server
 description: Channels DVR Server Widget Configuration
 ---
 
+Learn more about [Channels DVR Server](https://getchannels.com/dvr-server/).
+
 ```yaml
 widget:
-    type: channelsdvrserver
-    url: http://192.168.1.55:8089
+  type: channelsdvrserver
+  url: http://server.host.or.ip:port
 ```

docs/widgets/services/cloudflared.md

@@ -3,14 +3,16 @@ title: Cloudflare Tunnels
 description: Cloudflare Tunnels Widget Configuration
 ---
 
+Learn more about [Cloudflare Tunnels](https://www.cloudflare.com/products/tunnel/).
+
 _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
+  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

@@ -3,23 +3,26 @@ title: Coin Market Cap
 description: Coin Market Cap Widget Configuration
 ---
 
+Learn more about [Coin Market Cap](https://coinmarketcap.com/api).
+
 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
+  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:
+You can also specify slugs instead of symbols (since symbols aren't guaranteed to be unique). If you supply both, slugs will be used. For example:
 
 ```yaml
 widget:
-    type: coinmarketcap
-    slugs: [chia-network, uniswap]
-    key: apikeyapikeyapikeyapikeyapikey
+  type: coinmarketcap
+  slugs: [chia-network, uniswap]
+  key: apikeyapikeyapikeyapikeyapikey
 ```

docs/widgets/services/crowdsec.md

@@ -0,0 +1,19 @@
+---
+title: Crowdsec
+description: Crowdsec Widget Configuration
+---
+
+Learn more about [Crowdsec](https://crowdsec.net).
+
+See the [crowdsec docs](https://docs.crowdsec.net/docs/local_api/intro/#machines) for information about registering a machine,
+in most instances you can use the default credentials (`/etc/crowdsec/local_api_credentials.yaml`).
+
+Allowed fields: `["alerts", "bans"]`.
+
+```yaml
+widget:
+  type: crowdsec
+  url: http://crowdsechostorip:port
+  username: localhost # machine_id in crowdsec
+  password: password
+```

docs/widgets/services/customapi.md

@@ -9,31 +9,64 @@ Fields need to be defined in the `mappings` section YAML object to correlate wit
 
 ```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
+  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
+  requestBody: # optional, can be string or object, see below
+  display: # optional, default to block, 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
+    - field: key # needs to be YAML string or object
+      label: Field 4
+      format: date # optional - defaults to text
+      locale: nl # optional
+      dateStyle: long # optional - defaults to "long". Allowed values: `["full", "long", "medium", "short"]`.
+      timeStyle: medium # optional - Allowed values: `["full", "long", "medium", "short"]`.
+    - field: key # needs to be YAML string or object
+      label: Field 5
+      format: relativeDate # optional - defaults to text
+      locale: nl # optional
+      style: short # optional - defaults to "long". Allowed values: `["long", "short", "narrow"]`.
+      numeric: auto # optional - defaults to "always". Allowed values `["always", "auto"]`.
+    - field: key
+      label: Field 6
+      format: text
+      additionalField: # optional
+        field:
+          hourly:
+            time: other key
+        color: theme # optional - defaults to "". Allowed values: `["theme", "adaptive", "black", "white"]`.
+        format: date # optional
+    - field: key
+      label: Number of things in array
+      format: size
+    # This (no field) will take the root of the API response, e.g. when APIs return an array:
+    - label: Number of items
+      format: size
 ```
 
-Supported formats for the values are `text`, `number`, `float`, `percent`, `bytes` and `bitrate`.
+Supported formats for the values are `text`, `number`, `float`, `percent`, `bytes`, `bitrate`, `size`, `date` and `relativeDate`.
+
+The `dateStyle` and `timeStyle` options of the `date` format are passed directly to [Intl.DateTimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat) and the `style` and `numeric` options of `relativeDate` are passed to [Intl.RelativeTimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/RelativeTimeFormat).
+
+The `size` format will return the length of the array or string, or the number of keys in an object. This is then formatted as `number`.
 
 ## Example
 
@@ -41,62 +74,97 @@ 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)"
+  "id": 1,
+  "name": "Rick Sanchez",
+  "status": "Alive",
+  "species": "Human",
+  "gender": "Male",
+  "origin": {
+    "name": "Earth (C-137)"
+  },
+  "locations": [
+    {
+      "name": "Earth (C-137)"
     },
-    "locations": [
-        {
-            "name": "Earth (C-137)"
-        },
-        {
-            "name": "Citadel of Ricks"
-        }
-    ]
+    {
+      "name": "Citadel of Ricks"
+    }
+  ]
 }
 ```
 
-Define the `mappings` section as an aray, for example:
+Define the `mappings` section as an array, 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
+  - 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:
+You can manipulate data with the following tools `remap`, `scale`, `prefix` 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
+    - 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
+  suffix: "kW"
+- field: key6
+  label: Price
+  format: float
+  prefix: "$"
+```
+
+## List View
+
+You can change the default block view to a list view by setting the `display` option to `list`.
+
+The list view can optionally display an additional field next to the primary field.
+
+`additionalField`: Similar to `field`, but only used in list view. Displays additional information for the mapping object on the right.
+
+`field`: Defined the same way as other custom api widget fields.
+
+`color`: Allowed options: `"theme", "adaptive", "black", "white"`. The option `adaptive` will apply a color using the value of the `additionalField`, green for positive numbers, red for negative numbers.
+
+```yaml
+- field: key
+  label: Field
+  format: text
+  remap:
+    - value: 0
+      to: None
+    - value: 1
+      to: Connected
+    - any: true # will map all other values
+      to: Unknown
+  additionalField:
+    field:
+      hourly:
+        time: key
+    color: theme
+    format: date
 ```
 
 ## Custom Headers
@@ -105,5 +173,18 @@ Pass custom headers using the `headers` option, for example:
 
 ```yaml
 headers:
-    X-API-Token: token
+  X-API-Token: token
 ```
+
+## Custom Request Body
+
+Pass custom request body using the `requestBody` option in either a string or object format. Objects will automatically be converted to a JSON string.
+
+```yaml
+requestBody:
+  foo: bar
+# or
+requestBody: "{\"foo\":\"bar\"}"
+```
+
+Both formats result in `{"foo":"bar"}` being sent as the request body. Don't forget to set your `Content-Type` headers!

docs/widgets/services/deluge.md

@@ -3,13 +3,15 @@ title: Deluge
 description: Deluge Widget Configuration
 ---
 
+Learn more about [Deluge](https://deluge-torrent.org/).
+
 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
+  type: deluge
+  url: http://deluge.host.or.ip
+  password: password # webui password
 ```

docs/widgets/services/develancacheui.md

@@ -0,0 +1,14 @@
+---
+title: DeveLanCacheUI
+description: DeveLanCacheUI Widget Configuration
+---
+
+Learn more about [DeveLanCacheUI](https://github.com/devedse/DeveLanCacheUI_Backend).
+
+```yaml
+widget:
+  type: develancacheui
+  url: http://your.develancacheui_backend.host:port
+```
+
+The url should point to the DeveLanCacheUI Backend (API)

docs/widgets/services/diskstation.md

@@ -3,34 +3,41 @@ title: Synology Disk Station
 description: Synology Disk Station Widget Configuration
 ---
 
+Learn more about [Synology Disk Station](https://www.synology.com/en-global/dsm).
+
 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:
+To access these system metrics you need to connect to the DiskStation (`DSM`) 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`.
+6. Now _only_ allow login to the `DSM` 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 `DSM` 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.
+If you encounter issues during testing:
+
+1. 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.
+2. Login to your Synology DSM with the newly created account and accept terms and conditions.
+3. Reattempt
 
 ```yaml
 widget:
-    type: diskstation
-    url: http://diskstation.host.or.ip:port
-    username: username
-    password: password
-    volume: volume_N # optional
+  type: diskstation
+  url: http://diskstation.host.or.ip:port
+  username: username
+  password: password
+  volume: volume_N # optional
 ```

docs/widgets/services/downloadstation.md

@@ -3,14 +3,16 @@ title: Synology Download Station
 description: Synology Download Station Widget Configuration
 ---
 
+Learn more about [Synology Download Station](https://www.synology.com/en-us/dsm/packages/DownloadStation).
+
 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
+  type: downloadstation
+  url: http://downloadstation.host.or.ip:port
+  username: username
+  password: password
 ```

docs/widgets/services/emby.md

@@ -3,15 +3,20 @@ title: Emby
 description: Emby Widget Configuration
 ---
 
+Learn more about [Emby](https://github.com/MediaBrowser/Emby).
+
 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
+  type: emby
+  url: http://emby.host.or.ip
+  key: apikeyapikeyapikeyapikeyapikey
+  enableBlocks: true # optional, defaults to false
+  enableNowPlaying: true # optional, defaults to true
+  enableUser: true # optional, defaults to false
+  showEpisodeNumber: true # optional, defaults to false
+  expandOneStreamToTwoRows: false # optional, defaults to true
 ```