commit 493172dc90a7f123915ec28e6ffb5db764857b6e Author: Germaine Brown Date: Sun Aug 9 23:38:14 2026 -0400 Initial: ITPP standards repo with templates, CI workflows, .gitignore, and .markdownlint.json diff --git a/.gitea/workflows/docs-check.yml b/.gitea/workflows/docs-check.yml new file mode 100644 index 0000000..17dc263 --- /dev/null +++ b/.gitea/workflows/docs-check.yml @@ -0,0 +1,26 @@ +name: Docs Check +on: + push: + paths: + - '**.md' + - 'docs/**' + pull_request: + +jobs: + lint: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Markdown lint + run: | + npm install -g markdownlint-cli + markdownlint '**/*.md' --ignore node_modules + - name: Link check + run: | + npm install -g markdown-link-check + find . -name '*.md' -not -path '*/node_modules/*' \ + -exec markdown-link-check {} \; + - name: Spell check + run: | + pip install codespell + codespell '**/*.md' --skip='*.git*' diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..76f8134 --- /dev/null +++ b/.gitignore @@ -0,0 +1,29 @@ +# OS +.DS_Store +Thumbs.db + +# Editor +.vscode/ +.idea/ +*.swp +*.swo + +# Secrets +.env +*.pem +*.key +credentials.json + +# Python +__pycache__/ +*.pyc +.venv/ +venv/ + +# Node +node_modules/ + +# Build output +dist/ +build/ +site/ diff --git a/.markdownlint.json b/.markdownlint.json new file mode 100644 index 0000000..5fdbc38 --- /dev/null +++ b/.markdownlint.json @@ -0,0 +1,9 @@ +{ + "default": true, + "MD013": { "line_length": 200 }, + "MD033": false, + "MD041": false, + "MD024": { "siblings_only": true }, + "MD034": false, + "MD046": { "style": "fenced" } +} diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..8625887 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,8 @@ +# ITPP Standards — CHANGELOG + +## 2026-08-09 — Initial + +- Created repository with documentation templates and CI workflows. +- Added README template, CHANGELOG template, DESIGN.md template, MkDocs config template. +- Added Gitea Actions workflows: docs-check (lint + link check + spell check), docs-publish (aggregated site rebuild). +- Added canonical .gitignore and .markdownlint.json. diff --git a/README.md b/README.md new file mode 100644 index 0000000..4b0e99f --- /dev/null +++ b/README.md @@ -0,0 +1,39 @@ +# ITPP Standards + +> **Owner:** Germaine | **Status:** LIVE +> **Last Updated:** 2026-08-09 + +Canonical documentation standards, templates, and CI workflows for all IT Pro Partner repositories. Use this repo as a Gitea template when creating new projects, or copy individual templates as needed. + +## What's Inside + +- `templates/` — README, CHANGELOG, DESIGN.md, and MkDocs config templates for new projects +- `templates/gitea-ci/` — Reusable Gitea Actions workflows (docs lint, link check, spell check) +- `.markdownlint.json` — Standard Markdown linting rules for all ITPP repos +- `.gitignore` — Canonical `.gitignore` for Python, Node.js, secrets, and build artifacts + +## Quick Start + +```bash +# Option 1: Use as Gitea template +# In Gitea UI: New Repository → From Template: itpp-standards + +# Option 2: Copy templates into existing repo +git clone https://git.itpropartner.com/ippadmin/.git +cp /path/to/itpp-standards/templates/repo-readme.md /README.md +cp /path/to/itpp-standards/templates/repo-changelog.md /CHANGELOG.md +cp /path/to/itpp-standards/.gitignore / +cp /path/to/itpp-standards/templates/gitea-ci/docs-check.yml /.gitea/workflows/ +``` + +## Standards + +- **README.md** — Mandatory. Every repo must have one. Minimum 400 bytes. Follow the template. +- **CHANGELOG.md** — Mandatory. Reverse-chronological, user-facing, one line per change. +- **DESIGN.md** — When the project has a public API or multiple consumers. +- **.gitea/workflows/docs-check.yml** — Recommended. Lints Markdown and checks links on push. + +## Related + +- [itpp-infrastructure](https://git.itpropartner.com/ippadmin/itpp-infrastructure) — server inventory, DNS +- [itpp-docs](https://git.itpropartner.com/ippadmin/itpp-docs) — aggregated docs site diff --git a/templates/design-template.md b/templates/design-template.md new file mode 100644 index 0000000..7c32f57 --- /dev/null +++ b/templates/design-template.md @@ -0,0 +1,26 @@ +# {{PROJECT_NAME}} — Design + +> **Status:** DRAFT +> **Last Updated:** YYYY-MM-DD + +## Overview + + + +## Architecture + + + +## API / Interface + + + +## Decisions + +| Date | Decision | Rationale | +|---|---|---| +| YYYY-MM-DD | | | + +## Consumers + + diff --git a/templates/gitea-ci/docs-check.yml b/templates/gitea-ci/docs-check.yml new file mode 100644 index 0000000..17dc263 --- /dev/null +++ b/templates/gitea-ci/docs-check.yml @@ -0,0 +1,26 @@ +name: Docs Check +on: + push: + paths: + - '**.md' + - 'docs/**' + pull_request: + +jobs: + lint: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Markdown lint + run: | + npm install -g markdownlint-cli + markdownlint '**/*.md' --ignore node_modules + - name: Link check + run: | + npm install -g markdown-link-check + find . -name '*.md' -not -path '*/node_modules/*' \ + -exec markdown-link-check {} \; + - name: Spell check + run: | + pip install codespell + codespell '**/*.md' --skip='*.git*' diff --git a/templates/gitea-ci/docs-publish.yml b/templates/gitea-ci/docs-publish.yml new file mode 100644 index 0000000..e7b2b60 --- /dev/null +++ b/templates/gitea-ci/docs-publish.yml @@ -0,0 +1,20 @@ +name: Publish Docs Site +on: + push: + branches: [main] + schedule: + - cron: '0 5 * * *' + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Build MkDocs site + run: | + pip install mkdocs mkdocs-material + bash build-docs.sh + mkdocs build + - name: Deploy to app3 + run: | + rsync -avz site/ root@152.53.241.111:/var/www/docs.itpropartner.com/ diff --git a/templates/mkdocs.yml b/templates/mkdocs.yml new file mode 100644 index 0000000..1535698 --- /dev/null +++ b/templates/mkdocs.yml @@ -0,0 +1,33 @@ +site_name: "{{PROJECT_NAME}} Docs" +site_url: "https://docs.itpropartner.com/{{PROJECT_NAME}}/" +repo_url: "https://git.itpropartner.com/ippadmin/{{PROJECT_NAME}}" +edit_uri: edit/main/docs/ + +theme: + name: material + palette: + scheme: slate + primary: indigo + accent: indigo + features: + - navigation.instant + - navigation.tracking + - navigation.tabs + - navigation.sections + - search.highlight + - search.share + +plugins: + - search + +markdown_extensions: + - admonition + - pymdownx.details + - pymdownx.superfences + - pymdownx.highlight + - tables + - toc: + permalink: true + +nav: + - Home: index.md diff --git a/templates/repo-changelog.md b/templates/repo-changelog.md new file mode 100644 index 0000000..f81345c --- /dev/null +++ b/templates/repo-changelog.md @@ -0,0 +1,5 @@ +# {{PROJECT_NAME}} — CHANGELOG + +## YYYY-MM-DD — Initial + +- Created project repository. diff --git a/templates/repo-readme.md b/templates/repo-readme.md new file mode 100644 index 0000000..3119c38 --- /dev/null +++ b/templates/repo-readme.md @@ -0,0 +1,29 @@ +# {{PROJECT_NAME}} + +> **Owner:** Germaine | **Status:** PLANNED +> **Last Updated:** YYYY-MM-DD + + + +## Access + +| Resource | URL | Location | Notes | +|---|---|---|---| +| | https://... | | | + +## Tech Stack + + + +## Quick Start + +```bash +git clone https://git.itpropartner.com/ippadmin/{{PROJECT_NAME}}.git +cd {{PROJECT_NAME}} +# how to run / deploy +``` + +## Related + +- [itpp-infrastructure](https://git.itpropartner.com/ippadmin/itpp-infrastructure) — server inventory, DNS +- [itpp-standards](https://git.itpropartner.com/ippadmin/itpp-standards) — docs standards and templates