Skip to content

Commit 3124b6c

Browse files
RedjiJBRedjiJB
committed
docs: complete Phase 3 standard numbered docs structure alongside MkDocs
- Create docs/01-core/ with 7 category architecture spec docs (identity, database, collaboration, communications, business, it-management, infrastructure) - Create docs/02-implementation/ - deployment and integration guides - Create docs/03-labs/ - lab manuals parts 1-5 - Create docs/04-github/ - GitHub org setup guide - Create docs/05-guides/ - master index, lab structure, framework - Create docs/06-technical-reference/ - full technical reference - Create docs/07-architecture/README.md - ADR index - Create docs/README.md - documentation navigation index - Add build-standard-docs.ps1 and create-category-specs.ps1 scripts - Update docs/project/todo.md to mark Phase 3 fully complete MkDocs site (docs website) is unchanged and still auto-deploys. Numbered structure is for direct repo browsing on GitHub.
1 parent 4e065e7 commit 3124b6c

26 files changed

+26666
-4
lines changed

‎build-standard-docs.ps1‎

Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
#!/usr/bin/env pwsh
2+
# build-standard-docs.ps1
3+
# Creates the standard numbered docs/* folder structure alongside the MkDocs structure.
4+
# Copies files from their MkDocs locations into numbered paths with YAML front-matter.
5+
6+
$root = "C:\IT-Stack"
7+
$docs = "$root\docs"
8+
9+
# ── 1. Create all directories ──────────────────────────────────────────────────
10+
$dirs = @(
11+
"01-core",
12+
"02-implementation",
13+
"03-labs",
14+
"04-github",
15+
"05-guides",
16+
"06-technical-reference",
17+
"07-architecture"
18+
)
19+
foreach ($d in $dirs) {
20+
$null = New-Item -ItemType Directory -Path "$docs\$d" -Force
21+
Write-Host " mkdir docs/$d" -ForegroundColor DarkGray
22+
}
23+
24+
# ── 2. Helper: copy file and prepend front-matter ──────────────────────────────
25+
function Copy-WithFrontMatter {
26+
param (
27+
[string]$Source, # relative to $docs, e.g. "project/master-index.md"
28+
[string]$Dest, # relative to $docs, e.g. "05-guides/01-master-index.md"
29+
[int] $DocNumber,
30+
[string]$Category,
31+
[string]$Title
32+
)
33+
$srcPath = "$docs\$($Source.Replace('/','\'))"
34+
$destPath = "$docs\$($Dest.Replace('/','\'))"
35+
if (-not (Test-Path $srcPath)) {
36+
Write-Host " [SKIP] Source not found: $srcPath" -ForegroundColor Yellow
37+
return
38+
}
39+
$original = Get-Content $srcPath -Raw -Encoding UTF8
40+
$frontmatter = @"
41+
---
42+
doc: $('{0:D2}' -f $DocNumber)
43+
title: "$Title"
44+
category: $Category
45+
date: 2026-02-27
46+
source: $Source
47+
---
48+
49+
"@
50+
# Don't double-add front-matter if it already has one
51+
if ($original -notmatch '^---') {
52+
$content = $frontmatter + $original
53+
} else {
54+
$content = $original
55+
}
56+
Set-Content -Path $destPath -Value $content -Encoding UTF8 -NoNewline
57+
Write-Host " [OK] docs/$Dest" -ForegroundColor Green
58+
}
59+
60+
# ── 3. Copy & number all existing documents ────────────────────────────────────
61+
Write-Host "`n==> Copying and numbering documents" -ForegroundColor Cyan
62+
63+
Copy-WithFrontMatter `
64+
-Source "project/master-index.md" `
65+
-Dest "05-guides/01-master-index.md" `
66+
-DocNumber 1 -Category "guides" `
67+
-Title "Master Index & Reading Guide"
68+
69+
Copy-WithFrontMatter `
70+
-Source "labs/overview.md" `
71+
-Dest "05-guides/02-lab-manual-structure.md" `
72+
-DocNumber 2 -Category "guides" `
73+
-Title "Lab Manual Structure & Methodology"
74+
75+
Copy-WithFrontMatter `
76+
-Source "deployment/lab-deployment.md" `
77+
-Dest "02-implementation/03-lab-deployment-plan.md" `
78+
-DocNumber 3 -Category "implementation" `
79+
-Title "Lab Deployment Plan"
80+
81+
# Doc 04 was a duplicate (lab-deployment-plan(1).md) — removed; placeholder retained
82+
$placeholder04 = @"
83+
---
84+
doc: 04
85+
title: "Lab Deployment Plan v2 (merged)"
86+
category: implementation
87+
date: 2026-02-27
88+
note: "Duplicate of doc 03 — content merged into 02-implementation/03-lab-deployment-plan.md"
89+
---
90+
91+
> **Note:** This document slot was previously occupied by a duplicate deployment plan.
92+
> The canonical document is [03-lab-deployment-plan.md](03-lab-deployment-plan.md).
93+
"@
94+
Set-Content "$docs\02-implementation\04-lab-deployment-plan-v2.md" $placeholder04 -Encoding UTF8
95+
Write-Host " [OK] docs/02-implementation/04-lab-deployment-plan-v2.md (placeholder)" -ForegroundColor DarkYellow
96+
97+
Copy-WithFrontMatter `
98+
-Source "deployment/enterprise-reference.md" `
99+
-Dest "06-technical-reference/05-stack-deployment.md" `
100+
-DocNumber 5 -Category "technical-reference" `
101+
-Title "Enterprise IT Stack Deployment Reference"
102+
103+
Copy-WithFrontMatter `
104+
-Source "architecture/overview.md" `
105+
-Dest "02-implementation/06-stack-complete-v2.md" `
106+
-DocNumber 6 -Category "implementation" `
107+
-Title "Enterprise Stack Complete v2 — 8-Server Architecture"
108+
109+
Copy-WithFrontMatter `
110+
-Source "labs/part1-network-os.md" `
111+
-Dest "03-labs/07-lab-manual-part1.md" `
112+
-DocNumber 7 -Category "labs" `
113+
-Title "Lab Manual Part 1: Network & OS Setup"
114+
115+
Copy-WithFrontMatter `
116+
-Source "labs/part2-identity-database.md" `
117+
-Dest "03-labs/08-lab-manual-part2.md" `
118+
-DocNumber 8 -Category "labs" `
119+
-Title "Lab Manual Part 2: Identity, Database & SSO"
120+
121+
Copy-WithFrontMatter `
122+
-Source "labs/part3-collaboration.md" `
123+
-Dest "03-labs/09-lab-manual-part3.md" `
124+
-DocNumber 9 -Category "labs" `
125+
-Title "Lab Manual Part 3: Collaboration"
126+
127+
Copy-WithFrontMatter `
128+
-Source "labs/part4-communications.md" `
129+
-Dest "03-labs/10-lab-manual-part4.md" `
130+
-DocNumber 10 -Category "labs" `
131+
-Title "Lab Manual Part 4: Communications"
132+
133+
Copy-WithFrontMatter `
134+
-Source "labs/part5-business-management.md" `
135+
-Dest "03-labs/11-lab-manual-part5.md" `
136+
-DocNumber 11 -Category "labs" `
137+
-Title "Lab Manual Part 5: Business & IT Management"
138+
139+
Copy-WithFrontMatter `
140+
-Source "architecture/integrations.md" `
141+
-Dest "02-implementation/12-integration-guide.md" `
142+
-DocNumber 12 -Category "implementation" `
143+
-Title "Integration Guide — Cross-Service Procedures"
144+
145+
Copy-WithFrontMatter `
146+
-Source "project/github-guide.md" `
147+
-Dest "04-github/13-github-guide.md" `
148+
-DocNumber 13 -Category "github" `
149+
-Title "IT-Stack GitHub Organization Setup Guide"
150+
151+
Copy-WithFrontMatter `
152+
-Source "contributing/framework-template.md" `
153+
-Dest "05-guides/14-project-framework.md" `
154+
-DocNumber 14 -Category "guides" `
155+
-Title "Project Framework Template"
156+
157+
# ── 4. Create 07-architecture README ──────────────────────────────────────────
158+
Write-Host "`n==> Creating docs/07-architecture/" -ForegroundColor Cyan
159+
$archReadme = @"
160+
# Architecture Reference
161+
162+
> **Category:** Architecture Decision Records (ADRs) and Technical Diagrams
163+
> **Doc Range:** 15+
164+
165+
This directory contains architecture decision records (ADRs) and technical diagrams for IT-Stack.
166+
167+
## ADR Index
168+
169+
| # | Title | Status | Date |
170+
|---|-------|--------|------|
171+
| ADR-001 | [Use FreeIPA + Keycloak for identity](adr-001-identity-stack.md) | Accepted | 2026-02-27 |
172+
| ADR-002 | [PostgreSQL as primary database for all services](adr-002-postgresql-primary.md) | Accepted | 2026-02-27 |
173+
| ADR-003 | [Traefik as reverse proxy with Let's Encrypt](adr-003-traefik-proxy.md) | Accepted | 2026-02-27 |
174+
| ADR-004 | [6-lab progressive testing methodology](adr-004-lab-methodology.md) | Accepted | 2026-02-27 |
175+
176+
## Diagrams
177+
178+
- Network topology: see [deployment/03-lab-deployment-plan.md](../02-implementation/03-lab-deployment-plan.md)
179+
- Service integration map: see [implementation/12-integration-guide.md](../02-implementation/12-integration-guide.md)
180+
- 7-layer architecture: see [architecture/overview.md](../architecture/overview.md)
181+
"@
182+
Set-Content "$docs\07-architecture\README.md" $archReadme -Encoding UTF8
183+
Write-Host " [OK] docs/07-architecture/README.md" -ForegroundColor Green
184+
185+
Write-Host "`nDone. Run phase-3-create-spec-docs.ps1 next for the 01-core/ category spec docs." -ForegroundColor Yellow

0 commit comments

Comments
 (0)