Joseph.Rawlings/Virtnet.bond
Public Access
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

refactor: streamline onboarding modal by removing unnecessary slide preparation logic and enhancing loading state management for improved user experience

Browse Source
This commit is contained in:
Joseph.Rawlings
2025-12-04 00:11:26 -05:00
parent a6c8e14db0
commit 5cd9a52668
242 changed files with 59643 additions and 61 deletions
Download Patch File Download Diff File Expand all files Collapse all files

270
.cursor/rules/mkdocs.mdc Normal file
View File

@@ -0,0 +1,270 @@
---
description: Comprehensive guidelines for mkdocs development, covering code organization, best practices, performance, security, testing, common pitfalls, and tooling. This rule aims to ensure maintainable, performant, and secure documentation using mkdocs.
globs: *.md
---
# mkdocs Best Practices
This document provides comprehensive guidelines for developing documentation using mkdocs. It covers various aspects including code organization, common patterns, performance, security, testing, common pitfalls, and tooling.
## 1. Code Organization and Structure
### 1.1. Directory Structure Best Practices
- **docs/**: All documentation source files should reside within this directory. This is the default and recommended location for mkdocs.
- `index.md`: The project homepage.
- `about.md`: An example of another page.
- `user-guide/`: A subdirectory for a section of documentation.
- `getting-started.md`: A sub-page within the user guide.
- `configuration-options.md`: Another sub-page.
- `img/`: A directory to store images used in the documentation. Store your images as close as possible to the document that references it.
- `screenshot.png`
- **mkdocs.yml**: The main configuration file for mkdocs, located at the root of the project alongside the `docs/` directory.
Example:
mkdocs.yml
docs/
index.md
about.md
license.md
img/
screenshot.png
user-guide/
getting-started.md
configuration-options.md
### 1.2. File Naming Conventions
- Use `.md` as the extension for Markdown files.
- Name the homepage `index.md` or `README.md`.
- Use descriptive names for other pages (e.g., `getting-started.md`, `configuration-options.md`).
- Use lowercase and hyphens for file names to create clean URLs.
### 1.3. Module Organization
- mkdocs itself doesn't have modules in the traditional programming sense. Structure your documentation content logically into sections and sub-sections using directories and files.
- Use the `nav` configuration in `mkdocs.yml` to define the structure of the navigation menu.
Example:
nav:
- Home: index.md
- User Guide:
- Getting Started: user-guide/getting-started.md
- Configuration Options: user-guide/configuration-options.md
- About: about.md
- License: license.md
### 1.4. Component Architecture
- mkdocs is not a component-based system like React or Vue.js.
- Instead, think of each Markdown file as a page or section of your documentation.
- Use includes or macros (via plugins) to reuse content across multiple pages (see Snippets and Includes section).
### 1.5. Code Splitting Strategies
- Divide your documentation into logical sections and sub-sections.
- Create separate Markdown files for each section.
- Use the `nav` configuration to structure the navigation menu.
- Use `include-markdown` plugin to avoid repeating content in multiple pages.
## 2. Common Patterns and Anti-patterns
### 2.1. Design Patterns Specific to mkdocs
- **Navigation as Code**: Managing the navigation structure directly within `mkdocs.yml` is a fundamental pattern. It allows for centralized control over the site's hierarchy.
- **Content Reusability**: Utilizing plugins like `include-markdown` to reuse common elements like disclaimers, notices, or standard procedures.
- **Theming Customization**: Overriding the default theme templates to tailor the look and feel of the documentation to match branding or specific aesthetic requirements.
- **Plugin Extension**: Extending the functionality of mkdocs by using and customizing existing plugins or creating custom ones to fulfill specific documentation needs, such as generating API documentation or integrating with external tools.
### 2.2. Recommended Approaches for Common Tasks
- **Linking to Pages**: Use relative paths for internal links to avoid issues when deploying (e.g., `[link to about](about.md)`).
- **Linking to Sections**: Use anchor links to link to specific sections within a page (e.g., `[link to license](about.md#license)`).
- **Including Images**: Place images in the `docs/img/` directory and link to them using relative paths (e.g., `![Screenshot](img/screenshot.png)`).
- **Adding Meta-Data**: Add YAML or MultiMarkdown style meta-data to the beginning of Markdown files to control page templates or add information such as authors or descriptions.
### 2.3. Anti-patterns and Code Smells to Avoid
- **Absolute Paths in Links**: Avoid using absolute paths for internal links. Use relative paths instead.
- **Large Markdown Files**: Avoid creating very large Markdown files. Break them into smaller, more manageable files and use the `nav` configuration to link them.
- **Ignoring the `nav` Configuration**: Relying on the automatic navigation generation instead of explicitly defining it in `mkdocs.yml` can lead to a disorganized navigation menu.
- **Over-Customization**: Excessively customizing the theme or adding too many plugins can make the documentation difficult to maintain and update.
- **Lack of a Clear File Structure**: An unstructured or inconsistent file structure makes it difficult to navigate and understand the documentation.
### 2.4. State Management Best Practices
- mkdocs is a static site generator, so it doesn't have a traditional concept of state management.
- However, you can use plugins to add dynamic content or interact with external data sources.
### 2.5. Error Handling Patterns
- mkdocs doesn't have runtime error handling in the traditional sense.
- Errors typically occur during the build process (e.g., invalid configuration, broken links).
- Use a CI/CD pipeline to automatically build and test the documentation and catch errors early.
- Utilize linters and validators (plugins) to ensure the integrity of your Markdown and configuration files.
## 3. Performance Considerations
### 3.1. Optimization Techniques
- **Optimize Images**: Use optimized images to reduce file sizes and improve loading times.
- **Minify HTML, CSS, and JavaScript**: Use the `mkdocs-minify-plugin` to minify the generated HTML, CSS, and JavaScript files.
- **Lazy Loading Images**: Lazy load images below the fold to improve initial page load time.
- **Use a CDN**: Use a CDN (Content Delivery Network) to serve static assets (images, CSS, JavaScript) from multiple locations around the world.
### 3.2. Memory Management
- mkdocs itself doesn't have specific memory management considerations.
- However, if you're using plugins that generate dynamic content, be mindful of memory usage.
### 3.3. Rendering Optimization
- mkdocs generates static HTML files, so rendering performance is generally not a concern.
- However, complex Markdown structures can slow down the build process. Keep your Markdown files as simple as possible.
### 3.4. Bundle Size Optimization
- Optimize the size of your images and other static assets.
- Use the `mkdocs-minify-plugin` to minify the generated HTML, CSS, and JavaScript files.
- Avoid including unnecessary CSS or JavaScript in your theme.
### 3.5. Lazy Loading Strategies
- Implement lazy loading for images using JavaScript.
## 4. Security Best Practices
### 4.1. Common Vulnerabilities and How to Prevent Them
- **Cross-Site Scripting (XSS)**: Since mkdocs generates static sites, the risk of XSS is minimal, but if you incorporate user-generated content or external data, sanitize inputs properly.
- **Injection Attacks**: Avoid using untrusted data to generate content. If you must use untrusted data, sanitize it properly.
### 4.2. Input Validation
- If your mkdocs site incorporates forms or user input via plugins, validate all inputs to prevent injection attacks.
### 4.3. Authentication and Authorization Patterns
- mkdocs doesn't provide built-in authentication or authorization.
- If you need to protect certain pages, you can implement authentication at the web server level or use a plugin.
### 4.4. Data Protection Strategies
- Since mkdocs generates static sites, there is no sensitive data stored on the server.
- However, be careful not to include sensitive information in your documentation source files.
### 4.5. Secure API Communication
- If your mkdocs site communicates with external APIs, use HTTPS to encrypt the communication.
- Verify the API server's SSL certificate.
## 5. Testing Approaches
### 5.1. Unit Testing Strategies
- mkdocs itself doesn't have unit tests in the traditional programming sense.
- However, if you create custom plugins, you should write unit tests for them.
### 5.2. Integration Testing
- Create integration tests to verify that your mkdocs site is built correctly and that all links are working.
- Use a tool like `htmlproofer` to validate URLs in the rendered HTML files.
### 5.3. End-to-end Testing
- Use an end-to-end testing framework to verify that your mkdocs site is working as expected in a browser.
### 5.4. Test Organization
- Organize your tests into separate directories (e.g., `tests/`).
- Use descriptive names for your test files and test functions.
### 5.5. Mocking and Stubbing
- If you're testing custom plugins that interact with external APIs, use mocking and stubbing to isolate your tests.
## 6. Common Pitfalls and Gotchas
### 6.1. Frequent Mistakes Developers Make
- **Incorrect File Paths**: Using incorrect file paths in links or image references.
- **Ignoring the `nav` Configuration**: Relying on the automatic navigation generation instead of explicitly defining it in `mkdocs.yml`.
- **Over-Customization**: Customizing the theme too much can make the documentation difficult to maintain and update.
- **Not Keeping Documentation Up-to-Date**: Forgetting to update the documentation when the codebase changes.
### 6.2. Edge Cases to Be Aware Of
- **Long File Paths**: Long file paths can cause issues on some operating systems.
- **Special Characters in File Names**: Avoid using special characters in file names.
- **Conflicting Plugin Options**: Some plugins may have conflicting options.
### 6.3. Version-Specific Issues
- mkdocs is constantly evolving, so be aware of version-specific issues.
- Always test your documentation with the latest version of mkdocs before deploying.
### 6.4. Compatibility Concerns
- Ensure that your documentation is compatible with different browsers and devices.
- Test your documentation on different platforms to ensure that it looks good everywhere.
### 6.5. Debugging Strategies
- **Check the mkdocs Build Log**: The mkdocs build log contains valuable information about errors and warnings.
- **Use a Debugger**: Use a debugger to step through the mkdocs build process and identify issues.
- **Simplify Your Configuration**: Simplify your `mkdocs.yml` file to isolate the issue.
- **Disable Plugins**: Disable plugins one by one to identify the plugin causing the issue.
## 7. Tooling and Environment
### 7.1. Recommended Development Tools
- **Text Editor**: VS Code, Sublime Text, Atom
- **Markdown Editor**: Typora, Mark Text
- **Web Browser**: Chrome, Firefox, Safari
- **mkdocs CLI**: The mkdocs command-line interface.
### 7.2. Build Configuration
- Use a `mkdocs.yml` file to configure your mkdocs site.
- The `mkdocs.yml` file should be located at the root of your project.
- The `mkdocs.yml` file should contain the following information:
- `site_name`: The name of your site.
- `site_description`: A description of your site.
- `site_author`: The author of your site.
- `docs_dir`: The directory containing your documentation source files.
- `theme`: The theme to use for your site.
- `nav`: The navigation menu for your site.
- `markdown_extensions`: A list of Markdown extensions to enable.
- `plugins`: A list of plugins to enable.
### 7.3. Linting and Formatting
- Use a linter to enforce code style and identify potential issues.
- Use a formatter to automatically format your Markdown files.
### 7.4. Deployment Best Practices
- **Use a CI/CD Pipeline**: Use a CI/CD pipeline to automatically build and deploy your mkdocs site.
- **Deploy to a CDN**: Deploy your mkdocs site to a CDN to improve performance.
- **Use HTTPS**: Use HTTPS to encrypt communication with your site.
- **Configure a Custom Domain**: Configure a custom domain for your site.
### 7.5. CI/CD Integration
- Use a CI/CD tool like GitHub Actions, GitLab CI, or Travis CI to automatically build and deploy your mkdocs site.
- Configure your CI/CD pipeline to run tests and linters.
- Configure your CI/CD pipeline to deploy your site to a CDN.
## Additional Notes
- Always refer to the official mkdocs documentation for the most up-to-date information.
- Consider contributing to the mkdocs community by creating plugins or themes.
- Stay informed about the latest best practices and security vulnerabilities.
This comprehensive guide should help you create maintainable, performant, and secure documentation using mkdocs.