--- 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.