📝 docs(platforms): fix RST formatting and TOC hierarchy

.github/workflows/check.yaml

@@ -7,11 +7,9 @@ on:
   pull_request:
   schedule:
     - cron: "0 8 * * *"
-
 concurrency:
   group: check-${{ github.ref }}
   cancel-in-progress: true
-
 jobs:
   test:
     name: test ${{ matrix.py }} - ${{ matrix.os }}
@@ -31,8 +29,7 @@ jobs:
           - windows-2025
           - macos-15
         exclude:
-          - { os: windows-2025, py: pypy3.11 }
-
+          - {os: windows-2025, py: pypy3.11}
     steps:
       - uses: actions/checkout@v6
         with:
@@ -73,7 +70,6 @@ jobs:
           name: .coverage.${{ matrix.os }}.${{ matrix.py }}
           path: ".tox/.coverage.*"
           retention-days: 3
-
   coverage:
     name: Combine coverage
     runs-on: ubuntu-24.04
@@ -107,7 +103,6 @@ jobs:
         with:
           name: html-report
           path: .tox/htmlcov
-
   check:
     name: ${{ matrix.tox_env }} - ${{ matrix.os }}
     runs-on: ${{ matrix.os }}
@@ -123,7 +118,7 @@ jobs:
           - docs
           - pkg_meta
         exclude:
-          - { os: windows-2025, tox_env: pkg_meta }
+          - {os: windows-2025, tox_env: pkg_meta}
     steps:
       - uses: actions/checkout@v6
         with:

.github/workflows/release.yaml

@@ -11,20 +11,13 @@ on:
   push:
     branches: ["main"]
   pull_request:
-
 concurrency:
-  group: >-
-    ${{ github.workflow }}-${{ github.ref }}${{
-      github.event.inputs.release && github.event.inputs.release != 'no' && '-release' || ''
-    }}
+  group: ${{ github.workflow }}-${{ github.ref }}${{ github.event.inputs.release && github.event.inputs.release != 'no' && '-release' || '' }}
   cancel-in-progress: ${{ github.event.inputs.release == 'no' || github.event.inputs.release == null }}
-
 permissions:
   contents: read
-
 env:
   dists-artifact-name: python-package-distributions
-
 jobs:
   build:
     name: build
@@ -47,10 +40,7 @@ jobs:
           cache-dependency-glob: "tasks/changelog.py"
       - name: Generate changelog
         id: v
