MKDocs

2025-12-06 17:15:38 -08:00 · 2025-02-09 12:01:02 +11:00
parent f793dec6c5
commit c6adaf99f4
14 changed files with 104 additions and 40 deletions
--- a/.github/ISSUE_TEMPLATE/feature_request.yml
+++ b/.github/ISSUE_TEMPLATE/feature_request.yml
@@ -46,7 +46,7 @@ body:
 - type: checkboxes
  attributes:
    label: Can I help implement this? 👩‍💻👨‍💻 
-    description: The maintainer will provide guidance and help. The implementer will read the PR guidelines https://github.com/jokob-sk/NetAlertX/tree/main/docs#-pull-requests-prs
+    description: The maintainer will provide guidance and help. The implementer will read the PR guidelines https://jokob-sk.github.io/NetAlertX/DEV_ENV_SETUP/
    options:
    - label: "Yes"
    - label: "No"
--- a/.github/ISSUE_TEMPLATE/i-have-an-issue.yml
+++ b/.github/ISSUE_TEMPLATE/i-have-an-issue.yml
@@ -7,7 +7,7 @@ body:
    label: Is there an existing issue for this?
    description: Please search to see if an open or closed issue already exists for the bug you encountered.
    options:
-    - label: I have searched the existing open and closed issues and I checked the docs https://github.com/jokob-sk/NetAlertX/tree/main/docs
+    - label: I have searched the existing open and closed issues and I checked the docs https://jokob-sk.github.io/NetAlertX/
      required: true
 - type: checkboxes
  attributes:
--- a/README.md
+++ b/README.md
@@ -9,7 +9,7 @@
 Get visibility of what's going on on your WIFI/LAN network and enable presence detection of important devices. Schedule scans for devices, port changes and get alerts if unknown devices or changes are found. Write your own [Plugins](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins#readme) with auto-generated UI and in-build notification system. Build out and easily maintain your network source of truth (NSoT).


