ci: introduce markdownlint-cli2 and verify docs build on PRs (closes #717)

Lint Markdown under docs/ and project-root *.md, and run sphinx-multiversion
build on docs-touching PRs to catch syntax/reference errors before merge.

- Pin markdownlint-cli2 0.18.1 via .mise.toml (npm backend; node auto-resolved)
- Add .markdownlint-cli2.jsonc tuned to existing PyAthena docs style:
  dash bullets, 2-space indent, allow inline HTML used in MyST/README
- Add make docs-lint / docs-lint-fix targets that shell out via mise exec
- Add .github/workflows/docs-lint.yaml: lint + sphinx-multiversion build,
  triggered only on docs/**, **.md, and the workflow/config files themselves
- Fix 5 remaining manual violations after auto-fix:
  - MD051: use MyST {ref}`pandas-cursor` instead of broken HTML anchor
  - MD036: promote three bold-as-heading spans in pandas.md to h4
  - MD001: add "Basic usage" h2 wrapper in sqlalchemy.md
- Auto-fix touched README.md, CLAUDE.md, docs/*.md (mostly bullet style)
- Document mise-based local workflow in CLAUDE.md

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: laughingman7743

.github/workflows/docs-lint.yaml

@@ -0,0 +1,36 @@
+name: Docs Lint
+
+on:
+  pull_request:
+    paths:
+      - 'docs/**'
+      - '**.md'
+      - '.markdownlint-cli2.jsonc'
+      - '.mise.toml'
+      - 'Makefile'
+      - '.github/workflows/docs-lint.yaml'
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: jdx/mise-action@1648a7812b9aeae629881980618f079932869151 # v4.0.1
+      - run: make docs-lint
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 0  # Fetch all history for sphinx-multiversion
+      - uses: jdx/mise-action@1648a7812b9aeae629881980618f079932869151 # v4.0.1
+      - uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7.6.0
+        with:
+          enable-cache: true
+      - run: |
+          uv sync --group dev
+          make docs

.markdownlint-cli2.jsonc

@@ -0,0 +1,40 @@
+{
+  // https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md
+  "config": {
+    "default": true,
+    // Line length: docs have long URLs, code blocks, and prose lines
+    "MD013": false,
+    // Match existing style: dash bullets, 2-space nested indent
+    "MD004": { "style": "dash" },
+    "MD007": { "indent": 2 },
+    // Allow inline HTML used by README (centered images) and MyST admonitions
+    "MD033": {
+      "allowed_elements": ["details", "summary", "br", "kbd", "sub", "sup", "div", "img", "p", "a"]
+    },
+    // Cursor docs intentionally repeat subsection names ("Basic usage") under different cursors
+    "MD024": { "siblings_only": true },
+    // Don't require fenced code blocks to specify a language
+    "MD040": false,
+    // Don't require blank lines around code fences / lists — existing docs intermix them
+    "MD031": false,
+    "MD032": false,
+    // Allow `$ command` style in shell snippets (testing.md, README)
+    "MD014": false,
+    // Allow bare URLs
+    "MD034": false,
+    // First line need not be a top-level heading (some files start with MyST ref targets)
+    "MD041": false
+  },
+  "globs": [
+    "docs/**/*.md",
+    "*.md"
+  ],
+  "ignores": [
+    "docs/_build/**",
+    "node_modules/**",
+    ".venv/**",
+    ".tox/**",
+    ".pytest_cache/**",
+    ".serena/**"
+  ]
+}

.mise.toml

@@ -1,2 +1,3 @@
 [tools]
 python = "3.12"
+"npm:markdownlint-cli2" = "0.18.1"

CLAUDE.md

@@ -1,26 +1,31 @@
 # PyAthena Development Guide for AI Assistants
 
 ## Project Overview
+
 PyAthena is a Python DB API 2.0 (PEP 249) compliant client for Amazon Athena. See `pyproject.toml` for Python version support and dependencies.
 
 ## Rules and Constraints
 
 ### Git Workflow
+
 - **NEVER** commit directly to `master` — always create a feature branch and PR
 - Create PRs as drafts: `gh pr create --draft`
 
 ### Import Rules
+
 - **NEVER** use runtime imports (inside functions, methods, or conditional blocks)
 - All imports must be at the top of the file, after the license header
 - Exception: the existing codebase uses runtime imports for optional dependencies (`pyarrow`, `pandas`, etc.) in source code. For new code, use `TYPE_CHECKING` instead when possible
 
 ### Code Quality — Always Run Before Committing
