.. _markdown_formatting_guide:

*****************************
Markdown Formatting and Tools
*****************************

This page explains how Markdown formatting works in ``scaldys-project``:
why ``mdformat`` is used directly via ``uv``, how target files are scoped
(``README.md`` and MkDocs documentation in ``docs/``), and what happens at
each stage — local CLI commands and GitHub Actions CI.

.. contents:: On this page
   :local:
   :depth: 2


Why mdformat for Markdown?
==========================

Python tools such as Ruff and Pyright handle Python source files, but leave
Markdown untouched.  Markdown files in a project — such as ``README.md`` and
user-facing documentation pages — benefit from automated, deterministic
formatting:

* **Pure-Python toolchain** — ``mdformat`` is written in Python and runs directly
  via ``uv run mdformat`` without requiring Node.js, npm, or wrapper frameworks
  like ``pre-commit``.
* **CommonMark compliance** — ``mdformat`` enforces standard CommonMark formatting,
  producing clean, predictable Markdown syntax across all platforms.
* **Consistent diffs** — list numbering, code block fences, indentation, and blank
  lines are formatted deterministically.
* **Unified developer experience** — Markdown checking and formatting work with
  the exact same CLI idioms (``ci`` and ``format``) as Ruff and Pyright.


Target File Scoping
===================

Markdown formatting in ``scaldys-project`` can be explicitly configured via
``scaldys-project.toml`` or discovered automatically.

Configured targets:
-------------------

When ``[format]`` defines ``markdown_targets`` in ``scaldys-project.toml``:

* **File paths** (e.g. ``"README.md"``, ``"docs/guide.md"``) are targeted directly.
* **Directory paths** (e.g. ``"docs/manual"``, ``"docs"``) are scanned recursively
  for all ``*.md`` files.
* **Empty list** (``markdown_targets = []``) cleanly skips all Markdown formatting.

Default auto-discovery:
-----------------------

When ``[format]`` or ``markdown_targets`` is omitted, automatic discovery is used:

1. **``README.md``** — in the project root directory (if present).
2. **MkDocs documentation files** — all ``*.md`` files located within ``docs/``
   subdirectories that are detected as MkDocs projects (containing ``mkdocs.yml``).

Excluded by default:
--------------------

* **``RELEASES.md``** — preserved as-is so release notes remain untouched.
* **Other root markdown files** — internal notes (e.g. ``ideas.md``,
  ``improvements.md``) and license files (``licenses/*.md``).
* **Sphinx documentation** — Sphinx projects in ``docs/`` typically use
  reStructuredText (``*.rst``) and are checked by ``sphinx-lint``.


CI Drift Detection
==================

When ``scaldys-project ci markdown`` runs, it compares the target files configured
in ``scaldys-project.toml`` against the ``mdformat`` check step in
``.github/workflows/ci.yml`` (if present).

If the arguments in ``ci.yml`` differ from the configured targets, a warning is
logged to notify developers of the discrepancy, ensuring local checks and CI
remain synchronized.


Command Summary
===============

.. list-table::
   :header-rows: 1
   :widths: 35 25 15 25

   * - Command
     - Underlying action
     - Rewrites?
     - Exits non-zero on
   * - ``scaldys-project ci markdown``
     - ``uv run mdformat --check <targets>``
     - No
     - Formatting differences
   * - ``scaldys-project format markdown``
     - ``uv run mdformat <targets>``
     - Yes
     - Execution error
   * - ``scaldys-project ci all``
     - Runs all CI checks in sequence
     - No
     - Any step failure
   * - ``scaldys-project format all``
     - Runs Python and Markdown formatters
     - Yes
     - Any step failure

.. note::
   The underlying command syntax for each action is displayed in the terminal
   output at the standard ``INFO`` level in dim text.


Local Workflow
==============

The recommended developer workflow is:

1. Run ``scaldys-project ci all`` to check everything (matches GitHub Actions CI).
2. If ``ci format`` fails, run ``scaldys-project format python`` to fix Python files.
3. If ``ci markdown`` fails, run ``scaldys-project format markdown`` to fix target
   Markdown files in place.
4. Stage and commit the formatted files.
5. Re-run ``scaldys-project ci all`` to confirm all checks pass.


GitHub Actions CI
=================

In GitHub Actions (``.github/workflows/ci.yml``), Markdown formatting is verified
in the ``code_quality`` job step::

    - name: Markdown format check
      run: uv run mdformat --check README.md

Because ``mdformat`` runs with the ``--check`` flag, it will report any
unformatted files and fail the CI job without making modifications on the runner.
Running ``scaldys-project ci markdown`` locally checks all target Markdown files
and guarantees parity with the CI pipeline.