Skip to content

Commit 7afb883

Browse files
nielsweistranielsweistra
committed
feat(docs): add reusable component library for all ITL projects
- Add 8 reusable Jekyll components (_includes/) - alert.html: styled alerts (info/warning/success/danger) - badge.html: status/version badges - button.html: action buttons with multiple styles - card.html: feature cards with icons, tags, badges - code-block.html: syntax-highlighted code with copy button - breadcrumb.html: navigation breadcrumbs - grid.html: responsive grid layouts (1-4 columns) - link-card.html: clickable documentation links - Add comprehensive documentation - README.md: complete component API reference - COMPONENTS_DEMO.md: live examples of all components - INTEGRATION.md: guide for using components in other repos - QUICK_REFERENCE.md: one-page cheat sheet - Update _config.yml to include _includes directory - Components follow ITL Design System (Azure Portal dark theme) - 3 integration methods: copy, git submodule, GitHub Actions sync - Compatible with all Jekyll/GitHub Pages projects This creates a central component library that can be shared across: - ITL.ControlPlane.Attestation - ITL.BrainCell - ITL.ControlPlane.CLI - All future ITL documentation sites
1 parent 4d870aa commit 7afb883

13 files changed

Lines changed: 1259 additions & 0 deletions

‎docs/COMPONENTS_DEMO.md‎

