diff --git a/README.md b/README.md index 00a3943..53298c9 100644 --- a/README.md +++ b/README.md @@ -1,27 +1,82 @@

- + CMBA logo

-# 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. diff --git a/docs/index.md b/docs/index.md index 2aa117b..7d5ca61 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1 +1,34 @@ +

+ CMBA logo +

# 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.