Skip to content

Commit 6f3858f

Browse files
Copilotevcatalyst
Copilot
and
evcatalyst
committed
Add project depth pages, architecture diagram, and documentation structure
Co-authored-by: evcatalyst <8740078+evcatalyst@users.noreply.github.com>
1 parent 5a6218a commit 6f3858f

16 files changed

Lines changed: 2651 additions & 67 deletions

‎README.md‎

Lines changed: 297 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -6,19 +6,57 @@ This repository hosts the static landing page for GitBrain at [gitbrain.com](htt
66

77
A clean, accessible, static website that:
88
- Explains what GitBrain is and its core principles
9-
- Showcases GitBrainLab projects with links to repositories
9+
- Showcases GitBrainLab projects with links to repositories and documentation
1010
- Describes how the projects fit together as a cohesive ecosystem
11+
- Provides detailed project pages with architecture diagrams and use cases
1112
- Works well on mobile devices and follows accessibility best practices
1213

1314
## Technology
1415

1516
- **Pure HTML + CSS** – No build step required
1617
- **No external dependencies** – Self-contained, no CDNs
1718
- **Typography** – Uses JetBrains Mono (self-hosted) for labels/module titles; font files included under `assets/fonts/jetbrains-mono/` with OFL license
18-
- **Mobile-responsive** – Works on all screen sizes
19-
- **Accessible** – Skip links, semantic HTML, high contrast, keyboard navigation
19+
- **Mobile-responsive** – Works on all screen sizes with responsive diagrams
20+
- **Accessible** – Skip links, semantic HTML, high contrast, keyboard navigation, ARIA labels
2021
- **Dark mode** – Premium dark theme by default
2122

23+
## File Structure
24+
25+
```
26+
.
27+
├── index.html # Main landing page
28+
├── architecture.html # Integrated ecosystem architecture
29+
├── 404.html # Error page
30+
├── CNAME # Custom domain configuration
31+
├── robots.txt # Search engine directives
32+
├── sitemap.xml # Site map for SEO
33+
├── README.md # This file
34+
├── projects/ # Individual project detail pages
35+
│ ├── context.html
36+
│ ├── chartspec.html
37+
│ ├── shelfsignals.html
38+
│ ├── crowdcode.html
39+
│ └── happenstance.html
40+
├── docs/ # Documentation hub
41+
│ ├── index.html
42+
│ ├── context.html
43+
│ ├── chartspec.html
44+
│ ├── shelfsignals.html
45+
│ ├── crowdcode.html
46+
│ └── happenstance.html
47+
├── styles/
48+
│ └── main.css # All styles including responsive diagrams
49+
└── assets/
50+
├── logo.svg # GitBrain logo
51+
├── favicon.svg # Site favicon
52+
├── social-card.svg # Open Graph/Twitter card image
53+
└── fonts/
54+
└── jetbrains-mono/ # Self-hosted JetBrains Mono font
55+
├── JetBrainsMono-Regular.woff2
56+
├── JetBrainsMono-SemiBold.woff2
57+
└── OFL.txt # Font license (SIL Open Font License)
58+
```
59+
2260
## Preview Locally
2361

2462
Since this is a static site, you can preview it with any local web server:
@@ -40,25 +78,268 @@ npx serve
4078

4179
Then open http://localhost:8000 in your browser.
4280

43-
## Editing Content
81+
## Adding a New Project
82+
83+
To add a new project to the GitBrain ecosystem:
4484

45-
All content is in static HTML files:
85+
### 1. Update index.html
4686

47-
- **`index.html`** – Main landing page with all sections
48-
- **`styles/main.css`** – All styles including responsive and dark mode
49-
- **`assets/`** – Logo, favicon, and social card images
50-
- **`404.html`** – Custom error page
87+
Add a new bento tile in the `<section id="projects">`:
88+
89+
```html
90+
<article class="bento-tile" data-size="medium">
91+
<div class="tile-header">
92+
<h3>ProjectName</h3>
93+
<div class="tile-meta">
94+
<span class="meta-item">Type: Category</span>
95+
<span class="meta-item">Surface: Interface</span>
96+
</div>
97+
</div>
98+
<p class="tile-description">Short description of the project</p>
99+
<div class="tile-links">
100+
<a href="/projects/projectname.html" class="tile-link">Learn more →</a>
101+
<a href="/docs/projectname.html" class="tile-link">Docs →</a>
102+
<a href="https://github.com/gitbrainlab/ProjectName" class="tile-link" target="_blank" rel="noopener noreferrer">GitHub →</a>
103+
</div>
104+
</article>
105+
```
106+
107+
### 2. Create Project Detail Page
108+
109+
Create `/projects/projectname.html` using this template structure:
110+
111+
```html
112+
<!DOCTYPE html>
113+
<html lang="en">
114+
<head>
115+
<meta charset="UTF-8">
116+
<meta name="viewport" content="width=device-width, initial-scale=1.0">
117+
<meta name="theme-color" content="#0a0a0f">
118+
<title>ProjectName – GitBrain</title>
119+
<meta name="description" content="Project description">
120+
<link rel="canonical" href="https://gitbrain.com/projects/projectname.html">
121+
<link rel="icon" type="image/svg+xml" href="/assets/favicon.svg">
122+
<link rel="stylesheet" href="/styles/main.css">
123+
</head>
124+
<body>
125+
<!-- Breadcrumb navigation -->
126+
<nav class="breadcrumb">
127+
<div class="container">
128+
<nav aria-label="Breadcrumb">
129+
<a href="/">Home</a>
130+
<span>→</span>
131+
<a href="/#projects">Projects</a>
132+
<span>→</span>
133+
<span aria-current="page">ProjectName</span>
134+
</nav>
135+
</div>
136+
</nav>
137+
138+
<!-- Project header -->
139+
<header class="project-header">
140+
<div class="container">
141+
<h1 class="project-title">ProjectName</h1>
142+
<p class="project-tagline">One-line description</p>
143+
<div class="project-links">
144+
<a href="https://github.com/gitbrainlab/ProjectName" target="_blank" rel="noopener noreferrer">
145+
<span>📦</span> View Repository
146+
</a>
147+
<a href="/docs/projectname.html">
148+
<span>📚</span> Documentation
149+
</a>
150+
</div>
151+
</div>
152+
</header>
153+
154+
<main id="main">
155+
<!-- At a Glance section -->
156+
<section class="project-section">
157+
<div class="container">
158+
<h2>At a Glance</h2>
159+
<dl class="project-attrs">
160+
<div>
161+
<dt>Why</dt>
162+
<dd>Why this project exists / problem it solves</dd>
163+
</div>
164+
<div>
165+
<dt>Benefit</dt>
166+
<dd>Main benefit / value proposition</dd>
167+
</div>
168+
<div>
169+
<dt>For</dt>
170+
<dd>Target audience / who should use this</dd>
171+
</div>
172+
<div>
173+
<dt>Use</dt>
174+
<dd>How to use it at a high level</dd>
175+
</div>
176+
</dl>
177+
</div>
178+
</section>
179+
180+
<!-- Architecture section with diagrams -->
181+
<section class="project-section">
182+
<div class="container">
183+
<h2>Architecture</h2>
184+
185+
<h3>Context Diagram</h3>
186+
<p>How the project interacts with external systems:</p>
187+
<pre class="diagram" aria-label="Context diagram for ProjectName">
188+
┌─────────────────────┐
189+
│ Users │
190+
└──────────┬──────────┘
191+
│
192+
▼
193+
┌─────────────────────┐
194+
│ ProjectName │
195+
└──────────┬──────────┘
196+
│
197+
▼
198+
┌─────────────────────┐
199+
│ External Systems │
200+
└─────────────────────┘
201+
</pre>
202+
203+
<h3>Internal Architecture</h3>
204+
<p>Key modules inside the project:</p>
205+
<pre class="diagram" aria-label="Internal architecture of ProjectName">
206+
┌─────────────────────────────┐
207+
│ ProjectName Core │
208+
├─────────────────────────────┤
209+
│ ┌────────────────────┐ │
210+
│ │ Component A │ │
211+
│ └─────────┬──────────┘ │
212+
│ ▼ │
213+
│ ┌────────────────────┐ │
214+
│ │ Component B │ │
215+
│ └────────────────────┘ │
216+
└─────────────────────────────┘
217+
</pre>
218+
</div>
219+
</section>
220+
221+
<!-- How to Use section -->
222+
<section class="project-section">
223+
<div class="container">
224+
<h2>How to Use</h2>
225+
<ol class="step-list">
226+
<li>
227+
<strong>Step 1 title</strong>
228+
<span>Step 1 description</span>
229+
</li>
230+
<li>
231+
<strong>Step 2 title</strong>
232+
<span>Step 2 description</span>
233+
</li>
234+
<!-- Add 3-6 steps total -->
235+
</ol>
236+
</div>
237+
</section>
238+
239+
<!-- Related Projects section -->
240+
<section class="project-section">
241+
<div class="container">
242+
<h2>Related Projects</h2>
243+
<div class="related-projects">
244+
<a href="/projects/otherproject.html" class="related-project-card">
245+
<h3>OtherProject</h3>
246+
<p>How it relates to this project</p>
247+
</a>
248+
<a href="/architecture.html" class="related-project-card">
249+
<h3>View Ecosystem</h3>
250+
<p>See how this fits into the broader GitBrain architecture</p>
251+
</a>
252+
</div>
253+
</div>
254+
</section>
255+
</main>
256+
257+
<!-- Footer -->
258+
<footer class="footer">
259+
<div class="container">
260+
<nav class="footer-nav">
261+
<a href="/">Home</a>
262+
<a href="/#projects">Projects</a>
263+
<a href="/architecture.html">Architecture</a>
264+
<a href="https://github.com/gitbrainlab" target="_blank" rel="noopener noreferrer">GitHub</a>
265+
</nav>
266+
<p class="footer-copyright">© 2024 GitBrain. Open source projects.</p>
267+
</div>
268+
</footer>
269+
</body>
270+
</html>
271+
```
51272

52-
### To update projects:
273+
### 3. Create Documentation Stub
53274

54-
Edit the `<section id="projects">` in `index.html`. Each project is a `<article class="project-card">` with:
55-
- Project name in `<h3>`
56-
- Description in `<p>`
57-
- GitHub link in `<a class="project-link">`
275+
Create `/docs/projectname.html` with getting started guide structure (see existing docs for template).
58276

59-
### To update principles:
277+
### 4. Update Ecosystem Architecture
60278

61-
Edit the `<section class="principles">` in `index.html`. Each principle is a `<li>` with `<strong>` for the title and `<span>` for the description.
279+
Add the new project to `/architecture.html` in the integrated diagram and project links section.
280+
281+
### 5. Update Sitemap
282+
283+
Add entries to `sitemap.xml`:
284+
285+
```xml
286+
<url>
287+
<loc>https://gitbrain.com/projects/projectname.html</loc>
288+
<lastmod>YYYY-MM-DD</lastmod>
289+
<changefreq>monthly</changefreq>
290+
<priority>0.8</priority>
291+
</url>
292+
<url>
293+
<loc>https://gitbrain.com/docs/projectname.html</loc>
294+
<lastmod>YYYY-MM-DD</lastmod>
295+
<changefreq>weekly</changefreq>
296+
<priority>0.6</priority>
297+
</url>
298+
```
299+
300+
## Diagram Style Guidelines
301+
302+
All architecture diagrams use ASCII box-drawing characters for consistency:
303+
304+
### Rules:
305+
- Use box-drawing characters: `┌ ┐ └ ┘ │ ─ ├ ┤ ┬ ┴ ┼`
306+
- Arrows: `→ ←` or `▶ ▼ ▲ ◀`
307+
- Keep diagrams under 75 characters wide for mobile readability
308+
- Use `<pre class="diagram" aria-label="Description">` wrapper
309+
- Include descriptive aria-label for accessibility
310+
- Diagrams automatically scroll horizontally on narrow screens
311+
312+
### Example Context Diagram:
313+
```
314+
┌─────────────────────┐
315+
│ Users │
316+
└──────────┬──────────┘
317+
│
318+
▼
319+
┌─────────────────────┐
320+
│ Your Project │
321+
└──────────┬──────────┘
322+
│
323+
▼
324+
┌─────────────────────┐
325+
│ Dependencies │
326+
└─────────────────────┘
327+
```
328+
329+
### Example Internal Architecture:
330+
```
331+
┌─────────────────────────────────┐
332+
│ Project Core │
333+
├─────────────────────────────────┤
334+
│ ┌────────────────────┐ │
335+
│ │ Module A │ │
336+
│ └─────────┬──────────┘ │
337+
│ ▼ │
338+
│ ┌────────────────────┐ │
339+
│ │ Module B │ │
340+
│ └────────────────────┘ │
341+
└─────────────────────────────────┘
342+
```
62343

63344
## Deployment
64345

@@ -82,29 +363,6 @@ The DNS records for `gitbrain.com` should point to GitHub Pages:
82363

83364
Note: DNS changes are handled outside this repository.
84365

85-
## File Structure
86-
87-
```
88-
.
89-
├── index.html # Main landing page
90-
├── 404.html # Error page
91-
├── CNAME # Custom domain configuration
92-
├── robots.txt # Search engine directives
93-
├── sitemap.xml # Site map for SEO
94-
├── README.md # This file
95-
├── styles/
96-
│ └── main.css # All styles
97-
└── assets/
98-
├── logo.svg # GitBrain logo
99-
├── favicon.svg # Site favicon
100-
├── social-card.svg # Open Graph/Twitter card image
101-
└── fonts/
102-
└── jetbrains-mono/ # Self-hosted JetBrains Mono font
103-
├── JetBrainsMono-Regular.woff2
104-
├── JetBrainsMono-SemiBold.woff2
105-
└── OFL.txt # Font license (SIL Open Font License)
106-
```
107-
108366
## License
109367

110368
See individual project repositories for their respective licenses.

0 commit comments

Comments
 (0)