Guides overhaul

Documentation/.eslintrc.json

@@ -0,0 +1,26 @@
+{
+  "env": {
+    "browser": true,
+    "es2024": true,
+    "node": true
+  },
+  "extends": ["standard", "plugin:@typescript-eslint/recommended"],
+  "parser": "@typescript-eslint/parser",
+  "parserOptions": {
+    "ecmaVersion": 2024,
+    "sourceType": "module"
+  },
+  "plugins": ["@typescript-eslint"],
+  "rules": {
+    "@typescript-eslint/no-explicit-any": "warn",
+    "@typescript-eslint/explicit-function-return-types": "off",
+    "no-unused-vars": "off",
+    "@typescript-eslint/no-unused-vars": [
+      "error",
+      {
+        "argsIgnorePattern": "^_",
+        "varsIgnorePattern": "^_"
+      }
+    ]
+  }
+}

Documentation/.gitignore

@@ -1,6 +1,6 @@
-###############
-#    folder   #
-###############
+##############
+#   folder   #
+##############
 /**/DROP/
 /**/TEMP/
 /**/packages/

Documentation/build-templates.js

@@ -2,7 +2,6 @@
 
 import { build as _build } from "esbuild";
 import { copy } from "esbuild-plugin-copy";
-import { sassPlugin } from "esbuild-sass-plugin";
 import { cpSync, rmSync } from "fs";
 import { join } from "path";
 