+
 ```bash
 make format   # Auto-fix formatting and imports
 make lint   # Lint + format check + mypy
 ```
 
 ### Testing
+
 ```bash
 # ALWAYS run `make lint` first — tests will fail if lint doesn't pass
 make test       # Unit tests (runs chk first)
@@ -43,6 +48,7 @@ export $(cat .env | xargs) && uv run pytest tests/pyathena/test_file.py -v
 - New features require tests; changes to SQLAlchemy dialects must pass `make test-sqla`
 
 #### Test Conventions
+
 - **Class-based tests** for integration tests that use fixtures (cursors, engines): `class TestCursor:` with methods like `def test_fetchone(self, cursor):`
 - **Standalone functions** for unit tests of pure logic (converters, parsers, utils): `def test_to_struct_json_formats(input_value, expected):`
 - Test file naming mirrors source: `pyathena/parser.py` → `tests/pyathena/test_parser.py`
@@ -55,24 +61,41 @@ export $(cat .env | xargs) && uv run pytest tests/pyathena/test_file.py -v
 - **Parametrize** with `@pytest.mark.parametrize(("input", "expected"), [...])` for data-driven tests
 - **Integration tests** (need AWS) use cursor/engine fixtures with real Athena queries; **unit tests** (no AWS) call functions directly with test data
 
+### Markdown Lint
+
+`docs/**/*.md` and project-root `*.md` files are linted with [markdownlint-cli2](https://github.com/DavidAnson/markdownlint-cli2). The config lives at `.markdownlint-cli2.jsonc`. CI runs lint + Sphinx build on PRs that touch docs (`.github/workflows/docs-lint.yaml`).
+
+`markdownlint-cli2` is pinned in `.mise.toml` (along with `node`), so [`mise`](https://mise.jdx.dev/) installs the exact version used in CI. Run locally:
+
+```bash
+mise install          # one-time: installs node + markdownlint-cli2
+make docs-lint        # check
+make docs-lint-fix    # auto-fix what's possible
+```
+
 ## Architecture — Key Design Decisions
 
 These are non-obvious conventions that can't be discovered by reading code alone.
 
 ### PEP 249 Compliance
+
 All cursor types must implement: `execute()`, `fetchone()`, `fetchmany()`, `fetchall()`, `close()`. New cursor features must follow the DB API 2.0 specification.
 
 ### Cursor Module Pattern
+
 Each cursor type lives in its own subpackage (`pandas/`, `arrow/`, `polars/`, `s3fs/`, `spark/`) with a consistent structure: `cursor.py`, `async_cursor.py`, `converter.py`, `result_set.py`. When adding features, consider impact on all cursor types.
 
 ### Filesystem (fsspec) Compatibility
+
 `pyathena/filesystem/s3.py` implements fsspec's `AbstractFileSystem`. When modifying:
 - Match `s3fs` library behavior where possible (users migrate from it)
 - Use `delimiter="/"` in S3 API calls to minimize requests
 - Handle edge cases: empty paths, trailing slashes, bucket-only paths
 
 ### Version Management
+
 Versions are derived from git tags via `hatch-vcs` — never edit `pyathena/_version.py` manually.
 
 ### Google-style Docstrings
+
 Use Google-style docstrings for public methods. See existing code for examples.

Makefile

@@ -36,6 +36,14 @@ docs:
 	echo 'pyathena.dev' > docs/_build/html/CNAME
 	touch docs/_build/html/.nojekyll
 
+.PHONY: docs-lint
+docs-lint:
+	mise exec -- markdownlint-cli2
+
+.PHONY: docs-lint-fix
+docs-lint-fix:
+	mise exec -- markdownlint-cli2 --fix
+
 .PHONY: tool
 tool:
 	uv tool install ruff@$(RUFF_VERSION)

README.md

@@ -21,7 +21,7 @@ PyAthena is a Python [DB API 2.0 (PEP 249)](https://www.python.org/dev/peps/pep-
 
 ## Requirements
 
-* Python
+- Python
 
   - CPython 3.10, 3.11, 3.12, 3.13, 3.14
 

docs/cursor.md

@@ -293,7 +293,6 @@ cursor = connect(s3_staging_dir="s3://YOUR_S3_BUCKET/path/to/",
                  region_name="us-west-2").cursor(cursor=AsyncDictCursor, dict_type=OrderedDict)
 ```
 
-
 ## AioCursor
 
 See {ref}`aio-cursor`.

docs/introduction.md

@@ -6,7 +6,7 @@
 
 ## Requirements
 