Lines changed: 243 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,243 @@
1+
---
2+
layout: default
3+
title: Component Demo
4+
---
5+
6+
# ITL Component Library — Demo
7+
8+
Live examples of all reusable documentation components.
9+
10+
{% include breadcrumb.html path="Home,Components,Demo" %}
11+
12+
---
13+
14+
## 🎨 Alerts
15+
16+
{% include alert.html type="info" title="Information" content="This is an informational alert. Use it to highlight important details without blocking user flow." %}
17+
18+
{% include alert.html type="warning" content="This is a warning alert without a title. Use for caution messages." %}
19+
20+
{% include alert.html type="success" title="Success!" content="Your operation completed successfully. Everything is working as expected." %}
21+
22+
{% include alert.html type="danger" title="Critical Error" content="This is a critical error that requires immediate attention." %}
23+
24+
---
25+
26+
## 🔘 Buttons
27+
28+
### Styles
29+
30+
<div style="display: flex; gap: 1rem; flex-wrap: wrap; margin: 2rem 0;">
31+
{% include button.html text="Primary" link="#" style="primary" %}
32+
{% include button.html text="Secondary" link="#" style="secondary" %}
33+
{% include button.html text="Success" link="#" style="success" %}
34+
{% include button.html text="Danger" link="#" style="danger" %}
35+
{% include button.html text="Outline" link="#" style="outline" %}
36+
</div>
37+
38+
### Sizes
39+
40+
<div style="display: flex; gap: 1rem; flex-wrap: wrap; align-items: center; margin: 2rem 0;">
41+
{% include button.html text="Small" link="#" style="primary" size="small" %}
42+
{% include button.html text="Medium" link="#" style="primary" size="medium" %}
43+
{% include button.html text="Large" link="#" style="primary" size="large" %}
44+
</div>
45+
46+
### With Icons
47+
48+
<div style="display: flex; gap: 1rem; flex-wrap: wrap; margin: 2rem 0;">
49+
{% include button.html text="Rocket Launch" link="#" style="primary" icon="🚀" %}
50+
{% include button.html text="GitHub" link="https://github.com/ITlusions" style="secondary" icon="🔗" target="_blank" %}
51+
{% include button.html text="Documentation" link="/README" style="outline" icon="📖" %}
52+
</div>
53+
54+
---
55+
56+
## 🏷️ Badges
57+
58+
### Colors
59+
60+
<div style="display: flex; gap: 0.75rem; flex-wrap: wrap; margin: 2rem 0;">
61+
{% include badge.html text="v2.0.0" color="success" %}
62+
{% include badge.html text="Beta" color="warning" %}
63+
{% include badge.html text="Deprecated" color="danger" %}
64+
{% include badge.html text="New Feature" color="info" icon="✨" %}
65+
{% include badge.html text="Stable" color="muted" %}
66+
</div>
67+
68+
### Sizes
69+
70+
<div style="display: flex; gap: 0.75rem; flex-wrap: wrap; align-items: center; margin: 2rem 0;">
71+
{% include badge.html text="Small" color="info" size="small" %}
72+
{% include badge.html text="Medium" color="info" size="medium" %}
73+
{% include badge.html text="Large" color="info" size="large" %}
74+
</div>
75+
76+
---
77+
78+
## 📦 Cards
79+
80+
{% capture cards %}
81+
{% include card.html
82+
title="GitHub Actions"
83+
icon="⚙️"
84+
description="Reusable workflows for CI/CD pipelines. Automated versioning, Docker builds, and PyPI publishing."
85+
link="/workflows"
86+
tags="CI/CD,automation,workflows"
87+
badge="Production"
88+
badge_color="success"
89+
%}
90+
91+
{% include card.html
92+
title="Composite Actions"
93+
icon="🧩"
94+
description="Modular action building blocks. Python environment setup, release type detection, and more."
95+
link="/actions"
96+
tags="actions,reusable,composable"
97+
badge="Stable"
98+
badge_color="info"
99+
%}
100+
101+
{% include card.html
102+
title="Documentation"
103+
icon="📚"
104+
description="Component library for Jekyll-based documentation sites. Consistent design across all ITL projects."
105+
link="/docs/_includes"
106+
tags="docs,jekyll,components"
107+
badge="New"
108+
badge_color="warning"
109+
%}
110+
{% endcapture %}
111+
{% include grid.html content=cards columns="3" gap="large" %}
112+
113+
---
114+
115+
## 🔗 Link Cards
116+
117+
{% include link-card.html
118+
title="Workflow Documentation"
119+
description="Complete reference for all reusable GitHub Actions workflows"
120+
link="/workflows"
121+
icon="📖"
122+
%}
123+
124+
{% include link-card.html
125+
title="Getting Started Guide"
126+
description="Quick start guide for integrating ITL workflows into your repository"
127+
link="/getting-started"
128+
icon="🚀"
129+
%}
130+
131+
{% include link-card.html
132+
title="GitHub Repository"
133+
description="Source code, issues, and contributions"
134+
link="https://github.com/ITlusions/ITL.Github"
135+
icon="🔗"
136+
external="true"
137+
%}
138+
139+
---
140+
141+
## 💻 Code Blocks
142+
143+
### Bash Example
144+
145+
{% capture bash_code %}
146+
# Clone repository
147+
git clone https://github.com/ITlusions/ITL.Github.git
148+
cd ITL.Github
149+
150+
# Install dependencies
151+
npm install
152+
153+
# View documentation locally
154+
bundle exec jekyll serve
155+
{% endcapture %}
156+
{% include code-block.html code=bash_code language="bash" title="Installation" %}
157+
158+
### Python Example
159+
160+
{% capture python_code %}
161+
from pathlib import Path
162+
163+
def discover_workflows(path: Path) -> list[str]:
164+
"""Discover all reusable workflows."""
165+
return [
166+
f.stem for f in path.glob("_reusable-*.yml")
167+
if f.is_file()
168+
]
169+
{% endcapture %}
170+
{% include code-block.html code=python_code language="python" filename="discover.py" %}
171+
172+
### YAML Example
173+
174+
{% capture yaml_code %}
175+
name: CI Pipeline
176+
on: [push, pull_request]
177+
178+
jobs:
179+
build:
180+
uses: ITlusions/ITL.Github/.github/workflows/_reusable-ci-python.yml@main
181+
with:
182+
python-version: "3.12"
183+
{% endcapture %}
184+
{% include code-block.html code=yaml_code language="yaml" filename=".github/workflows/ci.yml" %}
185+
186+
---
187+
188+
## 📊 Grid Layouts
189+
190+
### 2-Column Grid
191+
192+
{% capture two_col %}
193+
{% include card.html title="Left Column" icon="📄" description="First column with equal width distribution for balanced layouts" %}
194+
{% include card.html title="Right Column" icon="📄" description="Second column content with automatic responsive behavior" %}
195+
{% endcapture %}
196+
{% include grid.html content=two_col columns="2" gap="medium" %}
197+
198+
### 4-Column Grid
199+
200+
{% capture four_col %}
201+
{% include card.html title="Step 1" icon="1️⃣" description="Clone repository" %}
202+
{% include card.html title="Step 2" icon="2️⃣" description="Install dependencies" %}
203+
{% include card.html title="Step 3" icon="3️⃣" description="Configure settings" %}
204+
{% include card.html title="Step 4" icon="4️⃣" description="Deploy to production" %}
205+
{% endcapture %}
206+
{% include grid.html content=four_col columns="4" gap="small" %}
207+
208+
---
209+
210+
## 🎯 Combining Components
211+
212+
Rich layouts by nesting components:
213+
214+
{% include alert.html type="info" title="Quick Integration Guide" content="Follow these steps to add ITL workflows to your repository." %}
215+
216+
{% capture step1 %}
217+
# Add workflow file
218+
mkdir -p .github/workflows
219+
touch .github/workflows/ci.yml
220+
{% endcapture %}
221+
{% include code-block.html code=step1 language="bash" title="Step 1: Create Workflow Directory" %}
222+
223+
{% capture step2 %}
224+
name: CI
225+
on: [push]
226+
jobs:
227+
build:
228+
uses: ITlusions/ITL.Github/.github/workflows/_reusable-ci-python.yml@main
229+
{% endcapture %}
230+
{% include code-block.html code=step2 language="yaml" title="Step 2: Configure Workflow" %}
231+
232+
<div style="margin-top: 2rem;">
233+
{% include button.html text="View Full Documentation" link="/README" style="primary" icon="📖" %}
234+
{% include button.html text="Browse Workflows" link="/workflows" style="secondary" icon="⚙️" %}
235+
</div>
236+
237+
---
238+
239+
## 📚 Documentation
240+
241+
- {% include badge.html text="README.md" color="info" %} Component API documentation
242+
- {% include badge.html text="MIGRATION_GUIDE.md" color="warning" %} Refactoring guide
243+
- {% include badge.html text="GitHub" color="muted" %} [Source code](https://github.com/ITlusions/ITL.Github)

‎docs/_config.yml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,10 @@ kramdown:
1313
block:
1414
line_numbers: false
1515

16+
# Force include static files and component directory
17+
include:
18+
- _includes
19+
1620
# Exclude files that shouldn't be built as pages
1721
exclude:
1822
- "*.py"

‎docs/_includes/INTEGRATION.md‎

Whitespace-only changes.

0 commit comments

Comments
 (0)