docs: Update examples to reflect real-world usage patterns

andrzejnovak · claude · andrzejnovak · commit cb7ad86dde40 · 2025-11-12T21:46:21.000+01:00
Updated all code examples in README and documentation to use more realistic scenarios: - Replaced generic examples with practical use cases - Added clear organizational vs standalone project patterns - Included proper comments in YAML examples - Used realistic project names and URLs (your-org/your-project) - Emphasized shared config approach for organizations - Added step-by-step guides for common workflows - Made nested dropdown examples more comprehensive This makes it easier for new users to understand how to apply the plugin to their specific use case. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
diff --git a/README.md b/README.md
@@ -16,23 +16,47 @@ pip install -e /path/to/mkdocs_header_dropdown
 pip install git+https://github.com/cms-cat/mkdocs-header-dropdown.git
 ```
 
-## Configuration
+## Quick Start
 
-Add the plugin to your `mkdocs.yml` configuration file:
+### Option 1: Using a Shared Config (Recommended for Organizations)
+
+If you're part of an organization with shared documentation links:
+
+```bash
+# Add the shared config as a git submodule
+git submodule add https://github.com/your-org/docs-common.git
+```
 
 ```yaml
+# mkdocs.yml
+plugins:
+  - search
+  - header-dropdown:
+      config_file: "docs-common/header-dropdown.yml"
+```
+
+### Option 2: Direct Configuration
+
+For standalone projects:
+
+```yaml
+# mkdocs.yml
 plugins:
   - search
   - header-dropdown:
       dropdowns:
-        - title: "CMS POG Docs"
-          icon: "/assets/CMSlogo_white_nolabel_1024_May2014.png"
+        - title: "Documentation"
           links:
-            - text: "Analysis Corrections | CrossPOG"
-              url: "https://cms-analysis-corrections.docs.cern.ch/"
-              target: "_blank"
-            - text: "BTV Docs"
-              url: "https://btv-wiki.docs.cern.ch/"
+            - text: "Getting Started"
+              url: "/getting-started/"
+            - text: "User Guide"
+              url: "/guide/"
+            - text: "API Reference"
+              url: "/api/"
+        - title: "External Links"
+          links:
+            - text: "GitHub Repository"
+              url: "https://github.com/your-org/your-project"
               target: "_blank"
 ```
 
diff --git a/example/docs/getting-started.md b/example/docs/getting-started.md
@@ -15,61 +15,97 @@ pip install git+https://github.com/cms-cat/mkdocs-header-dropdown-plugin.git
 The minimal configuration requires just the plugin and at least one dropdown:
 
 ```yaml
+# mkdocs.yml
 plugins:
+  - search
   - header-dropdown:
       dropdowns:
-        - title: "Links"
+        - title: "Documentation"
           links:
             - text: "Home"
               url: "/"
+            - text: "Getting Started"
+              url: "/getting-started/"
 ```
 
 ## Adding Icons
 
-You can add icons to your dropdowns:
+You can add icons to your dropdowns. The icon path should be relative to your docs directory:
 
 ```yaml
+# mkdocs.yml
 plugins:
   - header-dropdown:
       dropdowns:
-        - title: "Documentation"
-          icon: "/assets/logo.png"
+        - title: "My Project"
+          icon: "/assets/logo.png"  # Located at docs/assets/logo.png
           links:
-            - text: "Getting Started"
-              url: "/getting-started/"
+            - text: "Home"
+              url: "/"
+            - text: "Documentation"
+              url: "/docs/"
 ```
 
 ## Multiple Dropdowns
 
 Add as many dropdowns as you need:
 
 ```yaml
+# mkdocs.yml
 plugins:
   - header-dropdown:
       dropdowns:
-        - title: "Docs"
+        - title: "Documentation"
           links:
-            - text: "Guide"
+            - text: "User Guide"
               url: "/guide/"
-        - title: "External"
+            - text: "API Reference"
+              url: "/api/"
+            - text: "Examples"
+              url: "/examples/"
+        - title: "Resources"
           links:
-            - text: "GitHub"
-              url: "https://github.com"
+            - text: "GitHub Repository"
+              url: "https://github.com/your-org/your-project"
+              target: "_blank"
+            - text: "Issue Tracker"
+              url: "https://github.com/your-org/your-project/issues"
               target: "_blank"
 ```
 
 ## Using Shared Configuration
 
 For multiple documentation sites sharing the same navigation:
 
-1. Create a shared config repository
-2. Add as git submodule
-3. Reference in `mkdocs.yml`:
+**Step 1:** Create a shared config repository (`your-org/docs-common`):
 
 ```yaml
