Skip to content

Commit 3004e04

Browse files
lioneltchamilioneltchami
committed
Migrate documentation portal to Astro Starlight
1 parent 27e1603 commit 3004e04

19 files changed

Lines changed: 7361 additions & 998 deletions

‎.github/workflows/docs-site.yml‎

Lines changed: 26 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -12,23 +12,31 @@ permissions:
1212

1313
jobs:
1414
build:
15-
name: Build MkDocs site
15+
name: Build Astro Starlight site
1616
runs-on: ubuntu-latest
1717
timeout-minutes: 10
1818
steps:
1919
- name: Checkout repository
2020
uses: actions/checkout@v4
2121

22+
- name: Set up Node
23+
uses: actions/setup-node@v4
24+
with:
25+
node-version: "22"
26+
cache: npm
27+
2228
- name: Set up Python
2329
uses: actions/setup-python@v5
2430
with:
2531
python-version: "3.12"
2632

27-
- name: Install documentation dependencies
28-
run: python -m pip install -r tools/requirements.txt
33+
- name: Install dependencies
34+
run: |
35+
python -m pip install -r tools/requirements.txt
36+
npm ci
2937
30-
- name: Build documentation
31-
run: python -m mkdocs build --strict
38+
- name: Build documentation portal
39+
run: npm run build
3240

3341
deploy:
3442
name: Deploy to GitHub Pages
@@ -47,16 +55,24 @@ jobs:
4755
- name: Checkout repository
4856
uses: actions/checkout@v4
4957

58+
- name: Set up Node
59+
uses: actions/setup-node@v4
60+
with:
61+
node-version: "22"
62+
cache: npm
63+
5064
- name: Set up Python
5165
uses: actions/setup-python@v5
5266
with:
5367
python-version: "3.12"
5468

55-
- name: Install documentation dependencies
56-
run: python -m pip install -r tools/requirements.txt
69+
- name: Install dependencies
70+
run: |
71+
python -m pip install -r tools/requirements.txt
72+
npm ci
5773
58-
- name: Build documentation
59-
run: python -m mkdocs build --strict
74+
- name: Build documentation portal
75+
run: npm run build
6076

6177
- name: Configure Pages
6278
uses: actions/configure-pages@v5
@@ -66,7 +82,7 @@ jobs:
6682
- name: Upload Pages artifact
6783
uses: actions/upload-pages-artifact@v3
6884
with:
69-
path: site
85+
path: dist
7086

7187
- name: Deploy to GitHub Pages
7288
id: deployment

‎.github/workflows/global-security.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -74,3 +74,4 @@ jobs:
7474
VALIDATE_JSCPD: false
7575
VALIDATE_KUBERNETES_KUBEVAL: false
7676
VALIDATE_PYTHON_MYPY: false
77+
VALIDATE_TYPESCRIPT_STANDARD: false

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,8 @@ REVIEW-UPDATES.md
2929
node_modules/
3030
__pycache__/
3131
.pytest_cache/
32+
.astro/
33+
/src/content/docs/
3234
*.pyc
3335
*.pyo
3436
target/

‎Makefile‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
.PHONY: help quality list-projects validate-project test-tools
1+
.PHONY: help quality list-projects validate-project test-tools build-site
22

33
PYTHON ?= python3
44
PROJECT ?=
@@ -9,7 +9,8 @@ help:
99
' make quality Run tool tests and the repository quality gate' \
1010
' make list-projects List metadata-discovered root projects' \
1111
' make validate-project PROJECT=<path> Validate one project with the quality gate' \
12-
' make test-tools Run tool unit tests'
12+
' make test-tools Run tool unit tests' \
13+
' make build-site Build the Astro Starlight learning portal'
1314

1415
quality: test-tools
1516
$(PYTHON) -m tools.quality_gate .
@@ -23,3 +24,6 @@ validate-project:
2324

2425
test-tools:
2526
$(PYTHON) -m pytest tools/tests tools/repo_consolidation/tests -q
27+
28+
build-site:
29+
npm run build

‎README.md‎

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -26,12 +26,15 @@ This repository is designed to prove practical engineering judgment: infrastruct
2626
The student portal is the best entry point for browsing, choosing, and safely running projects:
2727

