Update contributing / development guidelines

---------

Co-authored-by: shamoon <4887959+shamoon@users.noreply.github.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"

.github/DISCUSSION_TEMPLATE/support.yml

@@ -0,0 +1,49 @@
+body:
+  - 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,2 @@
-github: benphelps
-ko_fi: benphelps
-custom: ["https://paypal.me/phelpsben"]
+github: [gethomepage, benphelps, shamoon]
+open_collective: homepage

.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/gethomepage/homepage/discussions/new) or [ask in chat](https://discord.gg/SaPGSzrEZC).
-
-        Before opening an issue, please double check:
-
-        - [The troubleshooting guide](https://gethomepage.dev/latest/more/troubleshooting/).
-        - [The homepage documentation](https://gethomepage.dev/)
-        - [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 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 suggest I open an issue (note that AI bots are not maintainers).
           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/gethomepage/homepage/search?q=&type=issues) and [discussions](https://github.com/gethomepage/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

@@ -2,7 +2,7 @@ blank_issues_enabled: false
 contact_links:
   - name: 🤔 Questions and Help
     url: https://github.com/gethomepage/homepage/discussions
-    about: This issue tracker is for bugs only, not general support questions. Please refer to our Discussions.
+    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.

.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).
-- [ ] I have checked that all code style checks pass using pre-commit hooks and linting checks with `pnpm lint` (see development guidelines).
+- [ ] If applicable, I have 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@v1
+      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:
@@ -39,12 +41,12 @@ jobs:
         uses: actions/checkout@v4
       -
         name: Install python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: 3.x
       -
         name: Check files
-        uses: pre-commit/action@v3.0.0
+        uses: pre-commit/action@v3.0.1
 
   build:
     name: Docker Build & Push
@@ -117,7 +119,7 @@ jobs:
         uses: docker/build-push-action@v5
         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: |

.github/workflows/docs-publish.yml

@@ -27,12 +27,12 @@ jobs:
         uses: actions/checkout@v4
       -
         name: Install python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: 3.x
       -
         name: Check files
-        uses: pre-commit/action@v3.0.0
+        uses: pre-commit/action@v3.0.1
 
   test:
     name: Test Build
@@ -42,11 +42,11 @@ jobs:
       - 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
@@ -67,18 +67,18 @@ jobs:
       - 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==1.1.2
+      - run: pip install mike==2.0.0
       - run: pip install git+https://${GH_TOKEN}@github.com/benphelps/mkdocs-material-insiders.git
       - name: Set Git config
         run: |

.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);
+              }
+            }

CONTRIBUTING.md

@@ -16,9 +16,9 @@ We use github to host code, to track issues and feature requests, as well as acc
 
 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/gethomepage/homepage/issues)
+## Report bugs using Github [discussions](https://github.com/gethomepage/homepage/discussions)
 
