[DRAFT] docs

.cursor/commands/documentation/docs-serve.md

@@ -113,48 +113,47 @@ Start and manage a local documentation server to preview documentation changes,
 ## Server Configuration
 
 ### Default Settings
+
 - **Port**: 8000 (configurable)
 - **Host**: localhost (127.0.0.1)
 - **Auto-reload**: Enabled
 - **Live-reload**: Browser refresh on file changes
 - **Watch**: All documentation source files
 
 ### Custom Configuration
-- **Port**: Use `--port` flag to specify different port
-- **Host**: Use `--host` flag for different host binding
-- **No-reload**: Use `--no-reload` to disable auto-reload
-- **Verbose**: Use `--verbose` for detailed logging
 
-### Environment Variables
-- `DOCS_PORT`: Override default port
-- `DOCS_HOST`: Override default host
-- `DOCS_RELOAD`: Enable/disable auto-reload
-- `DOCS_OPEN`: Auto-open browser on start
+- **Dev Address**: Use `--dev-addr` (or `-a`) flag to specify IP address and port (format: `host:port`, default: `localhost:8000`)
+- **Open Browser**: Use `--open` (or `-o`) flag to automatically open browser on start
+- **Strict Mode**: Use `--strict` (or `-s`) flag for strict mode (not yet supported by zensical)
 
 ## Testing Scenarios
 
 ### New Content Testing
+
 1. Add new documentation page
 2. Verify it appears in navigation
 3. Test all links to and from the page
 4. Check formatting and styling
 5. Verify search includes new content
 
 ### Content Updates Testing
+
 1. Modify existing documentation
 2. Verify changes appear immediately
 3. Check that formatting is preserved
 4. Test updated examples and code
 5. Verify cross-references still work
 
 ### Asset Testing
+
 1. Add new images or media files
 2. Verify they display correctly
 3. Check different image formats
 4. Test responsive image behavior
 5. Verify alt text and accessibility
 
 ### Configuration Testing
+
 1. Modify site configuration
 2. Restart server to apply changes
 3. Verify configuration takes effect
@@ -164,34 +163,39 @@ Start and manage a local documentation server to preview documentation changes,
 ## Troubleshooting
 
 ### Server Won't Start
+
 - Check if port is already in use
 - Verify documentation builds successfully
 - Check for missing dependencies
-- Try different port with `--port` flag
+- Try different port with `--dev-addr` flag (e.g., `--dev-addr localhost:3000`)
 - Check file permissions
 
 ### Pages Don't Load
+
 - Verify build completed successfully
 - Check for broken internal links
 - Verify file paths are correct
 - Check for case sensitivity issues
 - Clear browser cache
 
 ### Auto-Reload Not Working
+
 - Check file system permissions
 - Verify watch functionality is enabled
 - Try restarting the server
 - Check for file system limitations
 - Use manual refresh as fallback
 
 ### Styling Issues
+
 - Clear browser cache and reload
 - Check for CSS build errors
 - Verify static assets are loading
 - Check browser developer tools
 - Try different browser
 
 ### Search Not Working
+
 - Verify search index is built
 - Check for JavaScript errors
 - Clear browser cache
@@ -219,6 +223,7 @@ Start and manage a local documentation server to preview documentation changes,
 ## Examples
 
 ### Basic Server Start
+
 ```bash
 uv run docs serve
 # Server starts on http://localhost:8000
@@ -227,21 +232,24 @@ uv run docs serve
 ```
 
 ### Custom Port and Host
+
 ```bash
-uv run docs serve --port 3000 --host 0.0.0.0
+uv run docs serve --dev-addr 0.0.0.0:3000
 # Server accessible on all network interfaces
 # Custom port for avoiding conflicts
 ```
 
-### Development Mode
+### Development Mode with Auto-Open
+
 ```bash
-uv run docs serve --verbose --no-cache
-# Detailed logging enabled
-# Cache disabled for development
+uv run docs serve --open
+# Automatically opens browser on start
+# Live reload enabled by default
 # Immediate reflection of changes
 ```
 
 ### Testing Workflow
+
 1. Start server: `uv run docs serve`
 2. Open browser to `http://localhost:8000`
 3. Navigate through documentation
@@ -256,13 +264,12 @@ uv run docs serve --verbose --no-cache
 - Related rule: @docs/docs.mdc - Documentation standards and patterns
 - Related command: `/update-docs` - Update existing documentation
 - Related command: `/generate-docs` - Generate new documentation
-- Related guide: [Documentation Development Guide](../../../docs/content/developer/guides/documentation-development.md)
 
 ## Additional Notes
 
 - **Development**: Use serve command during active documentation development
 - **Testing**: Always test documentation locally before committing changes
 - **Performance**: Monitor server performance with large documentation sites