-| [📑 Docker guide](https://github.com/jokob-sk/NetAlertX/blob/main/dockerfiles/README.md) | [🚀 Releases](https://github.com/jokob-sk/NetAlertX/releases) | [📚 Docs](https://github.com/jokob-sk/NetAlertX/tree/main/docs) | [🔌 Plugins](https://github.com/jokob-sk/NetAlertX/blob/main/front/plugins/README.md) | [🤖 Ask AI](https://gurubase.io/g/netalertx)
+| [📑 Docker guide](https://github.com/jokob-sk/NetAlertX/blob/main/dockerfiles/README.md) | [🚀 Releases](https://github.com/jokob-sk/NetAlertX/releases) | [📚 Docs](https://jokob-sk.github.io/NetAlertX/) | [🔌 Plugins](https://github.com/jokob-sk/NetAlertX/blob/main/front/plugins/README.md) | [🤖 Ask AI](https://gurubase.io/g/netalertx)
 |----------------------| ----------------------|  ----------------------| ----------------------| ----------------------| 

 ![showcase][showcase] 
--- a/dockerfiles/README.md
+++ b/dockerfiles/README.md
@@ -6,7 +6,7 @@

 # NetAlertX - Network scanner & notification framework

-| [📑 Docker guide](https://github.com/jokob-sk/NetAlertX/blob/main/dockerfiles/README.md) | [🚀 Releases](https://github.com/jokob-sk/NetAlertX/releases) | [📚 Docs](https://github.com/jokob-sk/NetAlertX/tree/main/docs) | [🔌 Plugins](https://github.com/jokob-sk/NetAlertX/blob/main/front/plugins/README.md) | [🤖 Ask AI](https://gurubase.io/g/netalertx)
+| [📑 Docker guide](https://github.com/jokob-sk/NetAlertX/blob/main/dockerfiles/README.md) | [🚀 Releases](https://github.com/jokob-sk/NetAlertX/releases) | [📚 Docs](https://jokob-sk.github.io/NetAlertX/) | [🔌 Plugins](https://github.com/jokob-sk/NetAlertX/blob/main/front/plugins/README.md) | [🤖 Ask AI](https://gurubase.io/g/netalertx)
 |----------------------| ----------------------|  ----------------------| ----------------------| ----------------------| 

 <a href="https://raw.githubusercontent.com/jokob-sk/NetAlertX/main/docs/img/GENERAL/github_social_image.jpg" target="_blank">
--- a/docs/DEV_ENV_SETUP.md
+++ b/docs/DEV_ENV_SETUP.md
@@ -97,7 +97,7 @@ Most code changes can be tetsed without rebuilding the container. When working o
 ✔ New features are **reusable**, not narrowly scoped.  
 ✔ Features are implemented via **plugins** if possible.  

-### ✅ Suggested Test Cases
+### Mandatory Test Cases

 - Fresh install (no DB/config).
 - Existing DB/config compatibility.
@@ -108,7 +108,7 @@ Most code changes can be tetsed without rebuilding the container. When working o
    - Webhook (e.g., Discord)  
    - MQTT (e.g., Home Assistant)  

- Settings persistence.
+- Updating Settings and their persistence.
 - Updating a Device
 - Plugin functionality.
 - Error log inspection.
--- a/docs/FRONTEND_DEVELOPMENT.md
+++ b/docs/FRONTEND_DEVELOPMENT.md
@@ -1,4 +1,4 @@
-# 🖼 Frontend development 
+# Frontend development 

 This page contains tips for frontend development when extending NetAlertX. Guiding principles are:

--- a/docs/INITIAL_SETUP.md
+++ b/docs/INITIAL_SETUP.md
@@ -36,5 +36,7 @@
 ## 🛠️ Common Issues

 Before creating a new issue:
+
 - Check if a similar issue was [already resolved](https://github.com/jokob-sk/NetAlertX/issues?q=is%3Aissue+is%3Aclosed).
 - Review [common debugging tips](./DEBUG_TIPS.md).
+- Check [Common Issues](./COMMON_ISSUES.md)
--- a/docs/INSTALLATION.md
+++ b/docs/INSTALLATION.md
@@ -1,4 +1,6 @@
-# Installation options
+# Installation
+
+## Installation options

 NetAlertX can be installed several ways. The best supported option is Docker, followed by a supervised the Home Assistant instance, as an Unraid app and lastly on bare metal. 

@@ -7,6 +9,9 @@ NetAlertX can be installed several ways. The best supported option is Docker, fo
 - [[Installation] Unraid App](https://unraid.net/community/apps) 
 - [[Installation] Bare metal (experimental - looking for maintainers)](https://github.com/jokob-sk/NetAlertX/blob/main/docs/HW_INSTALL.md) 

+
+## Help
+
 If facing issues, please spend a few minutes seraching. 

 - Check [common issues](./COMMON_ISSUES.md)
@@ -16,3 +21,5 @@ If facing issues, please spend a few minutes seraching.

 > [!NOTE]
 > If you can't find a solution anywhere, ask in Discord if you think it's a quick question, otherwise open a new [issue](https://github.com/jokob-sk/NetAlertX/issues/new?template=setup-help.yml). Please fill in as much as possible to speed up the help process. 
+>
+
--- a/docs/PLUGINS_DEV.md
+++ b/docs/PLUGINS_DEV.md
@@ -776,8 +776,8 @@ The UI will adjust how columns are displayed in the UI based on the resolvers de
        }
 ```

-[screen1]: https://raw.githubusercontent.com/jokob-sk/NetAlertX/main./img/plugins.png                    "Screen 1"
-[screen2]: https://raw.githubusercontent.com/jokob-sk/NetAlertX/main./img/plugins_settings.png           "Screen 2"
-[screen3]: https://raw.githubusercontent.com/jokob-sk/NetAlertX/main./img/plugins_json_settings.png      "Screen 3"
-[screen4]: https://raw.githubusercontent.com/jokob-sk/NetAlertX/main./img/plugins_json_ui.png            "Screen 4"
-[screen5]: https://raw.githubusercontent.com/jokob-sk/NetAlertX/main./img/plugins_device_details.png     "Screen 5"
+[screen1]: https://raw.githubusercontent.com/jokob-sk/NetAlertX/main/docs/img/plugins.png                    "Screen 1"
+[screen2]: https://raw.githubusercontent.com/jokob-sk/NetAlertX/main/docs/img/plugins_settings.png           "Screen 2"
+[screen3]: https://raw.githubusercontent.com/jokob-sk/NetAlertX/main/docs/img/plugins_json_settings.png      "Screen 3"
+[screen4]: https://raw.githubusercontent.com/jokob-sk/NetAlertX/main/docs/img/plugins_json_ui.png            "Screen 4"
+[screen5]: https://raw.githubusercontent.com/jokob-sk/NetAlertX/main/docs/img/plugins_device_details.png     "Screen 5"
--- a/docs/SETTINGS_SYSTEM.md
+++ b/docs/SETTINGS_SYSTEM.md
@@ -74,4 +74,4 @@ Here's a high-level description of the code:

 _____________________

-[screen1]: https://raw.githubusercontent.com/jokob-sk/NetAlertX/main./img/plugins_json_settings.png      "Screen 1"
+[screen1]: https://raw.githubusercontent.com/jokob-sk/NetAlertX/main/docs/img/plugins_json_settings.png      "Screen 1"
--- a/docs/img/NetAlertX_logo.png
+++ b/docs/img/NetAlertX_logo.png
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,31 +1,80 @@
-# NetAlertX documentation
+# NetAlertX Documentation

-## ℹ️ In-App Help
+Welcome to the official NetAlertX documentation! NetAlertX is a powerful tool designed to simplify the management and monitoring of your network. Below, you will find guides and resources to help you set up, configure, and troubleshoot your NetAlertX instance.

- Hover over settings, fields, or labels.
- Click the blue ❔ (question-mark) icons.
- Access the in-app **Help / FAQ** section for frequently asked questions.
+## In-App Help
+
+NetAlertX provides contextual help within the application:
+
+- **Hover over settings, fields, or labels** to see additional tooltips and guidance.
+- **Click the blue ❔ (question-mark) icons** next to various elements to view detailed information.
+- Access the in-app **Help / FAQ** section for frequently asked questions and quick answers.

 ---

-## Installation
+## Installation Guides

 ### Docker (Fully Supported)

- [Follow the official installation guide](https://github.com/jokob-sk/NetAlertX/blob/main/dockerfiles/README.md).
+NetAlertX is fully supported in Docker environments, allowing for easy setup and configuration. Follow the official guide to get started:

-### Bare-Metal 
+- [Docker Installation Guide](https://github.com/jokob-sk/NetAlertX/blob/main/dockerfiles/README.md)

- 🧪 [(Experimental) On-hardware installation](./HW_INSTALL.md) (looking for maintainers)  
+This guide will take you through the process of setting up NetAlertX using Docker Compose or standalone Docker commands.
+
+### Bare-Metal Installation (Experimental)
+
+If you prefer to run NetAlertX on your own hardware, you can try the experimental bare-metal installation. Please note that this method is still under development, and we're looking for maintainers to help improve it.
+
+- [Bare-Metal Installation Guide](./HW_INSTALL.md)

 ---

 ## Help and Support

-Before opening an issue:
+If you need help or run into issues, here are some resources to guide you:

- 🔍 [Check common issues](./DEBUG_TIPS.md#common-issues).
- 📌 [Look at closed issues](https://github.com/jokob-sk/NetAlertX/issues?q=is%3Aissue+is%3Aclosed).
- ⚠ **Enable debugging** before reporting: [Debug Guide](./DEBUG_TIPS.md).
+**Before opening an issue, please:**

-❗ **Follow the issue template** for faster resolution.
+  - [Check common issues](./DEBUG_TIPS.md#common-issues) to see if your problem has already been reported.
+  - [Look at closed issues](https://github.com/jokob-sk/NetAlertX/issues?q=is%3Aissue+is%3Aclosed) for possible solutions to past problems.
+  - **Enable debugging** to gather more information: [Debug Guide](./DEBUG_TIPS.md).
+  
+**Need more help?** Join the community discussions or submit a support request:
+
+  - Visit the [GitHub Discussions](https://github.com/jokob-sk/NetAlertX/discussions) for community support.
+  - If you are experiencing issues that require immediate attention, consider opening an issue on our [GitHub Issues page](https://github.com/jokob-sk/NetAlertX/issues).
+
+---
+
+## Contributing
+
+NetAlertX is open-source and welcomes contributions from the community! If you'd like to help improve the software, please follow the guidelines below:
+
+- **Fork the repository** and make your changes.
+- **Submit a pull request** with a detailed description of what you’ve changed and why.
+
+For more information on contributing, check out our [Dev Guide](./DEV_ENV_SETUP.md).
+
+---
+
+## Stay Updated
+
+To keep up with the latest changes and updates to NetAlertX, please refer to the following resources:
+
+- [Releases](https://github.com/jokob-sk/NetAlertX/releases)
+
+Make sure to follow the project on GitHub to get notifications for new releases and important updates.
+
+---
+
+## Additional Resources
+
+- **Configuration Tips**: Learn how to optimize NetAlertX for your network setup.
+- **Advanced Features**: Explore advanced functionalities like plugin development and custom configurations.
+- **Documentation Index**: Check out the full [documentation index](https://github.com/jokob-sk/NetAlertX/tree/main/docs) for all the guides available.
+
+We hope you find this documentation helpful. If you have any suggestions or improvements, please don’t hesitate to contribute!
+
+---
+NetAlertX is actively maintained. You can find the source code, report bugs, or request new features on our [GitHub page](https://github.com/jokob-sk/NetAlertX).
--- a/front/php/templates/footer.php
+++ b/front/php/templates/footer.php
@@ -29,7 +29,7 @@
    <!-- To the right -->
    <div class="pull-right no-hidden-xs">
      | <a href="https://gurubase.io/g/netalertx" class="pointer" target="_blank" title="Ask AI"><i class="fa-regular fa-comment-dots fa-flip-horizontal"></i></a> 
-      | <a href="https://github.com/jokob-sk/NetAlertX/tree/main/docs#documentation-overview" class="pointer" target="_blank" title="Documentation"><i class="fa fa-book"></i></a>
+      | <a href="https://jokob-sk.github.io/NetAlertX/" class="pointer" target="_blank" title="Documentation"><i class="fa fa-book"></i></a>
      | <a href="https://github.com/jokob-sk/NetAlertX/issues" class="pointer" target="_blank"><i class="fa-solid fa-bug" title="Report a bug"></i></a> 
      | <a href="https://discord.com/invite/NczTUTWyRr" class="pointer" target="_blank"><i class="fa-brands fa-discord" title="Join Discord"></i></a> 
      | <?= lang('Maintenance_built_on');?>:  <?php include 'php/templates/build.php'; ?> 
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -2,11 +2,14 @@ site_name: NetAlertX Docs
 site_url: https://jokob-sk.github.io/NetAlertX/
 repo_url: https://github.com/jokob-sk/NetAlertX/
 edit_uri: blob/main/docs/
-static_dir: docs/img
+docs_dir: docs
+# static_dir: docs/img
 nav:
  - Home: index.md
+
  - Installation: 
      - Installation options: INSTALLATION.md
+      - Quick setup: INITIAL_SETUP.md
      - Docker Guide: https://github.com/jokob-sk/NetAlertX/blob/main/dockerfiles/README.md    
      - Docker Compose: DOCKER_COMPOSE.md
      - Docker File Permissions: FILE_PERMISSIONS.md
@@ -15,8 +18,10 @@ nav:
      - Bare-metal (Experimental): HW_INSTALL.md
      - Migration Guide: MIGRATION.md
      - Common issues: COMMON_ISSUES.md
+      - Docker Updates: UPDATES.md
  - Setup:
      - Subnets: SUBNETS.md
+      - Enable Plugins: https://github.com/jokob-sk/NetAlertX/blob/main/front/plugins/README.md  
      - Common issues: COMMON_ISSUES.md
      - Remote Networks: REMOTE_NETWORKS.md      
      - Notifications Guide: NOTIFICATIONS.md
@@ -51,12 +56,15 @@ nav:
      - API: API.md
      - Database: DATABASE.md
      - Settings: SETTINGS_SYSTEM.md
-      - Updates: UPDATES.md
      - Versions: VERSIONS.md


 theme:
  name: material
+  logo: img/NetAlertX_logo.png  # Reference the favicon here
+  favicon: img/NetAlertX_logo.png
+  extra:
+    home_hide_sidebar: true
  features:
    - announce.dismiss
    - content.action.edit
@@ -103,7 +111,5 @@ markdown_extensions:
 plugins:
  - gh-admonitions
  - search
-font:
-  text: Roboto
-  code: Roboto Mono
-  favicon: https://raw.githubusercontent.com/jokob-sk/NetAlertX/main/front/img/NetAlertX_logo.png
+
+favicon: /img/NetAlertX_logo.png