+# header-dropdown.yml
+dropdowns:
+  - title: "Company Resources"
+    icon: "company-logo.png"
+    links:
+      - text: "Internal Wiki"
+        url: "https://wiki.company.com"
+        target: "_blank"
+      - text: "Support Portal"
+        url: "https://support.company.com"
+        target: "_blank"
+```
+
+**Step 2:** Add as git submodule to your documentation repo:
+
+```bash
+git submodule add https://github.com/your-org/docs-common.git
+```
+
+**Step 3:** Reference in `mkdocs.yml`:
+
+```yaml
+# mkdocs.yml
 plugins:
   - header-dropdown:
-      config_file: "shared-config/dropdowns.yml"
+      config_file: "docs-common/header-dropdown.yml"
 ```
 
 **Live Example**: The "CMS POG Docs" dropdown in this site's header is loaded from the [cms-docs-common](https://github.com/cms-cat/cms-docs-common) repository via git submodule!
@@ -79,44 +115,59 @@ plugins:
 You can combine shared config with site-specific dropdowns:
 
 ```yaml
+# mkdocs.yml
 plugins:
   - header-dropdown:
-      config_file: "cms-docs-common/header-dropdown.yml"  # Shared
-      dropdowns:  # Site-specific
-        - title: "Local Links"
+      config_file: "docs-common/header-dropdown.yml"  # Shared organization links
+      dropdowns:  # Project-specific additions
+        - title: "This Project"
           links:
             - text: "About"
               url: "/about/"
+            - text: "Changelog"
+              url: "/changelog/"
+            - text: "Contributing"
+              url: "/contributing/"
 ```
 
-Both will appear in the header - check this example site to see it in action!
+Both shared and project-specific dropdowns will appear in the header - check this example site to see it in action!
 
 ## Nested Dropdowns
 
 You can create nested dropdowns (submenus) by using the `submenu` key instead of `url`:
 
 ```yaml
+# mkdocs.yml
 plugins:
   - header-dropdown:
       dropdowns:
         - title: "Resources"
           links:
-            - text: "GitHub"
-              url: "https://github.com/example"
-            - text: "Documentation"  # This will have an arrow
+            - text: "GitHub Repository"
+              url: "https://github.com/your-org/your-project"
+              target: "_blank"
+            - text: "Documentation"  # This will have an arrow →
               submenu:
                 - text: "User Guide"
                   url: "/guide/"
                 - text: "API Reference"
                   url: "/api/"
-                - text: "FAQ"
-                  url: "/faq/"
+                - text: "Tutorials"
+                  url: "/tutorials/"
+            - text: "Community"  # Another nested menu
+              submenu:
+                - text: "Forum"
+                  url: "https://forum.example.com"
+                  target: "_blank"
+                - text: "Chat"
+                  url: "https://chat.example.com"
+                  target: "_blank"
 ```
 
-**Live Example**: Hover over the "Resources" dropdown and then hover over "Documentation" to see a nested submenu appear to the right!
+**Live Example**: Hover over the "Resources" dropdown in this site's header, then hover over "Documentation" to see a nested submenu appear to the right!
 
 Features:
-- Arrow indicator (▶) shows which items have submenus
-- Submenus appear on hover to the right
+- **Arrow indicator** (▶) shows which items have submenus
+- **Submenus appear on hover** to the right
 - Works with both mouse and keyboard navigation
 - Multiple levels of nesting supported
diff --git a/example/docs/index.md b/example/docs/index.md
@@ -37,16 +37,32 @@ pip install git+https://github.com/cms-cat/mkdocs-header-dropdown-plugin.git
 
 ## Quick Start
 
-Add to your `mkdocs.yml`:
+**For organizations with shared links (using git submodules):**
+
+```bash
+git submodule add https://github.com/your-org/docs-common.git
+```
+
+```yaml
+# mkdocs.yml
+plugins:
+  - header-dropdown:
+      config_file: "docs-common/header-dropdown.yml"
+```
+
+**For standalone projects:**
 
 ```yaml
+# mkdocs.yml
 plugins:
   - header-dropdown:
       dropdowns:
         - title: "Documentation"
           links:
+            - text: "Getting Started"
+              url: "/getting-started/"
             - text: "User Guide"
-              url: "/user-guide/"
+              url: "/guide/"
             - text: "API Reference"
               url: "/api/"
 ```
