docs: publish documentation site

.github/workflows/docs.yml

@@ -0,0 +1,75 @@
+name: Documentation
+
+on:
+  pull_request:
+    branches:
+      - main
+    paths:
+      - ".github/workflows/docs.yml"
+      - "docs/**"
+      - "mkdocs.yml"
+      - "requirements-docs.txt"
+  push:
+    branches:
+      - main
+    paths:
+      - ".github/workflows/docs.yml"
+      - "docs/**"
+      - "mkdocs.yml"
+      - "requirements-docs.txt"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build documentation
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.14"
+          cache: pip
+          cache-dependency-path: requirements-docs.txt
+
+      - name: Install documentation dependencies
+        run: python -m pip install --requirement requirements-docs.txt
+
+      - name: Configure GitHub Pages
+        if: github.ref == 'refs/heads/main'
+        uses: actions/configure-pages@v6
+
+      - name: Build documentation
+        run: mkdocs build --strict --site-dir site
+
+      - name: Upload GitHub Pages artifact
+        if: github.ref == 'refs/heads/main'
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: site
+
+  deploy:
+    name: Deploy documentation
+    if: github.ref == 'refs/heads/main'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v5

README.md

@@ -9,7 +9,7 @@
 ![PyPI - Python Version](https://img.shields.io/pypi/pyversions/python-mlb-statsapi)
 ![GitHub](https://img.shields.io/github/license/zero-sum-seattle/python-mlb-statsapi)
 
-### [Wiki](https://github.com/zero-sum-seattle/python-mlb-statsapi/wiki) | [Methods](docs/methods.md) | [Examples](docs/examples.md) | [Stats](docs/stats.md) | [Async](docs/async.md) | [Public API](docs/public-api.md) | [MLB Stats API](https://statsapi.mlb.com/)
+### [Docs](https://zero-sum-seattle.github.io/python-mlb-statsapi/) | [Methods](https://zero-sum-seattle.github.io/python-mlb-statsapi/methods/) | [Examples](https://zero-sum-seattle.github.io/python-mlb-statsapi/examples/) | [Stats](https://zero-sum-seattle.github.io/python-mlb-statsapi/stats/) | [Async](https://zero-sum-seattle.github.io/python-mlb-statsapi/async/) | [Public API](https://zero-sum-seattle.github.io/python-mlb-statsapi/public-api/) | [MLB Stats API](https://statsapi.mlb.com/)
 
 </div>
 
@@ -46,7 +46,7 @@ The async extra installs HTTPX. Python 3.10 or newer is required.
 | Minimum Python version | `>=3.10` |
 | CI-validated versions | Python 3.10 through 3.14 (`3.10`, `3.11`, `3.12`, `3.13`, `3.14`) |
 
-See [Python support](docs/public-api.md#python-support) for the complete policy.
+See [Python support](https://zero-sum-seattle.github.io/python-mlb-statsapi/public-api/#python-support) for the complete policy.
 
 ## Quick Start
 
@@ -126,7 +126,7 @@ async def main():
 asyncio.run(main())
 ```
 
-See [Async usage](docs/async.md) for lifecycle, concurrency, custom HTTPX clients, and the current async endpoint list.
+See [Async usage](https://zero-sum-seattle.github.io/python-mlb-statsapi/async/) for lifecycle, concurrency, custom HTTPX clients, and the current async endpoint list.
 
 ## Sync or Async?
 
@@ -139,7 +139,7 @@ See [Async usage](docs/async.md) for lifecycle, concurrency, custom HTTPX client
 
 `AsyncMlb` mirrors the full endpoint surface of `Mlb`. Both clients return the same Pydantic models and follow the same public HTTP/error behavior.
 
-See the [public API contract](docs/public-api.md#asyncmlb-public-client) for the authoritative method list and signatures.
+See the [public API contract](https://zero-sum-seattle.github.io/python-mlb-statsapi/public-api/#asyncmlb-public-client) for the authoritative method list and signatures.
 
 ## Concurrent Async Requests
 
@@ -188,21 +188,21 @@ team_ids = mlb.get_team_id("Seattle Mariners")
 
 ### Stats
 
-The stats API has several entry points and returns a nested `stats[group][type]` structure. See the dedicated [Stats Guide](docs/stats.md) for `get_player_stats()`, `get_team_stats()`, `get_stats()`, and `get_players_stats_for_game()` examples using both `Mlb` and `AsyncMlb`.
+The stats API has several entry points and returns a nested `stats[group][type]` structure. See the dedicated [Stats Guide](https://zero-sum-seattle.github.io/python-mlb-statsapi/stats/) for `get_player_stats()`, `get_team_stats()`, `get_stats()`, and `get_players_stats_for_game()` examples using both `Mlb` and `AsyncMlb`.
 
 ### Schedule
 
 ```python
 schedule = mlb.get_schedule(date="2022-10-13")
 ```
 
-See the [method reference](docs/methods.md) for the full method documentation that previously lived in the README. Longer runnable examples live in [docs/examples.md](docs/examples.md).
+See the [method reference](https://zero-sum-seattle.github.io/python-mlb-statsapi/methods/) for the full method documentation that previously lived in the README. Longer runnable examples live in the [usage examples](https://zero-sum-seattle.github.io/python-mlb-statsapi/examples/).
 
 ## HTTP and Error Behavior
 
 Both clients use explicit timeouts, structured exceptions, and pooled HTTP connections. `strict_http=True` is the default. Final non-404 4xx responses raise `MlbHttpError`, while existing endpoint-specific 404 behavior is preserved.
 
-Library-created clients send a versioned User-Agent. The current package version sends `python-mlb-statsapi/1.1.0`. See the [HTTP transport documentation](docs/http-transport.md) for the full transport contract.
+Library-created clients send a versioned User-Agent. The current package version sends `python-mlb-statsapi/1.1.0`. See the [HTTP transport documentation](https://zero-sum-seattle.github.io/python-mlb-statsapi/http-transport/) for the full transport contract.
 
 The main transport exceptions are:
 
@@ -223,7 +223,7 @@ except MlbHttpError as exc:
     print(exc.status_code, exc.reason)
 ```
 
-For timeouts, retries, compatibility mode, ownership rules, and transport details, see [docs/http-transport.md](docs/http-transport.md).
+For timeouts, retries, compatibility mode, ownership rules, and transport details, see the [HTTP transport documentation](https://zero-sum-seattle.github.io/python-mlb-statsapi/http-transport/).
 
 ## Working with Models
 
@@ -244,14 +244,14 @@ print(player.model_dump_json(indent=2))
 
 | Document | Contents |
 | --- | --- |
-| [Wiki](https://github.com/zero-sum-seattle/python-mlb-statsapi/wiki) | Endpoint reference, return objects, and model documentation |
-| [Method reference](docs/methods.md) | Method signatures and short descriptions from the original README reference |
-| [Usage examples](docs/examples.md) | Extended synchronous examples |
-| [Stats guide](docs/stats.md) | Player, team, general, and per-game stat queries with sync and async examples |
-| [Async usage](docs/async.md) | Async installation, lifecycle, concurrency, and examples |
-| [HTTP transport](docs/http-transport.md) | Timeouts, retries, strict HTTP, exceptions, and ownership |
-| [Public API contract](docs/public-api.md) | Supported symbols, signatures, endpoint methods, and stability policy |
-| [Release notes](docs/releases/) | Release-specific changes and migration notes |
+| [Documentation home](https://zero-sum-seattle.github.io/python-mlb-statsapi/) | Installation, quick starts, and links to every guide |
+| [Method reference](https://zero-sum-seattle.github.io/python-mlb-statsapi/methods/) | Method signatures and short descriptions from the original README reference |
+| [Usage examples](https://zero-sum-seattle.github.io/python-mlb-statsapi/examples/) | Extended synchronous examples |
+| [Stats guide](https://zero-sum-seattle.github.io/python-mlb-statsapi/stats/) | Player, team, general, and per-game stat queries with sync and async examples |
+| [Async usage](https://zero-sum-seattle.github.io/python-mlb-statsapi/async/) | Async installation, lifecycle, concurrency, and examples |
+| [HTTP transport](https://zero-sum-seattle.github.io/python-mlb-statsapi/http-transport/) | Timeouts, retries, strict HTTP, exceptions, and ownership |
+| [Public API contract](https://zero-sum-seattle.github.io/python-mlb-statsapi/public-api/) | Supported symbols, signatures, endpoint methods, and stability policy |
+| [Release notes](https://zero-sum-seattle.github.io/python-mlb-statsapi/releases/) | Release-specific changes and migration notes |
 
 ## Contributing
 

docs/async.md

@@ -225,7 +225,7 @@ behavior.
 
 ## Documentation boundaries
 
-- [README](../README.md) — installation and quick-start examples
+- [Documentation home](index.md) — installation and quick-start examples
 - [Usage examples](examples.md) — longer synchronous examples
 - [Public API contract](public-api.md) — supported symbols, signatures, and endpoint coverage
 - [HTTP transport](http-transport.md) — timeouts, retries, errors, and compatibility behavior

docs/index.md

@@ -0,0 +1,85 @@
+# Python MLB Stats API
+
+`python-mlb-statsapi` is a Python client for MLB's Stats API with synchronous and asynchronous interfaces.
+
+[View usage examples](examples.md){ .md-button .md-button--primary }
+[Browse the method reference](methods.md){ .md-button }
+
+<div class="grid cards" markdown>
+
+-   **Broad API coverage**
+
+    Query teams, players, schedules, games, statistics, and more.
+
+-   **Pythonic models**
+
+    Work with [Pydantic](https://docs.pydantic.dev/) objects whose fields use `snake_case` names.
+
+-   **Sync and async**
+
+    Choose the synchronous `Mlb` client or the asynchronous `AsyncMlb` client. Existing sync users can upgrade without changing their code.
+
+</div>
+
+## Installation
+
+Install the synchronous client:
+
+```bash
+python3 -m pip install python-mlb-statsapi
+```
+
+Install the optional `async` extra to use `AsyncMlb` and `AsyncMlbDataAdapter`:
+
+```bash
+python3 -m pip install "python-mlb-statsapi[async]"
+```
+
+Python 3.10 or newer is required.
+
+## Quick start
+
+### Synchronous client
+
+```python
+from mlbstatsapi import Mlb
+
+with Mlb() as mlb:
+    player = mlb.get_person(664034)
+    team = mlb.get_team(136)
+
+print(player.full_name)
+print(team.name)
+```
+
+### Asynchronous client
+
+```python
+import asyncio
+
+from mlbstatsapi import AsyncMlb
+
+
+async def main():
+    async with AsyncMlb() as mlb:
+        player = await mlb.get_person(664034)
+        team = await mlb.get_team(136)
+
+        print(player.full_name)
+        print(team.name)
+
+
+asyncio.run(main())
+```
+
+## Explore the documentation
+
+- [Usage examples](examples.md) cover common synchronous workflows.
+- [Stats guide](stats.md) explains player, team, general, and per-game statistics.
+- [Async usage](async.md) covers lifecycle, concurrency, custom HTTPX clients, and endpoint support.
+- [Method reference](methods.md) lists the available endpoint methods.
+- [HTTP transport](http-transport.md) documents timeouts, retries, errors, proxies, and ownership.
+- [Public API contract](public-api.md) defines supported symbols and compatibility guarantees.
+- [Release notes](releases.md) summarize each published version.
+
+> **Unofficial project.** This package and its authors are not affiliated with or endorsed by Major League Baseball or any MLB team. Use of MLB data is subject to [MLB's copyright notice](https://gdx.mlb.com/components/copyright.txt). This is an educational project—not for commercial use.

docs/releases.md

@@ -0,0 +1,13 @@
+# Release Notes
+
+Release notes describe user-visible changes, compatibility guidance, and validation performed for each published version.
+
+## Releases
+
+- [1.1.0](releases/1.1.0.md) — first-class asynchronous client support
+- [1.0.1](releases/1.0.1.md) — packaging and Python support corrections
+- [1.0.0](releases/1.0.0.md) — strict HTTP behavior by default and a stable public API contract
+- [0.9.0](releases/0.9.0.md) — public retry policy, richer HTTP errors, and compatibility warnings
+- [0.8.0](releases/0.8.0.md) — shared sessions, explicit timeouts, retries, and structured exceptions
+- [0.7.1](releases/0.7.1.md) — Pydantic v2 migration and Pythonic model fields
+

mkdocs.yml

@@ -0,0 +1,76 @@
+site_name: Python MLB Stats API
+site_description: Unofficial Python client for MLB's Stats API with synchronous and asynchronous interfaces.
+site_url: https://zero-sum-seattle.github.io/python-mlb-statsapi/
+repo_url: https://github.com/zero-sum-seattle/python-mlb-statsapi
+repo_name: zero-sum-seattle/python-mlb-statsapi
+edit_uri: edit/main/docs/
+copyright: Unofficial project. Not affiliated with Major League Baseball or any MLB team.
+
+theme:
+  name: material
+  language: en
+  features:
+    - content.action.edit
+    - content.action.view
+    - content.code.copy
+    - navigation.footer
+    - navigation.instant
+    - navigation.sections
+    - navigation.top
+    - search.highlight
+    - search.share
+  palette:
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: indigo
+      accent: red
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: indigo
+      accent: red
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+
+nav:
+  - Home: index.md
+  - Guides:
+      - Usage Examples: examples.md
+      - Stats Guide: stats.md
+      - Async Usage: async.md
+  - Reference:
+      - Method Reference: methods.md
+      - HTTP Transport: http-transport.md
+      - Public API Contract: public-api.md
+  - Release Notes:
+      - Overview: releases.md
+      - 1.1.0: releases/1.1.0.md
+      - 1.0.1: releases/1.0.1.md
+      - 1.0.0: releases/1.0.0.md
+      - 0.9.0: releases/0.9.0.md
+      - 0.8.0: releases/0.8.0.md
+      - 0.7.1: releases/0.7.1.md
+
+plugins:
+  - search
+
+markdown_extensions:
+  - admonition
+  - attr_list
+  - md_in_html
+  - tables
+  - toc:
+      permalink: true
+  - pymdownx.highlight:
+      anchor_linenums: true
+  - pymdownx.inlinehilite
+  - pymdownx.superfences
+
+validation:
+  omitted_files: warn
+  absolute_links: warn
+  unrecognized_links: warn
+  anchors: warn

requirements-docs.txt

@@ -0,0 +1,3 @@
+mkdocs==1.6.1
+mkdocs-material==9.7.7
+