@@ -40,10 +39,10 @@ async function buildNetCordTemplate() {
     entryPoints: [
       `${template}/src/docfx.ts`,
       `${template}/src/search-worker.ts`,
+      `${template}/src/json-link-data.ts`,
     ],
     external: ["./main.js"],
     plugins: [
-      sassPlugin(),
       copy({
         assets: {
           from: [`${template}/src/*.js`],
@@ -66,7 +65,12 @@ async function buildNetCordTemplate() {
     loader,
   };
 
-  await _build(config);
+  try {
+    await _build(config);
+  } catch (error) {
+    console.error("Template build failed:", error.message);
+    process.exit(1);
+  }
 }
 
 function copyToDist() {

Documentation/docfx.json

@@ -36,6 +36,9 @@
     "resource": [
       {
         "files": [ "images/**", "favicon.ico", "logo.svg", "robots.txt" ]
+      },
+      {
+        "files": [ "guides/**/BareBones/**", "guides/**/Barebones/**", "guides/**/GenericHosts/**" ]
       }
     ],
     "overwrite": [
@@ -44,6 +47,11 @@
         "exclude": [ "obj/**", "_site/**" ]
       }
     ],
+    "warningLevel": "warn",
+    "lruSize": 1000,
+    "xrefService": [
+      "https://xref.docs.microsoft.com/query?project=dotnet&uid={uid}"
+    ],
     "dest": "_site",
     "template": [ "default", "templates/NetCord" ],
     "markdownEngineName": "markdig",
@@ -58,7 +66,9 @@
       "_enableSearch": true,
       "_disableFooter": true,
       "_noindex": true,
-      "_lang": "en"
+      "_lang": "en",
+      "_jsonLinkData": true,
+      "_canonicalUrlPattern": "https://netcord.dev/{path}"
     },
     "fileMetadata": {
       "_noindex": {
@@ -68,6 +78,8 @@
         "!docs/**": false
       }
     },
-    "xref": [ "https://learn.microsoft.com/en-us/dotnet/.xrefmap.json" ]
+    "xref": [
+      "https://learn.microsoft.com/en-us/dotnet/.xrefmap.json"
+    ]
   }
 }

Documentation/guides/.markdownlint.json

@@ -0,0 +1,32 @@
+{
+  "default": true,
+  "MD003": {
+    "style": "atx"
+  },
+  "MD004": {
+    "style": "dash"
+  },
+  "MD007": {
+    "indent": 2
+  },
+  "MD013": false,
+  "MD024": {
+    "siblings_only": true
+  },
+  "MD025": {
+    "front_matter_title": ""
+  },
+  "MD033": {
+    "allowed_elements": ["antml:function_calls", "antml:invoke", "antml:parameter"]
+  },
+  "MD041": false,
+  "MD046": {
+    "style": "fenced"
+  },
+  "MD049": {
+    "style": "underscore"
+  },
+  "MD050": {
+    "style": "asterisk"
+  }
+}

Documentation/guides/advanced-topics/caching-strategies.md

@@ -0,0 +1,36 @@
+---
+title: Optimizing Discord Bot Performance with Caching Strategies
+description: Implement efficient caching for Discord entities. Learn cache configuration, memory management, and performance optimization in NetCord.
+omitAppTitle: true
+---
+
+# Caching Strategies
+
+> [!NOTE]
+> Content for this section is under development.
+
+## Cache Interface {#cache-interface}
+
+IGatewayClientCache.
+
+## Concurrent vs Immutable {#concurrent-vs-immutable}
+
+ConcurrentGatewayClientCache, ImmutableGatewayClientCache.
+
+## Custom Cache {#custom-cache}
+
+Implementing custom caching.
+
+---
+
+## Navigation
+
+← **Previous:** @"advanced-topics/rate-limiting?text=Rate Limiting" | **Next:** @"advanced-topics/connection-resilience?text=Connection Resilience" →
+
+## See Also
+
+- @"advanced-topics/rate-limiting?text=Rate Limiting" - Cache reduces rate limit hits
+- @"advanced-topics/sharding?text=Sharding" - Cache across shards
+- @"discord-entities/overview?text=Discord Entities" - Entity caching
+- @"dotnet-integration/configuration?text=Configuration" - Cache configuration
+- @"events/intents?text=Intents" - Control cached data

Documentation/guides/advanced-topics/connection-resilience.md

@@ -0,0 +1,36 @@
+---
+title: Building Resilient Discord Bot Connections with NetCord
+description: Handle disconnections and maintain reliable gateway connections. Learn reconnection strategies, session resumption, and connection monitoring.
+omitAppTitle: true
+---
+
+# Connection Resilience
+
+> [!NOTE]
+> Content for this section is under development.
+
+## Reconnect Strategies {#reconnect-strategies}
+
+Built-in strategies.
+
+## Custom Strategy {#custom-strategy}
+
+Implementing custom reconnection logic.
+
+## Disconnect Handling {#disconnect-handling}
+
+Disconnected event.
+
+---
+
+## Navigation
+
+← **Previous:** @"advanced-topics/caching-strategies?text=Caching Strategies" | **Next:** @"migration/index?text=Migration Guide" →
+
+## See Also
+
+- @"dotnet-integration/configuration?text=Configuration" - Configure retry policies
+- @"dotnet-integration/logging?text=Logging" - Log connection events
+- @"events/gateway-events?text=Gateway Events" - Ready and Resumed events
+- @"deployment/docker?text=Docker Deployment" - Container restart policies
+- [Discord Docs: Gateway Lifecycle](https://discord.com/developers/docs/topics/gateway#connections)

Documentation/guides/advanced-topics/rate-limiting.md

@@ -0,0 +1,36 @@
+---
+title: Handling Discord API Rate Limits in NetCord Bots
+description: Manage Discord API rate limits effectively. Learn rate limit handling, bucket strategies, and avoiding 429 errors with NetCord.
+omitAppTitle: true
+---
+
+# Rate Limiting
+
+> [!NOTE]
+> Content for this section is under development.
+
+## Rate Limit Manager {#rate-limit-manager}
+
+IRateLimitManager.
+
+## Handling Rate Limits {#handling-rate-limits}
+
+RestRateLimitHandling.
+
+## Gateway Rate Limits {#gateway-rate-limits}
+
+IRateLimiterProvider.
+
+---
+
+## Navigation
+
+← **Previous:** @"advanced-topics/sharding?text=Sharding" | **Next:** @"advanced-topics/caching-strategies?text=Caching Strategies" →
+
+## See Also
+
+- @"advanced-topics/caching-strategies?text=Caching Strategies" - Reduce API calls
+- @"webhooks/managing-webhooks?text=Managing Webhooks" - Webhook rate limits
+- @"services-framework/preconditions?text=Preconditions" - Command cooldowns
+- @"troubleshooting/common-issues?text=Common Issues" - Rate limit errors
+- [Discord Docs: Rate Limits](https://discord.com/developers/docs/topics/rate-limits)

Documentation/guides/advanced-topics/sharding.md

@@ -0,0 +1,40 @@
+---
+title: Scaling Discord Bots with Sharding in NetCord
+description: Scale large Discord bots across multiple shards. Learn shard management, data synchronization, and multi-shard architecture with NetCord.
+omitAppTitle: true
+---
+
+# Sharding
+
+> [!NOTE]
+> Content for this section is under development.
+
+## Why Sharding {#why-sharding}
+
+When you need it (2500+ guilds).
+
+## Sharded Client {#sharded-client}
+
+ShardedGatewayClient.
+
+## Shard Configuration {#shard-configuration}
+
+Shard count and shard IDs.
+
+## Hosting Integration {#hosting-integration}
+
+UseShardedDiscordGateway.
+
+---
+
+## Navigation
+
+← **Previous:** @"deployment/cloud-hosting?text=Cloud Hosting" | **Next:** @"advanced-topics/rate-limiting?text=Rate Limiting" →
+
+## See Also
+
+- @"advanced-topics/caching-strategies?text=Caching Strategies" - Cache across shards
+- @"advanced-topics/connection-resilience?text=Connection Resilience" - Shard reconnection
+- @"deployment/cloud-hosting?text=Cloud Hosting" - Deploy sharded bots
+- @"dotnet-integration/generic-host?text=Generic Host" - Configure sharding
+- [Discord Docs: Sharding](https://discord.com/developers/docs/topics/gateway#sharding)