2828
- [Open the DevOps Projects Student Portal](https://devcloudninjas.github.io/DevOps-Projects/)
29-
- [Pick a project](./docs/catalog/project-picker.md)
30-
- [Run projects safely with your own credentials](./docs/runbooks/credentials-and-cost-safety.md)
29+
- [Pick a project](https://devcloudninjas.github.io/DevOps-Projects/catalog/project-picker/)
30+
- [Browse internal project guides](https://devcloudninjas.github.io/DevOps-Projects/projects/)
31+
- [Run projects safely with your own credentials](https://devcloudninjas.github.io/DevOps-Projects/runbooks/credentials-and-cost-safety/)
3132
- [Contribute improvements](./CONTRIBUTING.md)
3233
- [Ask for help without exposing secrets](./SUPPORT.md)
3334

34-
The site is static and privacy-first. It does not require accounts, forms, analytics, cookies, or shared credentials.
35+
The site is an Astro Starlight portal with internal pages for every project.
36+
It is static and privacy-first. It does not require accounts, forms,
37+
analytics, cookies, or shared credentials.
3538

3639
---
3740

@@ -65,7 +68,7 @@ flowchart LR
6568
reviewer["Reviewer / Hiring Manager"] --> readme["Root README"]
6669
readme --> flagship["5 Flagship Case Studies"]
6770
readme --> catalog["54 Project Catalog"]
68-
readme --> docs["Docs Site"]
71+
readme --> docs["Astro Starlight Portal"]
6972
7073
flagship --> app["Apps: Django, Node, AI Chatbot"]
7174
flagship --> infra["IaC: Terraform, EKS, ECS, VPC"]
@@ -103,7 +106,7 @@ Use this workflow:
103106
9. Run cleanup commands and confirm resources are deleted.
104107
10. Write a short learning report about what worked, what failed, and what you fixed.
105108

106-
For the full checklist, see the [Student Implementation Guide](./docs/runbooks/student-implementation-guide.md). For new projects, use the [Project README Template](./docs/project-readme-template.md).
109+
For the full checklist, see the [Student Implementation Guide](https://devcloudninjas.github.io/DevOps-Projects/runbooks/student-implementation-guide/). For new projects, use the [Project README Template](https://devcloudninjas.github.io/DevOps-Projects/project-readme-template/).
107110

108111
Use [LEARNING_TRACKER.md](./LEARNING_TRACKER.md) as a personal template for time planning, prerequisites, validation notes, cleanup, and portfolio evidence.
109112

‎astro.config.mjs‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
import { defineConfig } from 'astro/config';
2+
import starlight from '@astrojs/starlight';
3+
4+
export default defineConfig({
5+
site: 'https://devcloudninjas.github.io',
6+
base: '/DevOps-Projects',
7+
integrations: [
8+
starlight({
9+
title: 'DevOps Projects',
10+
description:
11+
'A student-first DevOps learning portal with 54 hands-on projects, guided paths, safety runbooks, and portfolio-ready proof.',
12+
customCss: ['./src/styles/portal.css'],
13+
favicon: '/favicon.svg',
14+
lastUpdated: true,
15+
pagefind: true,
16+
social: [
17+
{
18+
icon: 'github',
19+
label: 'GitHub repository',
20+
href: 'https://github.com/DevCloudNinjas/DevOps-Projects',
21+
},
22+
],
23+
tableOfContents: {
24+
minHeadingLevel: 2,
25+
maxHeadingLevel: 3,
26+
},
27+
sidebar: [
28+
{ label: 'Home', link: '/' },
29+
{
30+
label: 'Start Here',
31+
items: [
32+
{ label: 'Catalog Overview', link: '/catalog/' },
33+
{ label: 'Project Picker', link: '/catalog/project-picker/' },
34+
{ label: 'Run Safely', link: '/runbooks/' },
35+
],
36+
},
37+
{
38+
label: 'Projects',
39+
collapsed: true,
40+
items: [
41+
{ label: 'All Projects', link: '/projects/' },
42+
{ label: 'Project Picker', link: '/catalog/project-picker/' },
43+
{ label: 'ArgoCD GitOps Home Lab', link: '/projects/50-argocd-gitops-home-lab/' },
44+
{ label: 'OpenTelemetry Home Lab', link: '/projects/51-opentelemetry-observability-home-lab/' },
45+
{ label: 'OpenTofu Free-Tier Lab', link: '/projects/52-opentofu-aws-free-tier-lab/' },
46+
{ label: 'Supply Chain Security Lab', link: '/projects/53-supply-chain-security-lab/' },
47+
{ label: 'Progressive Delivery Lab', link: '/projects/54-progressive-delivery-home-lab/' },
48+
],
49+
},
50+
{
51+
label: 'Learning Paths',
52+
items: [{ autogenerate: { directory: 'learning-paths' } }],
53+
},
54+
{
55+
label: 'Runbooks',
56+
collapsed: true,
57+
items: [
58+
{ label: 'Student Guide', link: '/runbooks/student-implementation-guide/' },
59+
{ label: 'Credentials & Cost Safety', link: '/runbooks/credentials-and-cost-safety/' },
60+
{ label: 'IaC and Kubernetes', link: '/iac-kubernetes-solid-runbook/' },
61+
],
62+
},
63+
{
64+
label: 'Reference',
65+
collapsed: true,
66+
items: [
67+
{ label: 'Security Baselines', link: '/security-baselines/' },
68+
{ label: 'Project README Template', link: '/project-readme-template/' },
69+
{ label: 'Flagship Docs', link: '/flagship/' },
70+
{ label: 'Community', link: '/community/' },
71+
{ label: 'Marketing', link: '/marketing/' },
72+
],
73+
},
74+
],
75+
}),
76+
],
77+
});

‎docs/community/roadmap.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -53,9 +53,9 @@ Improve repository trust signals by tracking practical security hygiene:
5353

5454
The goal is not a badge-only score. The goal is safer day-to-day contribution.
5555

56-
### Material for MkDocs Search
56+
### Astro Starlight Search
5757

58-
Keep improving the Material for MkDocs experience where it clearly improves navigation, search, and copyable commands.
58+
Keep improving the Astro Starlight experience where it clearly improves navigation, search, internal project discovery, and copyable commands.
5959

6060
Desired improvements:
6161

0 commit comments

Comments
 (0)