update readme, index

2026-02-28 09:53:37 -06:00
parent c16e25a738
commit 5167aef0b8
2 changed files with 99 additions and 11 deletions
--- a/README.md
+++ b/README.md
@@ -1,27 +1,82 @@
 <p align="center">
-<img src="docs/assets/cmba-logo.svg" width="200">
+  <img src="docs/assets/cmba-logo.svg" width="200" alt="CMBA logo">
 </p>

-# CMBA Bylaws, Policies, and Playing rules
+# CMBA Bylaws, Policy, and Playing Rules

-The Constitution and Bylaws for the baseball league known as the [Chicago Metropolitan Baseball Association (CMBA)](#about-the-cmba).
+This repository contains the governing documents for the Chicago Metropolitan Baseball Association (CMBA) in Markdown form, along with the MkDocs configuration used to publish them as a static documentation site.

-The source text for this document can be found in Markdown format in [src/cmba-bylaws.md](src/cmba-bylaws.md).
+## Repository Layout

-## Building from source
+- `docs/index.md`: site home page
+- `docs/01-bylaws.md`: league bylaws
+- `docs/02-policy.md`: league policy
+- `docs/03-playing-rules.md`: playing rules
+- `mkdocs/mkdocs.yml`: MkDocs site configuration
+- `mkdocs/requirements.txt`: Python packages required to build the site
+- `tools/build.sh`: production build script
+- `tools/spellcheck/`: CSpell configuration and custom baseball dictionary
+
+## Local Development

 ### Requirements

-### Steps
+- Python 3
+- `pip`

-## Project history
+### Install Dependencies

-The constitution and bylaws were modernized in 2021, using Google Docs. This project brings that effort into Git and Github. Previous commits show a generated plain-text history of the changes prior to this project (thanks to [gitdriver](https://github.com/larsks/gitdriver)), with the first being the version from 2016.
+```bash
+python3 -m pip install -r mkdocs/requirements.txt
+```

-## Spell-checking
+### Preview the Site Locally

-## GitHub Pages
+```bash
+mkdocs serve -f mkdocs/mkdocs.yml
+```
+
+MkDocs serves the site locally and watches the Markdown files under `docs/` for changes.
+
+## Editing Guidance
+
+- Keep the canonical text in the Markdown files under `docs/`.
+- Preserve the separation between bylaws, policy, and playing rules.
+- Use the local preview server when editing headings, internal links, or cross-references.
+- Update `tools/spellcheck/baseball-words.txt` when league-specific terminology is flagged by CSpell.
+
+## Publishing
+
+Publishing is driven by GitHub Actions.
+
+### `ci-docs`
+
+The `.github/workflows/ci-docs.yml` workflow runs on pushes to `main`, `draft`, and `release-candidate`, and can also be started manually.
+
+It performs the non-publishing validation steps:
+
+- spellchecks `docs/**/*.md` and `README.md` with CSpell
+- installs the MkDocs dependencies from `mkdocs/requirements.txt`
+- runs a MkDocs build using `mkdocs/mkdocs.yml`
+
+### `release`
+
+The `.github/workflows/release.yml` workflow runs on pushed tags matching `draft*`, `rc*`, and `v*`, and can also be started manually.
+
+It builds both the normal site and an offline site package, then publishes based on the tag prefix:
+
+- `draft*`: creates a GitHub prerelease, attaches the offline zip and generated `.docx`, and deploys the preview site to the `gh-pages` branch under `/draft/`
+- `rc*`: creates a GitHub prerelease, attaches the offline zip and generated `.docx`, and deploys the preview site to the `gh-pages` branch under `/rc/`
+- `v*`: creates a GitHub release, attaches the offline zip, and deploys the release site to the root of the `gh-pages` branch
+
+In all cases, the release workflow uses the same MkDocs configuration in `mkdocs/mkdocs.yml`, with strict mode controlled by the `MKDOCS_STRICT` GitHub Actions variable.
+
+## Project History
+
+The constitution and bylaws were re-architected in 2026 into the CMBA Bylaws, Policy, and Playing Rules.
+
+The constitution and bylaws were modernized in 2021 using Google Docs. This project brings that work into Git and GitHub. Earlier commits preserve generated plain-text history of prior revisions, with the earliest tracked version dating to 2016.

 ## About the CMBA
-This baseball league known as the [Chicago Metropolitan Baseball Association (CMBA)](http://cmbabaseball.com) has been formed for the purpose of providing the finest amateur baseball league in the State of Illinois and Midwest; a league where an up and coming young prospect for professional baseball may play and develop; where the talented veteran player can enjoy playing among the best competition; and bring friendship and sportsmanship to the Association.

+The [Chicago Metropolitan Baseball Association](http://cmbabaseball.com) exists to provide a high-level amateur baseball league in Illinois and the Midwest, where developing players and veteran players can compete in a strong environment centered on baseball, sportsmanship, and community.
--- a/docs/index.md
+++ b/docs/index.md
@@ -1 +1,34 @@
+<p>
+  <img src="assets/cmba-logo.svg" width="300" alt="CMBA logo">
+</p>
 # CMBA Bylaws, Policy, and Playing Rules
+
+Welcome to the governing documents for the Chicago Metropolitan Baseball Association.
+
+This site brings together the league's core rules in a single place so managers, players, and league officials can quickly find the current governing text.
+
+## Documents
+
+- [League Bylaws](01-bylaws.md): the league's organizational structure, board authority, membership framework, meetings, and amendment process
+- [League Policy](02-policy.md): league operations, procedures, discipline, administration, and competition governance
+- [Playing Rules](03-playing-rules.md): on-field rules, lineup formats, game administration, and incorporated baseball rules
+
+## How to Use This Site
+
+- Start with the Bylaws for questions about league authority, governance, and membership.
+- Use League Policy for operational questions, discipline, roster administration, and league procedures.
+- Use Playing Rules for game-day and on-field questions.
+
+## Rule Hierarchy
+
+If documents overlap or appear to conflict, the controlling order is generally:
+
+1. Bylaws
+2. League Policy
+3. Playing Rules
+
+For on-field administration, the Playing Rules also incorporate the Official Baseball Rules of Major League Baseball except where CMBA rules provide otherwise.
+
+## About the CMBA
+
+The Chicago Metropolitan Baseball Association exists to provide strong amateur baseball competition in Illinois and the Midwest, with an emphasis on competitive play, sportsmanship, and league continuity.