-- **Collaboration**: Share local server URL for team review (use `--host 0.0.0.0`)
+- **Collaboration**: Share local server URL for team review (use `--dev-addr 0.0.0.0:8000`)
 - **Automation**: Consider integrating serve command into development workflows
-- **Debugging**: Use verbose mode and browser developer tools for troubleshooting
+- **Debugging**: Use browser developer tools and server console output for troubleshooting

.cursor/rules/docs/style.mdc

@@ -34,6 +34,20 @@ This section covers the core writing principles, style guidelines, and formattin
 - **UI Elements**: Format as they appear: **Submit**, **User settings**
 - **Bold Keywords**: Use `**bold**` for emphasis, `_italics_` sparingly
 - **Lists**: Complete sentences, dashes for unordered, bold keywords with colons
+- **Nested Lists**: When a numbered list item with bold text is followed by a nested bullet list, include a blank line between the bold text and the nested list for proper rendering:
+
+  ```markdown
+  ✅ Correct:
+  1. **Item title**
+
+     - Nested bullet item
+     - Another nested item
+
+  ❌ Incorrect:
+  1. **Item title**
+     - Nested bullet item
+     - Another nested item
+  ```
 
 ### Code Documentation
 

.markdownlint.yaml

@@ -90,7 +90,7 @@ MD023: true
 # MD024/no-duplicate-heading : Multiple headings with the same content : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md024.md
 MD024:
   # Only check sibling headings
-  siblings_only: false
+  siblings_only: true
 # MD025/single-title/single-h1 : Multiple top-level headings in the same document : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md025.md
 MD025:
   # Heading level

.vscode/settings.json

@@ -115,7 +115,7 @@
     "tag:yaml.org,2002:python/object/apply:pymdownx.slugs.slugify mapping",
     "tag:yaml.org,2002:python/name:material.plugins.tags.tag_name_casefold"
   ],
-  "markdown.validate.enabled": true,
+  "markdown.validate.enabled": false,
   "editor.wordWrap": "off",
   "editor.tabSize": 4,
   "editor.detectIndentation": false,

docs/content/admin/config/roles.md

@@ -56,13 +56,13 @@ You can also manage role assignments with text commands:
 **Assign a role to a rank:**
 
 ```text
-/config role assign 3 @Moderator
+/config role assign rank:3 role:@Moderator
 ```
 
 **Remove a role assignment:**
 
 ```text
-/config role unassign @Moderator
+/config role unassign role:@Moderator
 ```
 
 **List all assignments:**
@@ -120,7 +120,7 @@ Member (Rank 0) → @Member (everyone starts here)
 **Command Method:**
 
 ```text
-/config role assign <rank_number> @RoleName
+/config role assign rank:<rank_number> role:@RoleName
 ```
 
 ### Removing Assignments
@@ -134,7 +134,7 @@ Member (Rank 0) → @Member (everyone starts here)
 **Command Method:**
 
 ```text
-/config role unassign @RoleName
+/config role unassign role:@RoleName
 ```
 
 ### Viewing Assignments

docs/content/faq/index.md

@@ -9,3 +9,27 @@ icon: material/help-circle-outline
     This section is a work in progress. Please help us by contributing to the documentation.
 
 This page contains frequently asked questions and answers about Tux.
+
+## General Questions
+
+**Q:** Will I be able to invite Tux to my server?
+
+**A:** A public bot is planned but for now you can self-host.
+
+**Q:** How can I support Tux?
+
+**A:** For code or documentation you can ask in the [Discord](https://discord.gg/gpmSjcjQxg) or financially on [Open Collective](https://opencollective.com/allthingslinux).
+
+**Q:** Will I be able to use Tux inside Direct Messages?
+
+**A:** We plan to support this.
+
+**Q:** Can you add "X" Feature?
+
+**A:** Open a github issue with the "[FEATURE]" or open a pull-request and we'll think about it.
+
+## Support Questions
+
+**Q:** I need help setting up Tux!
+
+**A:** Feel free to open a Github issue or ask in the [Discord](https://discord.gg/gpmSjcjQxg).

docs/content/reference/docs/index.md

@@ -0,0 +1,19 @@
+---
+title: Documentation
+description: Templates and resources for creating consistent documentation for Tux
+tags:
+  - reference
+  - docs
+  - documentation
+---
+
+# Documentation
+
+This section contains templates and resources for creating consistent documentation for Tux.
+
+## Templates
+
+- [Module Template](templates/module-template.md)
+- [Command Template](templates/command-template.md)
+- [Command Group Template](templates/command-group-template.md)
+- [Feature Template](templates/feature-template.md)