-        run: >-
-          uv run tasks/changelog.py '${{ github.event.inputs.release == 'no' || github.event.inputs.release == null &&
-          'patch' || github.event.inputs.release }}' '${{ github.event.number }}' '${{
-          github.event.pull_request.base.sha }}'
+        run: uv run tasks/changelog.py '${{ github.event.inputs.release == 'no' || github.event.inputs.release == null && 'patch' || github.event.inputs.release }}' '${{ github.event.number }}' '${{ github.event.pull_request.base.sha }}'
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       - name: Create temporary tag for hatch-vcs
@@ -63,7 +53,6 @@ jobs:
         with:
           name: ${{ env.dists-artifact-name }}
           path: dist/*
-
   release:
     name: release
     needs: [build]

.pre-commit-config.yaml

@@ -15,24 +15,33 @@ repos:
       - id: codespell
         additional_dependencies: ["tomli>=2.4"]
   - repo: https://github.com/tox-dev/tox-toml-fmt
-    rev: "v1.5.4"
+    rev: "v1.6.0"
     hooks:
       - id: tox-toml-fmt
   - repo: https://github.com/tox-dev/pyproject-fmt
-    rev: "v2.15.3"
+    rev: "v2.16.0"
     hooks:
       - id: pyproject-fmt
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: "v0.15.0"
+    rev: "v0.15.1"
     hooks:
       - id: ruff-format
       - id: ruff-check
         args: ["--fix", "--unsafe-fixes", "--exit-non-zero-on-fix"]
-  - repo: https://github.com/rbubley/mirrors-prettier
-    rev: "v3.8.1"
-    hooks:
-      - id: prettier
-        args: ["--print-width=120", "--prose-wrap=always"]
+  - repo: https://github.com/google/yamlfmt
+    rev: "v0.21.0"
+    hooks:
+      - id: yamlfmt
+  - repo: local
+    hooks:
+      - id: mdformat
+        name: mdformat
+        entry: mdformat --wrap 120
+        language: python
+        types: [markdown]
+        additional_dependencies:
+          - mdformat-gfm
+          - mdformat-ruff
   - repo: meta
     hooks:
       - id: check-hooks-apply

CONTRIBUTING.md

@@ -1,6 +1,123 @@
-This project uses [tox](https://tox.wiki) for development. To see all available environments run `tox list`. To run the
-test suite under a specific Python version, e.g. Python 3.14:
+# Contributing to platformdirs
+
+Thank you for your interest in contributing to platformdirs! This document provides guidelines and instructions for
+contributing to the project.
+
+## Code of Conduct
+
+Be respectful and constructive in all interactions. We aim to maintain a welcoming environment for all contributors.
+
+## Getting Started
+
+This project uses [tox](https://tox.wiki) for all development tasks. Tox provides isolated environments for testing,
+linting, type checking, and documentation building.
+
+To install tox, run:
 
 ```bash
-tox r -e py314
+pip install tox
 ```
+
+To see all available tox environments, run:
+
+```bash
+tox list
+```
+
+## Development Workflow
+
+### Running Tests
+
+Run tests for a specific Python version with `tox r -e 3.14`. To run tests across multiple Python versions, use
+`tox r -e 3.13,3.14`. Running `tox r` will execute all test environments.
+
+### Code Quality Checks
+
+Use `tox r -e fix` to auto-fix formatting and linting issues using ruff. Run `tox r -e type` to check types with
+pyright.
+
+### Coverage
+
+The `coverage` environment combines results from previous test runs and generates reports. Run tests first with specific
+Python versions, then add `coverage` to the command, for example `tox r -e 3.14,3.13,3.12,coverage`. This generates HTML
+coverage reports in `.tox/htmlcov/` and checks coverage diff against `origin/main`.
+
+### Documentation
+
+Build and check documentation with `tox r -e docs`. The built documentation will be available in
+`.tox/docs_out/html/index.html`.
+
+### Package Metadata
+
+Validate package metadata and build artifacts with `tox r -e pkg_meta`. This checks that the package description renders
+correctly on PyPI and validates wheel contents.
+
+### Development Environment
+
+Set up a development environment with all dependencies with `tox r -e dev`. This creates an editable install with all
+development dependencies in `.tox/dev/`.
+
+### Running Everything
+
+Before submitting a pull request, run `tox r` to execute all checks. This runs tests across all supported Python
+versions and performs all quality checks.
+
+## Making Changes
+
+### Fork and Branch
+
+Start by forking the repository on GitHub, then clone your fork locally. Create a branch from `main` with a descriptive
+name such as `fix/issue-123` for bug fixes, `feat/new-directory-type` for features, or `docs/improve-readme` for
+documentation changes.
+
+### Code Style
+
+Follow existing code patterns in the codebase. All code must pass `tox r -e fix` for ruff formatting and linting. Add
+type annotations to all new code, which are checked by `tox r -e type`. Keep functions focused and well-named, and
+prefer explicit over implicit code.
+
+### Testing
+
+Add tests for all new features and bug fixes. Tests must pass on all supported Python versions. To check coverage across
+multiple Python versions, run `tox r -e 3.14,3.13,3.12,coverage` to execute tests and then combine coverage results. We
+target 100% code coverage.
+
+### Documentation
+
+When making user-facing changes, update relevant `.rst` files in `docs/`. Add docstrings to new public functions. Update
+examples if behavior changes. Run `tox r -e docs` to verify documentation builds.
+
+## Submitting Changes
+
+### Commit Messages
+
+Follow Commitizen conventions with the format `<type>: <summary>` and an optional body explaining the motivation and
+approach. Common types are `feat`, `fix`, `docs`, `refactor`, and `test`. For example:
+
+```
+fix: handle missing XDG_RUNTIME_DIR on FreeBSD
+
+Falls back to /var/run/user/<uid> when /run/user/<uid> does not exist,
+addressing issues on FreeBSD systems that don't create the runtime directory.
+```
+
+### Pull Requests
+
+Ensure `tox r` passes on your branch before pushing. Push to your fork and open a pull request against `main`. Fill in
+the PR template with a clear description of changes, related issue numbers, and testing performed. Wait for CI checks to
+complete and address any review feedback.
+
+## Platform-Specific Development
+
+When adding platform-specific functionality, test on the target platform. Document behavior in `docs/platforms.rst` and
+follow existing patterns for the platform by checking `src/platformdirs/<platform>.py`. Consider environment variable
+overrides if applicable.
+
+## Getting Help
+
+Check existing [issues](https://github.com/tox-dev/platformdirs/issues) and review the
+[documentation](https://platformdirs.readthedocs.io) before asking. Open a new issue for bugs or feature requests.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the project's MIT License.

README.md

@@ -14,13 +14,27 @@ differences between macOS, Windows, Linux/Unix, and Android so you don't have to
 from platformdirs import PlatformDirs
 
 dirs = PlatformDirs("MyApp", "MyCompany")
-dirs.user_data_dir  # e.g. ~/.local/share/MyApp on Linux
-dirs.user_config_dir  # e.g. ~/.config/MyApp on Linux
-dirs.user_cache_dir  # e.g. ~/.cache/MyApp on Linux
-dirs.user_log_dir  # e.g. ~/.local/state/MyApp/log on Linux
+dirs.user_data_dir  # ~/.local/share/MyApp (Linux)
+dirs.user_config_dir  # ~/.config/MyApp (Linux)
+dirs.user_cache_dir  # ~/.cache/MyApp (Linux)
+dirs.user_state_dir  # ~/.local/state/MyApp (Linux)
+dirs.user_log_dir  # ~/.local/state/MyApp/log (Linux)
+dirs.user_documents_dir  # ~/Documents
+dirs.user_downloads_dir  # ~/Downloads
+dirs.user_runtime_dir  # /run/user/<uid>/MyApp (Linux)
 ```
 
-Convenience functions are also available:
+For Path objects instead of strings:
+
+```python
+from platformdirs import PlatformDirs
+
+dirs = PlatformDirs("MyApp", "MyCompany")
+dirs.user_data_path  # pathlib.Path('~/.local/share/MyApp')
+dirs.user_config_path  # pathlib.Path('~/.config/MyApp')
+```
+
+Convenience functions for quick access:
 
 ```python
 from platformdirs import user_data_dir, user_config_path
@@ -29,25 +43,28 @@ user_data_dir("MyApp", "MyCompany")  # returns str
 user_config_path("MyApp", "MyCompany")  # returns pathlib.Path
 ```
 
-## Documentation
+## Directory types
 
-Full documentation is available at [platformdirs.readthedocs.io](https://platformdirs.readthedocs.io), including:
+- **Data**: Persistent application data (`user_data_dir`, `site_data_dir`)
+- **Config**: Configuration files and settings (`user_config_dir`, `site_config_dir`)
+- **Cache**: Cached data that can be regenerated (`user_cache_dir`, `site_cache_dir`)
+- **State**: Non-essential runtime state like window positions (`user_state_dir`, `site_state_dir`)
+- **Logs**: Log files (`user_log_dir`, `site_log_dir`)
+- **Runtime**: Runtime files like sockets and PIDs (`user_runtime_dir`, `site_runtime_dir`)
 
-- [Usage guide](https://platformdirs.readthedocs.io/en/latest/usage.html) -- parameters, examples, and patterns
-- [API reference](https://platformdirs.readthedocs.io/en/latest/api.html) -- all functions and classes
-- [Platform details](https://platformdirs.readthedocs.io/en/latest/platforms.html) -- per-platform paths and behavior
+Each type has both `user_*` (per-user, writable) and `site_*` (system-wide, read-only for users) variants.
 
-## Why this fork?
-
-This repository is a friendly fork of the wonderful work started by
-[ActiveState](https://github.com/ActiveState/appdirs) who created `appdirs`, this package's ancestor.
+## Documentation
 
-Maintaining an open source project is no easy task, particularly from within an organization, and the Python community
-is indebted to `appdirs` (and to Trent Mick and Jeff Rouse in particular) for creating an incredibly useful simple
-module, as evidenced by the wide number of users it has attracted over the years.
+Full documentation is available at [platformdirs.readthedocs.io](https://platformdirs.readthedocs.io):
 
-Nonetheless, given the number of long-standing open issues and pull requests, and no clear path towards
-[ensuring that maintenance of the package would continue or grow](https://github.com/ActiveState/appdirs/issues/79),
-this fork was created.
+- **[Getting started tutorial](https://platformdirs.readthedocs.io/en/latest/usage.html)** -- learn core concepts
+  through real-world examples
+- **[How-to guides](https://platformdirs.readthedocs.io/en/latest/howto.html)** -- recipes for common tasks and
+  platform-specific tips
+- **[API reference](https://platformdirs.readthedocs.io/en/latest/api.html)** -- complete list of functions and classes
+- **[Platform details](https://platformdirs.readthedocs.io/en/latest/platforms.html)** -- default paths for each
+  operating system
 
-Contributions are most welcome.
+Contributions are welcome! See [CONTRIBUTING.md](https://github.com/tox-dev/platformdirs/blob/main/CONTRIBUTING.md) for
+details.