ci: enable MD031/MD032/MD034/MD040 markdownlint rules

Originally disabled to land the initial config without manual cleanup, but
the violations are all fixable and the rules catch real Markdown smell.

- MD040 (require code fence language): 0 violations after auto-fix
- MD031 (blanks around fences) / MD032 (blanks around lists): fixed by
  --fix in docs/introduction.md, docs/sqlalchemy.md, CLAUDE.md
- MD034 (no bare URLs): wrapped 4 footer URLs in README.md with <...>

Remaining intentionally-disabled rules:
- MD013 (line length): docs have long URLs and code lines
- MD014 ($ command without output): convention in docs/testing.md, README
- MD024 siblings_only: cursor docs reuse subsection names per cursor
- MD041 (first line H1): MyST `(label)=` ref targets precede the first heading

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

Author: laughingman7743

.markdownlint-cli2.jsonc

@@ -2,7 +2,7 @@
   // https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md
   "config": {
     "default": true,
-    // Line length: docs have long URLs, code blocks, and prose lines
+    // Docs have long URLs and code lines that would be awkward to wrap
     "MD013": false,
     // Match existing style: dash bullets, 2-space nested indent
     "MD004": { "style": "dash" },
@@ -13,16 +13,10 @@
     },
     // 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)
+    // `$ command` style is intentional in docs/testing.md and README shell snippets
     "MD014": false,
