Skip to content

Commit da2e201

Browse files
djm81djm81
committed
docs: improve Jekyll GitHub Pages integration with navigation and styling
- Add YAML front matter to all documentation pages for proper Jekyll rendering - Implement left-side navigation sidebar for better UX - Fix CSS styling issues (white-on-white text, code block backgrounds) - Add custom default layout with two-column docs layout - Configure proper permalinks for all documentation pages - Fix Rouge syntax highlighting for code blocks with light theme - Ensure proper CSS asset generation and loading - Add responsive design for mobile devices
1 parent cdd90c2 commit da2e201

21 files changed

+1091
-34
lines changed

‎docs/README.md‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -66,11 +66,12 @@ SpecFact isn't just a technical tool—it's designed for **real-world agile/scru
6666
**Primary Goal**: Let SpecFact find gaps, use your AI IDE to fix them
6767

6868
```bash
69-
# 1. Find gaps in your code
70-
specfact analyze gaps --bundle my-project
69+
# 1. Run brownfield analysis and validation
70+
specfact import from-code my-project --repo .
71+
specfact repro --verbose
7172

72-
# 2. Generate AI-ready prompt
73-
specfact generate fix-prompt GAP-001
73+
# 2. Generate AI-ready prompt for a specific gap
74+
specfact generate fix-prompt GAP-001 --bundle my-project
7475

7576
# 3. Copy to AI IDE → AI generates fix → Validate with SpecFact
7677
specfact enforce sdd --bundle my-project

‎docs/_config.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,7 @@ exclude:
3636
- scripts
3737
- specs
3838
- resources
39+
- "*.css.map" # Exclude source map files
3940

4041
# Source and destination (Jekyll will look for files in docs/)
4142
# Note: For GitHub Pages, Jekyll typically expects source in root or docs/
@@ -88,6 +89,7 @@ minima:
8889
# sass_dir is only needed for custom SASS partials directory
8990
sass:
9091
style: compressed
92+
sourcemap: never # Disable source maps to avoid conflicts
9193

9294
# Footer
9395
footer:

‎docs/_layouts/default.html‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
<!DOCTYPE html>
2+
<html lang="{{ page.lang | default: site.lang | default: 'en' }}">
3+
<head>
4+
<meta charset="utf-8">
5+
<meta http-equiv="X-UA-Compatible" content="IE=edge">
6+
<meta name="viewport" content="width=device-width, initial-scale=1">
7+
{% seo %}
8+
<link rel="stylesheet" href="{{ '/assets/main.css' | relative_url }}">
9+
<link rel="alternate" type="application/rss+xml" title="{{ site.title | escape }}" href="{{ '/feed.xml' | relative_url }}">
10+
{% if jekyll.environment == 'production' and site.google_analytics %}
11+
{% include google-analytics.html %}
12+
{% endif %}
13+
</head>
14+
<body>
15+
<header class="site-header" role="banner">
16+
<div class="wrapper">
17+
<a class="site-title" rel="author" href="{{ '/' | relative_url }}">{{ site.title | escape }}</a>
18+
<nav class="site-nav">
19+
<input type="checkbox" id="nav-trigger" class="nav-trigger" />
20+
<label for="nav-trigger">
21+
<span class="menu-icon">
22+
<svg viewBox="0 0 18 15" width="18px" height="15px">
23+
<path d="M18,1.484c0,0.82-0.665,1.484-1.484,1.484H1.484C0.665,2.969,0,2.304,0,1.484l0,0C0,0.665,0.665,0,1.484,0 h15.032C17.335,0,18,0.665,18,1.484L18,1.484z M18,7.516C18,8.335,17.335,9,16.516,9H1.484C0.665,9,0,8.335,0,7.516l0,0 c0-0.82,0.665-1.484,1.484-1.484h15.032C17.335,6.031,18,6.696,18,7.516L18,7.516z M18,13.516C18,14.335,17.335,15,16.516,15H1.484 C0.665,15,0,14.335,0,13.516l0,0c0-0.82,0.665-1.484,1.484-1.484h15.032C17.335,12.031,18,12.696,18,13.516L18,13.516z"/>
24+
</svg>
25+
</span>
26+
</label>
27+
<div class="trigger">
28+
<a class="page-link" href="{{ '/' | relative_url }}">Home</a>
29+
<a class="page-link" href="{{ '/getting-started/installation/' | relative_url }}">Getting Started</a>
30+
<a class="page-link" href="{{ '/brownfield-engineer/' | relative_url }}">Guides</a>
31+
<a class="page-link" href="{{ '/commands/' | relative_url }}">Reference</a>
32+
</div>
33+
</nav>
34+
</div>
35+
</header>
36+
37+
<main class="page-content" aria-label="Content">
38+
<div class="wrapper docs-layout">
39+
<aside class="docs-sidebar" aria-label="Documentation navigation">
40+
<div class="docs-sidebar-inner">
41+
<h2 class="docs-sidebar-title">
42+
<a href="{{ '/' | relative_url }}">SpecFact CLI</a>
43+
</h2>
44+
45+
<nav class="docs-nav">
46+
<p class="docs-nav-section">Getting Started</p>
47+
<ul>
48+
<li><a href="{{ '/getting-started/installation/' | relative_url }}">Installation</a></li>
49+
<li><a href="{{ '/getting-started/first-steps/' | relative_url }}">First Steps</a></li>
50+
</ul>
51+
52+
<p class="docs-nav-section">Guides</p>
53+
<ul>
54+
<li><a href="{{ '/brownfield-engineer/' | relative_url }}">Modernizing Legacy Code</a></li>
55+
<li><a href="{{ '/brownfield-journey/' | relative_url }}">Brownfield Journey</a></li>
56+
<li><a href="{{ '/ux-features/' | relative_url }}">UX Features</a></li>
57+
<li><a href="{{ '/use-cases/' | relative_url }}">Use Cases</a></li>
58+
<li><a href="{{ '/ide-integration/' | relative_url }}">IDE Integration</a></li>
59+
<li><a href="{{ '/copilot-mode/' | relative_url }}">CoPilot Mode</a></li>
60+
<li><a href="{{ '/troubleshooting/' | relative_url }}">Troubleshooting</a></li>
61+
<li><a href="{{ '/competitive-analysis/' | relative_url }}">Competitive Analysis</a></li>
62+
</ul>
63+
64+
<p class="docs-nav-section">Reference</p>
65+
<ul>
66+
<li><a href="{{ '/commands/' | relative_url }}">Command Reference</a></li>
67+
<li><a href="{{ '/architecture/' | relative_url }}">Architecture</a></li>
68+
<li><a href="{{ '/modes/' | relative_url }}">Operational Modes</a></li>
69+
<li><a href="{{ '/directory-structure/' | relative_url }}">Directory Structure</a></li>
70+
</ul>
71+
72+
<p class="docs-nav-section">Examples</p>
73+
<ul>
74+
<li><a href="{{ '/examples/' | relative_url }}">All Examples</a></li>
75+
<li><a href="{{ '/quick-examples/' | relative_url }}">Quick Examples</a></li>
76+
</ul>
77+
</nav>
78+
</div>
79+
</aside>
80+
81+
<div class="docs-content">
82+
{{ content }}
83+
</div>
84+
</div>
85+
</main>
86+
87+
<footer class="site-footer h-card">
88+
<data class="u-url" href="{{ '/' | relative_url }}"></data>
89+
<div class="wrapper">
90+
<div class="footer-col-wrapper">
91+
<div class="footer-col">
92+
<p class="p-name">{{ site.title | escape }}</p>
93+
<p>{{ site.description | escape }}</p>
94+
</div>
95+
<div class="footer-col">
96+
<p>{{ site.footer.copyright | escape }}</p>
97+
</div>
98+
</div>
99+
</div>
100+
</footer>
101+
</body>
102+
</html>
103+
104+

0 commit comments

Comments
 (0)