270 lines
13 KiB
Plaintext
270 lines
13 KiB
Plaintext
---
|
|
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., ``).
|
|
- **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. |