-* Python
+- Python
 
   - CPython 3.10, 3.11, 3.12, 3.13, 3.14
 
@@ -35,23 +35,23 @@ Extra packages:
 PyAthena provides comprehensive support for Amazon Athena's data types and features:
 
 **Core Features:**
-  - **DB API 2.0 Compliance**: Full PEP 249 compatibility for database operations
-  - **SQLAlchemy Integration**: Native dialect support with table reflection and ORM capabilities
-  - **Multiple Cursor Types**: Standard, Pandas, Arrow, Polars, S3FS and Spark cursor implementations
-  - **Async Support**: Asynchronous query execution for non-blocking operations
+- **DB API 2.0 Compliance**: Full PEP 249 compatibility for database operations
+- **SQLAlchemy Integration**: Native dialect support with table reflection and ORM capabilities
+- **Multiple Cursor Types**: Standard, Pandas, Arrow, Polars, S3FS and Spark cursor implementations
+- **Async Support**: Asynchronous query execution for non-blocking operations
 
 **Data Type Support:**
-  - **STRUCT/ROW Types**: {ref}`Complete support <sqlalchemy>` for complex nested data structures
-  - **ARRAY Types**: {ref}`Complete support <sqlalchemy>` for ordered collections with automatic Python list conversion
-  - **MAP Types**: {ref}`Complete support <sqlalchemy>` for key-value dictionary-like data structures
-  - **JSON Integration**: Seamless JSON data parsing and conversion
-  - **Performance Optimized**: Smart format detection for efficient data processing
+- **STRUCT/ROW Types**: {ref}`Complete support <sqlalchemy>` for complex nested data structures
+- **ARRAY Types**: {ref}`Complete support <sqlalchemy>` for ordered collections with automatic Python list conversion
+- **MAP Types**: {ref}`Complete support <sqlalchemy>` for key-value dictionary-like data structures
+- **JSON Integration**: Seamless JSON data parsing and conversion
+- **Performance Optimized**: Smart format detection for efficient data processing
 
 **Additional Features:**
-  - **Connection Management**: Efficient connection pooling and configuration
-  - **Result Caching**: Athena query result reuse capabilities
-  - **Error Handling**: Comprehensive exception handling and recovery
-  - **S3 Integration**: Direct S3 data access and staging support
+- **Connection Management**: Efficient connection pooling and configuration
+- **Result Caching**: Athena query result reuse capabilities
+- **Error Handling**: Comprehensive exception handling and recovery
+- **S3 Integration**: Direct S3 data access and staging support
 
 (license)=
 

docs/pandas.md

@@ -33,7 +33,7 @@ df = as_pandas(cursor)
 print(df.describe())
 ```
 
-If you want to use the query results output to S3 directly, you can use [PandasCursor](#pandas-cursor).
+If you want to use the query results output to S3 directly, you can use {ref}`pandas-cursor`.
 This cursor fetches query results faster than the default cursor. (See [benchmark results](https://github.com/pyathena-dev/PyAthena/tree/master/benchmarks).)
 
 (to-sql)=
@@ -392,7 +392,7 @@ for df in df_iter:
     print(df.head())
 ```
 
-**Memory-efficient iteration with iter_chunks()**
+#### Memory-efficient iteration with iter_chunks()
 
 PandasCursor provides an `iter_chunks()` method for convenient chunked processing:
 
@@ -456,7 +456,7 @@ df_iter.get_chunk(10)
 df_iter.get_chunk(10)  # raise StopIteration
 ```
 
-**Auto-optimization of chunksize**
+#### Auto-optimization of chunksize
 
 PandasCursor can automatically determine optimal chunksize based on result file size when enabled:
 
@@ -506,7 +506,7 @@ AthenaPandasResultSet.AUTO_CHUNK_SIZE_LARGE = 200_000  # Larger chunks
 AthenaPandasResultSet.AUTO_CHUNK_SIZE_MEDIUM = 100_000
 ```
 
-**Performance tuning options**
+#### Performance tuning options
 
 PandasCursor accepts additional pandas.read_csv() options for performance optimization:
 
@@ -829,4 +829,3 @@ async with await aio_connect(s3_staging_dir="s3://YOUR_S3_BUCKET/path/to/",
     await cursor.execute("SELECT * FROM many_rows")
     df = cursor.as_pandas()
 ```
-

docs/polars.md

@@ -649,4 +649,3 @@ async with await aio_connect(s3_staging_dir="s3://YOUR_S3_BUCKET/path/to/",
     await cursor.execute("SELECT * FROM many_rows")
     df = cursor.as_polars()
 ```
-