|
| 1 | +# Documentation Tool Configuration |
| 2 | + |
| 3 | +This directory contains configuration files for the various documentation validation tools used in our workflow. |
| 4 | + |
| 5 | +## Files |
| 6 | + |
| 7 | +- `.markdownlint.yml`: Configuration for markdownlint rules |
| 8 | +- `markdown-link-check.json`: Configuration for markdown-link-check tool |
| 9 | + |
| 10 | +## Integration with MegaLinter |
| 11 | + |
| 12 | +These configuration files are used by MegaLinter's documentation flavor. MegaLinter provides a standardized way to run various linters with consistent configuration and reporting. |
| 13 | + |
| 14 | +## Markdownlint Configuration |
| 15 | + |
| 16 | +The `.markdownlint.yml` file controls the rules for markdown linting, including: |
| 17 | + |
| 18 | +- Heading structure and formatting |
| 19 | +- List formatting and consistency |
| 20 | +- Permitted HTML elements |
| 21 | +- Line length requirements |
| 22 | +- Code block formatting |
| 23 | + |
| 24 | +## Link Checking Configuration |
| 25 | + |
| 26 | +The `markdown-link-check.json` file configures link validation: |
| 27 | + |
| 28 | +- URL patterns to ignore (anchors, mailto, etc.) |
| 29 | +- URL replacement patterns |
| 30 | +- Timeout and retry settings |
| 31 | +- Valid status codes |
| 32 | + |
| 33 | +## Local Usage |
| 34 | + |
| 35 | +To run these tools locally: |
| 36 | + |
| 37 | +```bash |
| 38 | +# Run markdown linting |
| 39 | +make lint/markdown |
| 40 | + |
| 41 | +# Run full documentation validation (including links) |
| 42 | +make lint/docs |
| 43 | +``` |
| 44 | + |
| 45 | +## Adding or Modifying Rules |
| 46 | + |
| 47 | +When modifying configuration files: |
| 48 | + |
| 49 | +1. Test changes locally first |
| 50 | +2. Document any significant changes in the PR |
| 51 | +3. Consider impacts on existing documentation |
| 52 | +4. Run the test script to validate integration: `.github/docs/testing/test-megalinter.sh` |
0 commit comments