Skip to content

Commit d660934

Browse files
pc-studypc-study
committed
docs: add AI maintenance handoff guide (.github/AI-GUIDE.md)
Concise reference document optimized for AI agents taking over site maintenance. Covers file map, i18n rules, cache busting, component architecture, common tasks, CSS tokens, and pitfalls.
1 parent 9e1825c commit d660934

File tree

1 file changed

+210
-0
lines changed

1 file changed

+210
-0
lines changed

‎.github/AI-GUIDE.md‎

Lines changed: 210 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,210 @@
1+
# AI Maintenance Guide — OracleShellInstall Website
2+
3+
> **Read this first.** This is the only file you need to understand the entire project.
4+
> For deep-dive details, read `DEVELOPMENT.md` in the repo root.
5+
6+
## What This Project Is
7+
8+
Static website for **OracleShellInstall** — a shell script that automates Oracle Database installation (11gR2–26ai) on 20+ Linux distros. The site has a command generator, docs, compatibility matrix, and 255 installation guide pages.
9+
10+
- **Hosting**: GitHub Pages, `main` branch auto-deploys
11+
- **Domain**: www.oracleshellinstall.com
12+
- **Stack**: Vanilla HTML/CSS/JS, no build tools, no frameworks
13+
- **Languages**: Chinese (default) + English via client-side i18n
14+
15+
---
16+
17+
## File Map
18+
19+
```
20+
/ # repo root = site root
21+
├── index.html # Homepage (hero + terminal animation + features + trust)
22+
├── generator.html # Command generator (interactive form → shell command)
23+
├── docs.html # Documentation (sidebar TOC + search + scroll spy)
24+
├── compat.html # Compatibility matrix (OS × Oracle version, 182 tutorials)
25+
├── pricing.html # Edition comparison (社区版 vs 专业版)
26+
├── download.html # Download center (paid users)
27+
├── 404.html # Custom error page
28+
├── css/style.css # Global stylesheet (CSS variables, components, responsive)
29+
├── js/shared.js # Core module (nav, footer, i18n, theme, code blocks)
30+
├── js/search.js # Client-side full-text search
31+
├── sw.js # Service Worker (cache: os-v9)
32+
├── manifest.json # PWA manifest
33+
├── search-index.json # Search index (188 entries)
34+
├── sitemap.xml # SEO sitemap
35+
├── DEVELOPMENT.md # Full development history (38KB, Chinese)
36+
├── guides/ # 255 installation tutorial pages
37+
│ ├── guide.css # Guide-specific styles
38+
│ ├── *.html # Individual guides
39+
│ └── img/ # Guide screenshots
40+
└── img/ # Site assets (og-cover, wechat-qr, icons)
41+
```
42+
43+
---
44+
45+
## Critical Architecture Rules
46+
47+
### 1. i18n System (MOST COMMON SOURCE OF BUGS)
48+
49+
**How it works:**
50+
- HTML default content = Chinese. English lives in JS `i18n.en` object.
51+
- Elements marked with `data-i18n="keyName"` get their innerHTML replaced on language switch.
52+
- `setLang()` in `shared.js` saves original Chinese HTML to `data-i18n-zh` attribute on first encounter, then swaps content.
53+
54+
**The #1 rule:**
55+
> `pageI18n.zh["keyName"]` MUST exactly match the HTML element's default innerHTML (byte-for-byte, including whitespace).
56+
> If they differ, switching EN → ZH will show the `pageI18n.zh` value instead of restoring the original HTML, causing visual glitches.
57+
58+
**Where translations live:**
59+
| Scope | Location |
60+
|-------|----------|
61+
| Shared (nav, footer, buttons) | `js/shared.js` → `i18n.zh` / `i18n.en` |
62+
| Page-specific | Each page's inline `<script>` → `pageI18n.zh` / `pageI18n.en`, merged via `Object.assign(i18n.zh, pageI18n.zh)` |
63+
64+
**Adding a new translated element:**
65+
```html
66+
<span data-i18n="myKey">中文内容</span>
67+
```
68+
```javascript
69+
// In the page's inline script or shared.js:
70+
Object.assign(i18n.zh, { myKey: '中文内容' }); // MUST match HTML exactly
71+
Object.assign(i18n.en, { myKey: 'English content' });
72+
```
73+
74+
**Testing i18n round-trip:**
75+
Switch to English → switch back to Chinese → verify Chinese matches original. Automated: use Playwright to compare `el.innerHTML` before and after EN→ZH round-trip.
76+
77+
### 2. Cache Busting
78+
79+
All CSS/JS/manifest references across every HTML file use a query parameter:
80+
```html
81+
<link rel="stylesheet" href="css/style.css?v=20260320b">
82+
<script src="js/shared.js?v=20260320b"></script>
83+
```
84+
85+
When you modify CSS or JS, you MUST update the version string globally:
86+
```bash
87+
# Find current version
88+
grep -r "v=20260320b" --include="*.html" -l | head -5
89+
90+
# Replace everywhere (190+ files including guides/)
91+
find . -name "*.html" -exec sed -i 's/v=20260320b/v=NEW_VERSION/g' {} +
92+
```
93+
94+
Also bump the Service Worker cache name in `sw.js` line 1:
95+
```javascript
96+
const CACHE_NAME = 'os-v10'; // increment from current os-v9
97+
```
98+
99+
### 3. Navigation & Footer
100+
101+
Generated dynamically by `js/shared.js`:
102+
```javascript
103+
document.getElementById('nav').innerHTML = navHTML('home'); // param = active page ID
104+
document.getElementById('footer').innerHTML = footerHTML();
105+
```
106+
107+
Nav links: home, generator, docs, compat, subscribe, download
108+
CTA button: links to `generator.html` (not pricing)
109+
110+
Guide pages use `../` prefix automatically (detected by path).
111+
112+
### 4. Theme System
113+
114+
- Dark theme = default (CSS variables in `:root`)
115+
- Light theme = `[data-theme="light"]` overrides
116+
- Stored in `localStorage('theme')`
117+
- Terminal/code blocks stay dark even in light theme
118+
119+
### 5. docs.html Special Features
120+
121+
- **Dual content blocks**: `.doc-zh` (Chinese) and `.doc-en` (English), toggled by `display:none/block`
122+
- **Sidebar scroll spy**: IntersectionObserver highlights active section
123+
- **Search filter**: Filters sidebar links AND content sections
124+
- **Section IDs**: Chinese sections use `id="quickstart"`, English use `id="en-quickstart"`
125+
- **Sidebar click**: Automatically resolves to correct language prefix
126+
127+
### 6. generator.html
128+
129+
- Three modes: single / standalone / rac
130+
- Dynamic form shows/hides parameters per mode
131+
- Real-time command preview (only non-default params included)
132+
- Copy-to-clipboard button
133+
134+
### 7. pricing.html Terminology
135+
136+
- Free tier = **社区版** (Community Edition), NOT "开源版"
137+
- Paid tier = **专业版** (Pro Edition), NOT "付费版"
138+
- Missing features shown with `—` (em dash), NOT `✕` (red cross)
139+
- FAQ explains why some features aren't in community edition
140+
141+
---
142+
143+
## Common Maintenance Tasks
144+
145+
### Add a new page
146+
147+
1. Create HTML file with standard head (copy from existing page)
148+
2. Include `css/style.css?v=CURRENT` and `js/shared.js?v=CURRENT`
149+
3. Add `<div id="nav"></div>` and `<div id="footer"></div>`
150+
4. In inline script: call `navHTML('pageId')`, `footerHTML()`, register pageI18n, call `setLang(currentLang)`
151+
5. Add to `sitemap.xml` and `search-index.json`
152+
6. Add nav link in `shared.js` if it should appear in navigation
153+
154+
### Modify shared nav/footer
155+
156+
Edit `js/shared.js` — search for `function navHTML` or `function footerHTML`.
157+
158+
### Update search index
159+
160+
Edit `search-index.json`. Each entry:
161+
```json
162+
{ "url": "page.html", "title": "Page Title", "desc": "Short description", "text": "Full text content for search matching" }
163+
```
164+
165+
### Add a guide tutorial
166+
167+
1. Create `guides/TIMESTAMP.html` (use existing guide as template)
168+
2. Add entry to `search-index.json`
169+
3. Add `<url>` to `sitemap.xml`
170+
4. Add link in `compat.html` compatibility matrix
171+
172+
---
173+
174+
## CSS Design Tokens
175+
176+
```
177+
Brand red: --red: #C74634
178+
Glow red: --red-glow: #e05a48
179+
Background: --bg: #0a0a0e → --bg2: #111118 → --bg3: #181822
180+
Cards: --card: #14141d
181+
Text: --text: #e8e6e3 → --text-dim: #9a9aaa → --text-muted: #5a5a6e
182+
Border: --border: #232334
183+
Accent: --accent2: #e8934a, --green: #3aba6a, --blue: #4a8fe8
184+
Fonts: --font: 'Noto Sans SC', --mono: 'JetBrains Mono', --display: 'Orbitron'
185+
Radii: --r-sm: 6px, --r: 10px, --r-lg: 14px
186+
Nav height: --nav-h: 64px
187+
Max width: --max-w: 1160px
188+
```
189+
190+
Responsive breakpoints: 768px (mobile), 900px (tablet), 1200px (wide)
191+
192+
---
193+
194+
## Git Conventions
195+
196+
- Commit prefixes: `feat:`, `fix:`, `enhance:`, `cleanup:`, `refactor:`, `docs:`
197+
- Push to `main` = auto-deploy to GitHub Pages
198+
- No build step needed
199+
- `.playwright-cli/` is gitignored (test artifacts)
200+
201+
---
202+
203+
## Known Pitfalls
204+
205+
1. **i18n zh mismatch**: If HTML default and `pageI18n.zh` differ, EN→ZH switch breaks. Always keep them identical.
206+
2. **Cache stale**: After editing CSS/JS, forgetting to bump `?v=` means users see old versions.
207+
3. **SW cache name**: Must bump `CACHE_NAME` in `sw.js` when changing static assets, or old SW serves stale files.
208+
4. **Guide paths**: Guides are in `guides/` subdirectory — all asset references use `../css/`, `../js/`, `../img/`.
209+
5. **Large page edits**: `docs.html` has dual zh/en content blocks (~1200 lines). Edits to one language block must be mirrored in the other.
210+
6. **Tables in docs.html**: Parameter tables use `resp-cards` class for mobile card layout. New tables need `<div class="doc-table-wrap"><table class="param-table resp-cards">`.

0 commit comments

Comments
 (0)