-We use GitHub issues to track public bugs. Report a bug by [opening a new issue](https://github.com/gethomepage/homepage/issues/new); it's that easy!
+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
 
@@ -48,6 +48,24 @@ Please see information in the docs regarding [code formatting with pre-commit ho
 
 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.

README.md

@@ -41,7 +41,7 @@ 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
 
@@ -164,8 +164,6 @@ mkdocs serve # or build, to build the static site
 
 If you have any questions, suggestions, or general issues, please start a discussion on the [Discussions](https://github.com/gethomepage/homepage/discussions) page.
 
-For bug reports, please open an issue on the [Issues](https://github.com/gethomepage/homepage/issues) page.
-
 ## Contributing & Contributors
 
 Contributions are welcome! Please see the [CONTRIBUTING.md](CONTRIBUTING.md) file for more information.

crowdin.yml

@@ -1,3 +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,6 +12,7 @@ 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
@@ -29,4 +30,8 @@ By default, the description will use the hostname of the link, but you can overr
           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

@@ -153,7 +153,7 @@ labels:
   - homepage.widget.fields=["field1","field2"] # optional
 ```
 
-You can add specify fields for e.g. the [CustomAPI](/widgets/services/customapi) widget by using array-style dot notation:
+You can add specify fields for e.g. the [CustomAPI](../widgets/services/customapi.md) widget by using array-style dot notation:
 
 ```yaml
 labels:
@@ -164,10 +164,10 @@ labels:
   - homepage.description=Media server
   - homepage.widget.type=customapi
   - homepage.widget.url=http://argus.service/api/v1/service/summary/emby
-  - homepage.widget.field[0].label=Deployed Version
-  - homepage.widget.field[0].field.status=deployed_version
-  - homepage.widget.field[1].label=Latest Version
-  - homepage.widget.field[1].field.status=latest_version
+  - 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
@@ -201,6 +201,22 @@ 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.md](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:

docs/configs/kubernetes.md

@@ -79,6 +79,7 @@ metadata:
     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
@@ -95,6 +96,8 @@ spec:
 
 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.
+
 ### 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:
@@ -116,6 +119,7 @@ metadata:
     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

docs/configs/services.md

@@ -101,7 +101,7 @@ 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 external host. As of v0.8.0, the ping feature attempts to use a true (ICMP) ping command on the underlying host.
+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:
@@ -179,7 +179,7 @@ Services may be connected to a Docker container, either running on the local mac
 
 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

@@ -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.
@@ -337,12 +379,14 @@ There are a few optional settings for the Quick Launch feature:
 
 - `searchDescriptions`: which lets you control whether item descriptions are included in searches. This is off by default. When enabled, results that match the item name will be placed above those that only match the description.
 - `hideInternetSearch`: disable automatically including the currently-selected web search (e.g. from the widget) as a Quick Launch option. This is false by default, enabling the feature.
+- `showSearchSuggestions`: shows search suggestions for the internet search. This value will be inherited from the search widget if it is not specified. If it is not specified there either, it will default to false.
 - `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
 ```
 
@@ -362,6 +406,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`:
@@ -384,7 +430,7 @@ If you have both set the per-service settings take precedence.
 
 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 montior and ping response time in ms and the docker / k8s container status
+- 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
 
@@ -404,6 +450,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`:

docs/installation/k8s.md

@@ -361,3 +361,33 @@ spec:
                 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/more/development.md

@@ -39,12 +39,24 @@ Once installed, hooks will run when you commit. If the formatting isn't quite ri
 
 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 5 'up-votes'
+- 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.
 - Widgets should be only one row of blocks
-- Widgets should be no more than 4 blocks wide
+- 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/more/troubleshooting.md

@@ -6,6 +6,10 @@ hide:
   - navigation
 ---
 
+## Introducing the Homepage AI Bot
+
+Thanks to the generous folks at [Glime](https://glimelab.ai), Homepage is now equipped with a pretty clever AI-powered bot. The bot has full knowledge of our docs, GitHub issues and discussions and is great at answering specific questions about setting up your Homepage. To use the bot, just hit the 'Ask AI' button on any page in our docs, [open a GitHub discussion](https://github.com/gethomepage/homepage/discussions) or check out the [#ai-support channel on Discord](https://discord.com/channels/1019316731635834932/1177885603552038993)!
+
 ## 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.

docs/scripts/extra.js

@@ -0,0 +1,35 @@
+var glimeScript;
+var glimeStyles = [];
+document$.subscribe(function () {
+  if (!glimeScript) {
+    glimeScript = document.createElement("script");
+    glimeScript.setAttribute("src", "https://cdn.glimelab.ai/widget/1.0.0/widget.js");
+    glimeScript.setAttribute("onload", "onGlimeLoad()");
+    document.head.appendChild(glimeScript);
+  } else {
+    var newGlimeStyle = document.createElement("style");
+    document.head.appendChild(newGlimeStyle);
+    var i = 0;
+    glimeStyles.forEach((rule) => {
+      newGlimeStyle.sheet.insertRule(rule.cssText, i);
+      i++;
+    });
+  }
+});
+
+onGlimeLoad = () => {
+  window.glime.init("Bl3mlvfCnTnRm5");
+  setTimeout(() => {
+    const sheets = document.styleSheets;
+    [...sheets].forEach((sheet) => {
+      if (!sheet.href) {
+        [...sheet.cssRules].forEach((rule) => {
+          if (!rule || rule.href || !rule.selectorText) return;
+          if (rule.selectorText.indexOf(".css-") === 0 || rule.selectorText.indexOf("glime") > -1) {
+            glimeStyles.push(rule);
+          }
+        });
+      }
+    });
+  }, 1000);
+};

docs/stylesheets/extra.css

@@ -18,3 +18,7 @@
         border-color: var(--md-default-bg-color--lighter);
     }
 }
+
+#glimeRoot * {
+    font-family: var(--md-text-font) !important;
+}

docs/widgets/index.md

@@ -7,7 +7,7 @@ Homepage has two types of widgets: info and service. Below we'll cover each type
 
 ## 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 +24,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/glances.md

@@ -12,11 +12,13 @@ The Glances widget allows you to monitor the resources (CPU, memory, storage, te
     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
 ```

docs/widgets/info/longhorn.md

@@ -26,4 +26,12 @@ It can show the aggregate metrics and/or the individual node metrics.
       - 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

@@ -13,6 +13,8 @@ No registration is required at all! See [https://open-meteo.com/en/docs](https:/
     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

@@ -14,6 +14,8 @@ The free tier "One Call API" is all that's required, you will need to [subscribe
     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

@@ -22,6 +22,7 @@ _Note: unfortunately, the package used for getting CPU temp ([systeminformation]
     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,

docs/widgets/info/search.md

@@ -9,6 +9,7 @@ You can add a search bar to your top widget area that can search using Google, D
 - search:
     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
 ```
 
@@ -17,8 +18,10 @@ or for a custom search:
 ```yaml
 - search:
     provider: custom
-    url: https://lougle.com/?q=
+    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):
@@ -28,4 +31,25 @@ multiple providers is also supported via a dropdown (excluding custom):
     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/weather.md

@@ -15,6 +15,8 @@ The free tier is all that's required, you will need to [register](https://www.we
     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,6 +3,8 @@ 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"]`.

docs/widgets/services/atsumeru.md

@@ -3,6 +3,8 @@ 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"]`.

docs/widgets/services/audiobookshelf.md

@@ -3,6 +3,8 @@ 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"]`

docs/widgets/services/authentik.md

@@ -3,16 +3,19 @@ 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
+  - User
+- authentik Events
+  - Event
 
 Allowed fields: `["users", "loginsLast24H", "failedLoginsLast24H"]`.
 

docs/widgets/services/autobrr.md

@@ -3,6 +3,8 @@ 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"]`.

docs/widgets/services/azuredevops.md

@@ -3,12 +3,14 @@ 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 at least 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)

docs/widgets/services/bazarr.md

@@ -3,6 +3,8 @@ 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"]`.

docs/widgets/services/caddy.md

@@ -3,6 +3,8 @@ title: Caddy
 description: Caddy Widget Configuration
 ---
 
+Learn more about [Caddy](https://github.com/caddyserver/caddy).
+
 Allowed fields: `["upstreams", "requests", "requests_failed"]`.
 
 ```yaml

docs/widgets/services/calendar.md

@@ -15,13 +15,21 @@ widget:
   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
@@ -33,6 +41,8 @@ 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
 ```
 
@@ -41,3 +51,7 @@ widget:
 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,7 +3,9 @@ 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"]`.
 

docs/widgets/services/changedetectionio.md

@@ -3,6 +3,8 @@ 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

docs/widgets/services/channelsdvrserver.md

@@ -3,6 +3,8 @@ 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

docs/widgets/services/cloudflared.md

@@ -3,6 +3,8 @@ 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"]`.

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

@@ -3,6 +3,8 @@ 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.
@@ -16,7 +18,7 @@ widget:
   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:

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
+  passowrd: password
+```

docs/widgets/services/customapi.md

@@ -16,6 +16,8 @@ widget:
   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
@@ -34,10 +36,29 @@ widget:
     - 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
 ```
 
-Supported formats for the values are `text`, `number`, `float`, `percent`, `bytes`, `bitrate` and `date`.
+Supported formats for the values are `text`, `number`, `float`, `percent`, `bytes`, `bitrate`, `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).
 
 ## Example
 
@@ -83,7 +104,7 @@ mappings:
 
 ## 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
@@ -100,7 +121,42 @@ You can manipulate data with the following tools `remap`, `scale` and `suffix`,
   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
@@ -111,3 +167,16 @@ Pass custom headers using the `headers` option, for example:
 headers:
   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,6 +3,8 @@ 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"]`.

docs/widgets/services/diskstation.md

@@ -3,28 +3,35 @@ 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
+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 `Download Station` row, click `Save`.
+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:

docs/widgets/services/downloadstation.md

@@ -3,6 +3,8 @@ 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"]`.

docs/widgets/services/emby.md

@@ -3,6 +3,8 @@ 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.

docs/widgets/services/esphome.md

@@ -0,0 +1,19 @@
+---
+title: ESPHome
+description: ESPHome Widget Configuration
+---
+
+Learn more about [ESPHome](https://esphome.io/).
+
+Show the number of ESPHome devices based on their state.
+
+Allowed fields: `["total", "online", "offline", "offline_alt", "unknown"]` (maximum of 4).
+
+By default ESPHome will only mark devices as `offline` if their address cannot be pinged. If it has an invalid config or its name cannot be resolved (by DNS) its status will be marked as `unknown`.
+To group both `offline` and `unknown` devices together, users should use the `offline_alt` field instead. This sums all devices that are _not_ online together.
+
+```yaml
+widget:
+  type: esphome
+  url: http://esphome.host.or.ip:port
+```

docs/widgets/services/evcc.md

@@ -3,6 +3,8 @@ title: EVCC
 description: EVCC Widget Configuration
 ---
 
+Learn more about [EVSS](https://github.com/evcc-io/evcc).
+
 Allowed fields: `["pv_power", "grid_power", "home_power", "charge_power]`.
 
 ```yaml

docs/widgets/services/fileflows.md

@@ -3,6 +3,8 @@ title: Fileflows
 description: Fileflows Widget Configuration
 ---
 
+Learn more about [FileFlows](https://github.com/revenz/FileFlows).
+
 Allowed fields: `["queue", "processing", "processed", "time"]`.
 
 ```yaml

docs/widgets/services/flood.md

@@ -3,6 +3,8 @@ title: Flood
 description: Flood Widget Configuration
 ---
 
+Learn more about [Flood](https://github.com/jesec/flood).
+
 Allowed fields: `["leech", "download", "seed", "upload"]`.
 
 ```yaml

docs/widgets/services/freshrss.md

@@ -3,6 +3,8 @@ title: FreshRSS
 description: FreshRSS Widget Configuration
 ---
 
+Learn more about [FreshRSS](https://github.com/FreshRSS/FreshRSS).
+
 Please refer to [Enable the API in FreshRSS](https://freshrss.github.io/FreshRSS/en/users/06_Mobile_access.html#enable-the-api-in-freshrss) for the "API password" to be entered in the password field.
 
 Allowed fields: `["subscriptions", "unread"]`.

docs/widgets/services/fritzbox.md

@@ -0,0 +1,22 @@
+---
+title: FRITZ!Box
+description: FRITZ!Box Widget Configuration
+---
+
+Application access & UPnP must be activated on your device:
+
+```
+Home Network > Network > Network Settings > Access Settings in the Home Network
+[x] Allow access for applications
+[x] Transmit status information over UPnP
+```
+
+Credentials are not needed and, as such, you may want to consider using `http` instead of `https` as those requests are significantly faster.
+
+Allowed fields (limited to a max of 4): `["connectionStatus", "uptime", "maxDown", "maxUp", "down", "up", "received", "sent", "externalIPAddress"]`.
+
+```yaml
+widget:
+  type: fritzbox
+  url: http://192.168.178.1
+```

docs/widgets/services/gamedig.md

@@ -3,6 +3,8 @@ title: GameDig
 description: GameDig Widget Configuration
 ---
 
+Learn more about [GameDig](https://github.com/gamedig/node-gamedig).
+
 Uses the [GameDig](https://www.npmjs.com/package/gamedig) library to get game server information for any supported server type.
 
 Allowed fields (limited to a max of 4): `["status", "name", "map", "currentPlayers", "players", "maxPlayers", "bots", "ping"]`.

docs/widgets/services/gatus.md

@@ -0,0 +1,12 @@
+---
+title: Gatus
+description: Gatus Widget Configuration
+---
+
+Allowed fields: `["up", "down", "uptime"]`.
+
+```yaml
+widget:
+  type: gatus
+  url: http://gatus.host.or.ip:port
+```

docs/widgets/services/ghostfolio.md

@@ -3,6 +3,8 @@ title: Ghostfolio
 description: Ghostfolio Widget Configuration
 ---
 
+Learn more about [Ghostfolio](https://github.com/ghostfolio/ghostfolio).
+
 Authentication requires manually obtaining a Bearer token which can be obtained by make a POST request to the API e.g.
 
 ```

docs/widgets/services/gitea.md

@@ -0,0 +1,17 @@
+---
+title: Gitea
+description: Gitea Widget Configuration
+---
+
+Learn more about [Gitea](https://gitea.com).
+
+API token requires `notifications`, `repository` and `issue` permissions. See the [gitea documentation](https://docs.gitea.com/development/api-usage#generating-and-listing-api-tokens) for details on generating tokens.
+
+Allowed fields: `["notifications", "issues", "pulls"]`.
+
+```yaml
+widget:
+  type: gitea
+  url: http://gitea.host.or.ip:port
+  key: giteaapitoken
+```

docs/widgets/services/glances.md

@@ -3,6 +3,8 @@ title: Glances
 description: Glances Widget Configuration
 ---
 
+Learn more about [Glances](https://github.com/nicolargo/glances).
+
 <img width="1614" alt="glances" src="https://github-production-user-asset-6210df.s3.amazonaws.com/82196/257382012-25648c97-2c1b-4db0-b5a5-f1509806079c.png">
 
 _(Find the Glances information widget [here](../info/glances.md))_
@@ -15,7 +17,11 @@ widget:
   url: http://glances.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
   metric: cpu
+  diskUnits: bytes # optional, bytes (default) or bbytes. Only applies to disk
+  refreshInterval: 5000 # optional - in milliseconds, defaults to 1000 or more, depending on the metric
+  pointsLimit: 15 # optional, defaults to 15
 ```
 
 _Please note, this widget does not need an `href`, `icon` or `description` on its parent service. To achieve the same effect as the examples above, see as an example:_

docs/widgets/services/gluetun.md

@@ -3,12 +3,16 @@ title: Gluetun
 description: Gluetun Widget Configuration
 ---
 
-Requires [HTTP control server options](https://github.com/qdm12/gluetun-wiki/blob/main/setup/advanced/control-server.md) to be enabled.
+Learn more about [Gluetun](https://github.com/qdm12/gluetun).
+
+!!! note
+
+    Requires [HTTP control server options](https://github.com/qdm12/gluetun-wiki/blob/main/setup/advanced/control-server.md) to be enabled. By default this runs on port `8000`.
 
 Allowed fields: `["public_ip", "region", "country"]`.
 
 ```yaml
 widget:
   type: gluetun
-  url: http://gluetun.host.or.ip
+  url: http://gluetun.host.or.ip:port
 ```

docs/widgets/services/gotify.md

@@ -3,6 +3,8 @@ title: Gotify
 description: Gotify Widget Configuration
 ---
 
+Learn more about [Gotify](https://github.com/gotify/server).
+
 Get a Gotify client token from an existing client or create a new one on your Gotify admin page.
 
 Allowed fields: `["apps", "clients", "messages"]`.

docs/widgets/services/grafana.md

@@ -3,6 +3,8 @@ title: Grafana
 description: Grafana Widget Configuration
 ---
 
+Learn more about [Grafana](https://github.com/grafana/grafana).
+
 Allowed fields: `["dashboards", "datasources", "totalalerts", "alertstriggered"]`.
 
 ```yaml

docs/widgets/services/hdhomerun.md

@@ -3,10 +3,16 @@ title: HDHomerun
 description: HDHomerun Widget Configuration
 ---
 
-Allowed fields: `["channels", "hd"]`.
+Learn more about [HDHomerun](https://www.silicondust.com/support/downloads/).
+
+Allowed fields: `["channels", "hd", "tunerCount", "channelNumber", "channelNetwork", "signalStrength", "signalQuality", "symbolQuality", "networkRate", "clientIP" ]`.
+
+If more than 4 fields are provided, only the first 4 are displayed.
 
 ```yaml
 widget:
   type: hdhomerun
   url: http://hdhomerun.host.or.ip
+  tuner: 0 # optional - defaults to 0, used for tuner-specific fields
+  fields: ["channels", "hd"] # optional - default fields shown
 ```

docs/widgets/services/healthchecks.md

@@ -3,18 +3,23 @@ title: Health checks
 description: Health checks Widget Configuration
 ---
 
-To use the Health Checks widget, you first need to generate an API key. To do this, follow these steps:
+Learn more about [Health Checks](https://github.com/healthchecks/healthchecks).
 
-1. Go to Settings in your check dashboard.
+Specify a single check by including the `uuid` field or show the total 'up' and 'down' for all
+checks by leaving off the `uuid` field.
+
+To use the Health Checks widget, you first need to generate an API key.
+
+1. In your project, go to project Settings on the navigation bar.
 2. Click on API key (read-only) and then click _Create_.
 3. Copy the API key that is generated for you.
 
-Allowed fields: `["status", "last_ping"]`.
+Allowed fields: `["status", "last_ping"]` for single checks, `["up", "down"]` for total stats.
 
 ```yaml
 widget:
   type: healthchecks
   url: http://healthchecks.host.or.ip:port
   key: <YOUR_API_KEY>
-  uuid: <YOUR_CHECK_UUID>
+  uuid: <CHECK_UUID> # optional, if not included total statistics for all checks is shown
 ```

docs/widgets/services/homeassistant.md

@@ -3,6 +3,8 @@ title: Home Assistant
 description: Home Assistant Widget Configuration
 ---
 
+Learn more about [Home Assistant](https://www.home-assistant.io/).
+
 You will need to generate a long-lived access token for an existing Home Assistant user in its profile.
 
 Allowed fields: `["people_home", "lights_on", "switches_on"]`.
@@ -16,7 +18,7 @@ The `custom` property will have no effect as long as the `fields` property is de
   - state labels and values can be user defined and may reference entity attributes in curly brackets
   - if no state label is defined it will default to `"{attributes.friendly_name}"`
   - if no state value is defined it will default to `"{state} {attributes.unit_of_measurement}"`
-- `template` will query the specified template, see (Home Assistant Templating)[https://www.home-assistant.io/docs/configuration/templating]
+- `template` will query the specified template, see [Home Assistant Templating](https://www.home-assistant.io/docs/configuration/templating)
   - if no template label is defined it will be empty
 
 ```yaml

docs/widgets/services/homebox.md

@@ -0,0 +1,23 @@
+---
+title: Homebox
+description: Homebox Widget Configuration
+---
+
+Learn more about [Homebox](https://github.com/hay-kot/homebox).
+
+Uses the same username and password used to login from the web.
+
+The `totalValue` field will attempt to format using the currency you have configured in Homebox.
+
+Allowed fields: `["items", "totalWithWarranty", "locations", "labels", "users", "totalValue"]`.
+
+If more than 4 fields are provided, only the first 4 are displayed.
+
+```yaml
+widget:
+  type: homebox
+  url: http://homebox.host.or.ip:port
+  username: username
+  password: password
+  fields: ["items", "locations", "totalValue"] # optional - default fields shown
+```

docs/widgets/services/homebridge.md

@@ -3,6 +3,8 @@ title: Homebridge
 description: Homebridge
 ---
 
+Learn more about [Homebridge](https://github.com/homebridge/homebridge).
+
 The Homebridge API is actually provided by the Config UI X plugin that has been included with Homebridge for a while, still it is required to be installed for this widget to work.
 
 Allowed fields: `["updates", "child_bridges"]`.

docs/widgets/services/iframe.md

@@ -27,7 +27,7 @@ widget:
   src: http://example.com
   classes: h-60 sm:h-60 md:h-60 lg:h-60 xl:h-60 2xl:h-72 # optional, use tailwind height classes, see https://tailwindcss.com/docs/height
   referrerPolicy: same-origin # optional, no default
-  allowPolicy: autoplay fullscreen gamepad # optional, no default
+  allowPolicy: autoplay; fullscreen; gamepad # optional, no default
   allowFullscreen: false # optional, default: true
   loadingStrategy: eager # optional, default: eager
   allowScrolling: no # optional, default: yes

docs/widgets/services/immich.md

@@ -3,6 +3,10 @@ title: Immich
 description: Immich Widget Configuration
 ---
 
+Learn more about [Immich](https://github.com/immich-app/immich).
+
+Find your API key under `Account Settings > API Keys`.
+
 Allowed fields: `["users" ,"photos", "videos", "storage"]`.
 
 Note that API key must be from admin user.

docs/widgets/services/jackett.md

@@ -3,7 +3,9 @@ title: Jackett
 description: Jackett Widget Configuration
 ---
 
-Jackett must not have any authentication for the widget to work.
+Learn more about [Jackett](https://github.com/Jackett/Jackett).
+
+If Jackett has an admin password set, you must set the `password` field for the widget to work.
 
 Allowed fields: `["configured", "errored"]`.
 
@@ -11,4 +13,5 @@ Allowed fields: `["configured", "errored"]`.
 widget:
   type: jackett
   url: http://jackett.host.or.ip
+  password: jackettadminpassword # optional
 ```

docs/widgets/services/jdownloader.md

@@ -3,6 +3,8 @@ title: JDownloader
 description: NextPVR Widget Configuration
 ---
 
+Learn more about [JDownloader](https://jdownloader.org/).
+
 Basic widget to show number of items in download queue, along with the queue size and current download speed.
 
 Allowed fields: `["downloadCount", "downloadTotalBytes","downloadBytesRemaining", "downloadSpeed"]`.

docs/widgets/services/jellyfin.md

@@ -3,6 +3,8 @@ title: Jellyfin
 description: Jellyfin Widget Configuration
 ---
 
+Learn more about [Jellyfin](https://github.com/jellyfin/jellyfin).
+
 You can create an API key from inside Jellyfin at `Settings > Advanced > Api Keys`.
 
 As of v0.6.11 the widget supports fields `["movies", "series", "episodes", "songs"]`. These blocks are disabled by default but can be enabled with the `enableBlocks` option, and the "Now Playing" feature (enabled by default) can be disabled with the `enableNowPlaying` option.

docs/widgets/services/jellyseerr.md

@@ -3,6 +3,8 @@ title: Jellyseerr
 description: Jellyseerr Widget Configuration
 ---
 
+Learn more about [Jellyseerr](https://github.com/Fallenbagel/jellyseerr).
+
 Find your API key under `Settings > General > API Key`.
 
 Allowed fields: `["pending", "approved", "available"]`.

docs/widgets/services/kavita.md

@@ -3,7 +3,9 @@ title: Kavita
 description: Kavita Widget Configuration
 ---
 
-Uses the same username and password used to login from the web.
+Learn more about [Kavita](https://github.com/Kareadita/Kavita).
+
+Uses the same admin role username and password used to login from the web.
 
 Allowed fields: `["seriesCount", "totalFiles"]`.
 

docs/widgets/services/komga.md

@@ -3,6 +3,8 @@ title: Komga
 description: Komga Widget Configuration
 ---
 
+Learn more about [Komga](https://github.com/gotson/komga).
+
 Uses the same username and password used to login from the web.
 
 Allowed fields: `["libraries", "series", "books"]`.

docs/widgets/services/kopia.md

@@ -3,6 +3,8 @@ title: Kopia
 description: Kopia Widget Configuration
 ---
 
+Learn more about [Kopia](https://github.com/kopia/kopia).
+
 Allowed fields: `["status", "size", "lastrun", "nextrun"]`.
 
 You may optionally pass values for `snapshotHost` and / or `snapshotPath` to select a specific backup source for the widget.

docs/widgets/services/lidarr.md

@@ -3,6 +3,8 @@ title: Lidarr
 description: Lidarr Widget Configuration
 ---
 
+Learn more about [Lidarr](https://github.com/Lidarr/Lidarr).
+
 Find your API key under `Settings > General`.
 
 Allowed fields: `["wanted", "queued", "artists"]`.

docs/widgets/services/mastodon.md

@@ -3,6 +3,8 @@ title: Mastodon
 description: Mastodon Widget Configuration
 ---
 
+Learn more about [Mastodon](https://github.com/mastodon/mastodon).
+
 Use the base URL of the Mastodon instance you'd like to pull stats for. Does not require authentication as the stats are part of the public API endpoints.
 
 Allowed fields: `["user_count", "status_count", "domain_count"]`.

docs/widgets/services/mealie.md

@@ -3,6 +3,8 @@ title: Mealie
 description: Mealie Widget Configuration
 ---
 
+Learn more about [Mealie](https://github.com/mealie-recipes/mealie).
+
 Generate a user API key under `Profile > Manage Your API Tokens > Generate`.
 
 Allowed fields: `["recipes", "users", "categories", "tags"]`.

docs/widgets/services/medusa.md

@@ -3,6 +3,8 @@ title: Medusa
 description: Medusa Widget Configuration
 ---
 
+Learn more about [Medusa](https://github.com/medusajs/medusa).
+
 Allowed fields: `["wanted", "queued", "series"]`.
 
 ```yaml

docs/widgets/services/miniflux.md

@@ -3,6 +3,8 @@ title: Miniflux
 description: Miniflux Widget Configuration
 ---
 
+Learn more about [Miniflux](https://github.com/miniflux/v2).
+
 Api key is found under Settings > API keys
 
 Allowed fields: `["unread", "read"]`.

docs/widgets/services/moonraker.md

@@ -3,6 +3,8 @@ title: Moonraker (Klipper)
 description: Moonraker (Klipper) Widget Configuration
 ---
 
+Learn more about [Moonraker](https://github.com/Arksine/moonraker).
+
 Allowed fields: `["printer_state", "print_status", "print_progress", "layers"]`.
 
 ```yaml
@@ -10,3 +12,12 @@ widget:
   type: moonraker
   url: http://moonraker.host.or.ip:port
 ```
+
+If your moonraker instance has an active authorization and your homepage ip isn't whitelisted you need to add your api key ([Authorization Documentation](https://moonraker.readthedocs.io/en/latest/web_api/#authorization)).
+
+```yaml
+widget:
+  type: moonraker
+  url: http://moonraker.host.or.ip:port
+  key: api_keymoonraker
+```

docs/widgets/services/mylar.md

@@ -3,6 +3,8 @@ title: Mylar3
 description: Mylar3 Widget Configuration
 ---
 
+Learn more about [Mylar3](https://github.com/mylar3/mylar3).
+
 API must be enabled in Mylar3 settings.
 
 Allowed fields: `["series", "issues", "wanted"]`.

docs/widgets/services/navidrome.md

@@ -3,6 +3,8 @@ title: Navidrome
 description: Navidrome Widget Configuration
 ---
 
+Learn more about [Navidrome](https://github.com/navidrome/navidrome).
+
 For detailed information about how to generate the token see http://www.subsonic.org/pages/api.jsp.
 
 Allowed fields: no configurable fields for this widget.

docs/widgets/services/netalertx.md

@@ -0,0 +1,16 @@
+---
+title: NetAlertX
+description: NetAlertX (formerly PiAlert) Widget Configuration
+---
+
+Learn more about [NetAlertX](https://github.com/jokob-sk/NetAlertX).
+
+_Note that the project was renamed from PiAlert to NetAlertX._
+
+Allowed fields: `["total", "connected", "new_devices", "down_alerts"]`.
+
+```yaml
+widget:
+  type: netalertx
+  url: http://ip:port
+```

docs/widgets/services/netdata.md

@@ -0,0 +1,14 @@
+---
+title: Netdata
+description: Netdata Widget Configuration
+---
+
+Learn more about [Netdata](https://github.com/netdata/netdata).
+
+Allowed fields: `["warnings", "criticals"]`.
+
+```yaml
+widget:
+  type: netdata
+  url: http://netdata.host.or.ip
+```

docs/widgets/services/nextcloud.md

@@ -3,6 +3,8 @@ title: Nextcloud
 description: Nextcloud Widget Configuration
 ---
 
+Learn more about [Nextcloud](https://github.com/nextcloud).
+
 Use username & password, or the `NC-Token` key. Information about the token can be found under **Settings** > **System**. If both are provided, NC-Token will be used.
 
 Allowed fields: `["cpuload", "memoryusage", "freespace", "activeusers", "numfiles", "numshares"]`.

docs/widgets/services/nextdns.md

@@ -3,6 +3,8 @@ title: NextDNS
 description: NextDNS Widget Configuration
 ---
 
+Learn more about [NextDNS](https://nextdns.io/).
+
 Api key is found under Account > API, profile ID is found under Setup > Endpoints > ID
 
 ```yaml

docs/widgets/services/nginx-proxy-manager.md

@@ -3,6 +3,8 @@ title: Nginx Proxy Manager
 description: Nginx Proxy Manager Widget Configuration
 ---
 
+Learn more about [Nginx Proxy Manager](https://nginxproxymanager.com/).
+
 Login with the same admin username and password used to access the web UI.
 
 Allowed fields: `["enabled", "disabled", "total"]`.

docs/widgets/services/nzbget.md

@@ -3,6 +3,8 @@ title: NZBget
 description: NZBget Widget Configuration
 ---
 
+Learn more about [NZBget](https://github.com/nzbget/nzbget).
+
 This widget uses the same authentication method as your browser when logging in (HTTP Basic Auth), and is often referred to as the ControlUsername and ControlPassword inside of Nzbget documentation.
 
 Allowed fields: `["rate", "remaining", "downloaded"]`.

docs/widgets/services/octoprint.md

@@ -3,6 +3,8 @@ title: OctoPrint
 description: OctoPrintWidget Configuration
 ---
 
+Learn more about [OctoPrint](https://octoprint.org/).
+
 Allowed fields: `["printer_state", "temp_tool", "temp_bed", "job_completion"]`.
 
 ```yaml

docs/widgets/services/ombi.md

@@ -3,6 +3,8 @@ title: Ombi
 description: Ombi Widget Configuration
 ---
 
+Learn more about [Ombi](https://github.com/Ombi-app/Ombi).
+
 Find your API key under `Settings > Configuration > General`.
 
 Allowed fields: `["pending", "approved", "available"]`.

docs/widgets/services/opendtu.md

@@ -3,6 +3,8 @@ title: OpenDTU
 description: OpenDTU Widget
 ---
 
+Learn more about [OpenDTU](https://github.com/tbnobody/OpenDTU).
+
 Allowed fields: `["yieldDay", "relativePower", "absolutePower", "limit"]`.
 
 ```yaml

docs/widgets/services/openmediavault.md

@@ -3,6 +3,8 @@ title: OpenMediaVault
 description: OpenMediaVault Widget Configuration
 ---
 
+Learn more about [OpenMediaVault](https://www.openmediavault.org/).
+
 Provides useful information from your OpenMediaVault
 
 ```yaml