feat(config): add custom category slug configuration

Add category-slugs.yaml to support custom slugs for category misc topics
instead of always using auto-generated slugs from category names.
Update build_index.py to use these mappings when generating misc topics,
and document the functionality in README.md. This allows consistent use
of established short slugs like "lightning" for "Lightning Network" category.

README.md

@@ -35,6 +35,13 @@ aliases: # Optional: Alternative names for the topic
 excerpt: "A comprehensive description of the topic."
 ```
 
+## Category Topics
+
+Each category automatically includes a miscellaneous topic that covers content which doesn't fit neatly into other specific topics.
+By default, these topics use slugs generated from the category name (lowercase with hyphens).
+
+For categories that need custom slugs, define them in [category-slugs.yaml](category-slugs.yaml).
+
 ## Usage
 
 ### Building the Index
@@ -49,7 +56,7 @@ This will:
 
 1. Fetch the latest topics from Bitcoin Optech's [/topics.json](https://bitcoinops.org/topics.json).
 2. Combine them with additional topics from the `topics/` directory
-3. Automatically generate miscellaneous topics for each category to support uncategorized content
+3. Generate misc topics for each category using slugs from `category-slugs.yaml` where defined
 4. Generate `topics.json` with the complete topics data
 5. Create `TOPICS.md` with categorized listings
 

category-slugs.yaml

@@ -0,0 +1,4 @@
+"Lightning Network": "lightning"
+"P2P Network Protocol": "p2p"
+"Lightweight Client Support": "lightweight-client"
+"Scripts and Addresses": "scripts-addresses"

scripts/build_index.py

@@ -19,6 +19,15 @@ def __init__(self, optech_topics_url: str, topics_dir: str, root_dir: str):
         self.optech_topics_url = optech_topics_url
         self.topics_dir = topics_dir
         self.root_dir = root_dir
+        self.category_slugs = self.load_category_slugs()
+
+    def load_category_slugs(self) -> Dict[str, str]:
+        """Load category slug mappings from category-slugs.yaml."""
+        slugs_path = os.path.join(self.root_dir, "category-slugs.yaml")
+        if os.path.exists(slugs_path):
+            with open(slugs_path, "r") as f:
+                return yaml.safe_load(f) or {}
+        return {}
 
     def fetch_optech_topics(self) -> List[Dict]:
         """Fetch topics directly from the Bitcoin Optech website."""
@@ -52,12 +61,16 @@ def get_all_categories(self, topics: List[Dict]) -> set:
             categories.update(topic_categories)
         return categories
 
+    def get_category_slug(self, category: str) -> str:
+        """Get the slug for a category, using custom mapping if available."""
+        return self.category_slugs.get(category, category.lower().replace(" ", "-"))
+
     def generate_misc_topics(self, categories: set) -> List[Dict]:
         """Generate miscellaneous topics for each category."""
         misc_topics = []
         for category in categories:
-            # Convert category to slug format
-            slug = category.lower().replace(" ", "-")
+            # Use custom slug if defined, otherwise use default slug format
+            slug = self.get_category_slug(category)
 
             # Create misc topic for the category
             misc_topic = {

topics.json

@@ -900,15 +900,15 @@
   },
   {
     "title": "Lightning Network (Miscellaneous)",
-    "slug": "lightning-network",
+    "slug": "lightning",
     "categories": [
       "Lightning Network"
     ],
     "excerpt": "A catch-all for information related to Lightning Network, covering content that doesn't fit neatly into specific topics."
   },
   {
     "title": "Lightweight Client Support (Miscellaneous)",
-    "slug": "lightweight-client-support",
+    "slug": "lightweight-client",
     "categories": [
       "Lightweight Client Support"
     ],
@@ -1170,7 +1170,7 @@
   },
   {
     "title": "P2P Network Protocol (Miscellaneous)",
-    "slug": "p2p-network-protocol",
+    "slug": "p2p",
     "categories": [
       "P2P Network Protocol"
     ],
@@ -1458,7 +1458,7 @@
   },
   {
     "title": "Scripts and Addresses (Miscellaneous)",
-    "slug": "scripts-and-addresses",
+    "slug": "scripts-addresses",
     "categories": [
       "Scripts and Addresses"
     ],