-    // Allow bare URLs
-    "MD034": false,
-    // First line need not be a top-level heading (some files start with MyST ref targets)
+    // MyST `(label)=` ref targets must come before the first heading, so the
+    // first line of many docs/*.md files is not an H1
     "MD041": false
   },
   "globs": [

CLAUDE.md

@@ -33,12 +33,14 @@ make test-sqla  # SQLAlchemy dialect tests
 ```
 
 Tests require AWS environment variables. Use a `.env` file (gitignored):
+
 ```bash
 AWS_DEFAULT_REGION=<region>
 AWS_ATHENA_S3_STAGING_DIR=s3://<bucket>/<path>/
 AWS_ATHENA_WORKGROUP=<workgroup>
 AWS_ATHENA_SPARK_WORKGROUP=<spark-workgroup>
 ```
+
 ```bash
 export $(cat .env | xargs) && uv run pytest tests/pyathena/test_file.py -v
 ```
@@ -53,22 +55,24 @@ export $(cat .env | xargs) && uv run pytest tests/pyathena/test_file.py -v
 - **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`
 - **Fixtures**: Cursor/engine fixtures are defined in `conftest.py` and injected by name (e.g., `cursor`, `engine`, `async_cursor`). Use `indirect=True` parametrization to pass connection options:
+
   ```python
   @pytest.mark.parametrize("engine", [{"driver": "rest"}], indirect=True)
   def test_query(self, engine):
       engine, conn = engine
   ```
+
 - **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:
+`markdownlint-cli2` is pinned in `.mise.toml`, so [`mise`](https://mise.jdx.dev/) installs the exact version used in CI. Run locally:
 
 ```bash
-mise install          # one-time: installs node + markdownlint-cli2
+mise install          # one-time: installs markdownlint-cli2
 make docs-lint        # check
 make docs-lint-fix    # auto-fix what's possible
 ```
@@ -88,6 +92,7 @@ Each cursor type lives in its own subpackage (`pandas/`, `arrow/`, `polars/`, `s
 ### 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

README.md

@@ -77,10 +77,10 @@ Many of the implementations in this library are based on [PyHive](https://github
 
 ## Links
 
-- Documentation: https://pyathena.dev/
-- PyPI Releases: https://pypi.org/project/PyAthena/
-- Source Code: https://github.com/pyathena-dev/PyAthena/
-- Issue Tracker: https://github.com/pyathena-dev/PyAthena/issues
+- Documentation: <https://pyathena.dev/>
+- PyPI Releases: <https://pypi.org/project/PyAthena/>
+- Source Code: <https://github.com/pyathena-dev/PyAthena/>
+- Issue Tracker: <https://github.com/pyathena-dev/PyAthena/issues>
 
 ## Logo
 

docs/introduction.md

@@ -35,19 +35,22 @@ 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
 
 **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
 
 **Additional Features:**
+
 - **Connection Management**: Efficient connection pooling and configuration
 - **Result Caching**: Athena query result reuse capabilities
 - **Error Handling**: Comprehensive exception handling and recovery

docs/sqlalchemy.md

@@ -130,6 +130,7 @@ location
   value: s3://bucket/path/to/
 
   Example:
+
   ```python
   Table("some_table", metadata, ..., awsathena_location="s3://bucket/path/to/")
   ```
@@ -140,6 +141,7 @@ compression
   Description: Specifies the compression format.
 
   Value:
+
 - BZIP2
 - DEFLATE
 - GZIP
@@ -151,6 +153,7 @@ compression
 - NONE|UNCOMPRESSED
 
   Example:
+
   ```python
   Table("some_table", metadata, ..., awsathena_compression="SNAPPY")
   ```
@@ -161,6 +164,7 @@ row_format
   Description: Specifies the row format of the table and its underlying source data if applicable.
 
   Value:
+
 - [DELIMITED FIELDS TERMINATED BY char [ESCAPED BY char]]
 - [DELIMITED COLLECTION ITEMS TERMINATED BY char]
 - [MAP KEYS TERMINATED BY char]
@@ -169,6 +173,7 @@ row_format
 - SERDE 'serde_name'
 
   Example:
+
   ```python
   Table("some_table", metadata, ..., awsathena_row_format="SERDE 'org.openx.data.jsonserde.JsonSerDe'")
   ```
@@ -179,6 +184,7 @@ file_format
   Description: Specifies the file format for table data.
 
   Value:
+
 - SEQUENCEFILE
 - TEXTFILE
 - RCFILE
@@ -189,6 +195,7 @@ file_format
 - INPUTFORMAT input_format_classname OUTPUTFORMAT output_format_classname
 
   Example:
+
   ```python
   Table("some_table", metadata, ..., awsathena_file_format="PARQUET")
   Table("some_table", metadata, ..., awsathena_file_format="INPUTFORMAT 'org.apache.hadoop.hive.ql.io.parquet.MapredParquetInputFormat' OUTPUTFORMAT 'org.apache.hadoop.hive.ql.io.parquet.MapredParquetOutputFormat'")
@@ -200,11 +207,13 @@ serdeproperties
   Description: Specifies one or more custom properties allowed in SerDe.
 
   Value:
+
   ```python
   { "property_name": "property_value", "property_name": "property_value", ... }
   ```
 
   Example:
+
   ```python
   Table("some_table", metadata, ..., awsathena_serdeproperties={
       "separatorChar": ",", "escapeChar": "\\\\"
@@ -217,11 +226,13 @@ tblproperties
   Description: Specifies custom metadata key-value pairs for the table definition in addition to predefined table properties.
 
   Value:
+
   ```python
   { "property_name": "property_value", "property_name": "property_value", ... }
   ```
 
   Example:
+
   ```python
   Table("some_table", metadata, ..., awsathena_tblproperties={
       "projection.enabled": "true",
@@ -239,6 +250,7 @@ bucket_count
   Value: Integer value greater than or equal to 0
 
   Example:
+
   ```python
   Table("some_table", metadata, ..., awsathena_bucket_count=5)
   ```
@@ -268,6 +280,7 @@ partition
   Value: True / False
 
   Example:
+
   ```python
   Column("some_column", types.String, ..., awsathena_partition=True)
   ```
@@ -279,6 +292,7 @@ partition_transform
   Only has an effect for ICEBERG tables and when partition is set to true for the column.
 
   Value:
+
 - year
 - month
 - day
@@ -287,6 +301,7 @@ partition_transform
 - truncate
 
   Example:
+
   ```python
   Column("some_column", types.Date, ..., awsathena_partition=True, awsathena_partition_transform='year')
   ```
@@ -301,6 +316,7 @@ partition_transform_bucket_count
   Value: Integer value greater than or equal to 0
 
   Example:
+
   ```python
   Column("some_column", types.String, ..., awsathena_partition=True, awsathena_partition_transform='bucket', awsathena_partition_transform_bucket_count=5)
   ```
@@ -315,6 +331,7 @@ partition_transform_truncate_length
   Value: Integer value greater than or equal to 0
 
   Example:
+
   ```python
   Column("some_column", types.String, ..., awsathena_partition=True, awsathena_partition_transform='truncate', awsathena_partition_transform_truncate_length=5)
   ```
@@ -327,6 +344,7 @@ cluster
   Value: True / False
 
   Example:
+
   ```python
   Column("some_column", types.String, ..., awsathena_cluster=True)
   ```