Skip to content

Commit 070d447

Browse files
robertvokacclaude
robertvokac
and
claude
committed
docs: add Markdown migration analysis to PLAN.md
Adds Part 2 of the plan: full analysis of HTML constructs across 125 pages, proposed Markdown file format with YAML front-matter, recommended Python build pipeline, and migration strategy. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
1 parent dd618f4 commit 070d447

1 file changed

Lines changed: 242 additions & 0 deletions

File tree

‎PLAN.md‎

Lines changed: 242 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,247 @@
11
# OpenEggbert.com — Refactoring Plan
22

3+
---
4+
5+
## Part 2 — Markdown Source + HTML Generation Analysis
6+
7+
### Goal
8+
9+
Write all page content as Markdown files and use a build script to generate the same HTML+CSS output that currently exists, without changing the visual appearance.
10+
11+
---
12+
13+
### 2.1 Complete Inventory of HTML Constructs in `<main>`
14+
15+
The following table covers **all** HTML constructs found across the 125 article pages.
16+
17+
#### Standard constructs — map directly to Markdown
18+
19+
| HTML construct | Count of pages | Markdown equivalent |
20+
|---|---|---|
21+
| `<h1>` … `<h4>` | all pages | `# … ####` |
22+
| `<p>` | ~70 pages | blank line between paragraphs |
23+
| `<br>` (line break) | very common | two trailing spaces or `\` at end of line (CommonMark) |
24+
| `<ul>` / `<ol>` / `<li>` | ~110 pages | `- item` / `1. item` |
25+
| `<b>` / `<strong>` | ~90 pages | `**text**` |
26+
| `<i>` / `<em>` | ~20 pages | `*text*` |
27+
| `<s>` strikethrough | 2 pages | `~~text~~` (GFM extension) |
28+
| `<a href="…">` plain links | all pages | `[label](href)` |
29+
| `<code>` inline | ~15 pages | `` `code` `` |
30+
| `<pre><code>` block | 14 pages | ```` ```lang … ``` ```` fenced block |
31+
| `<blockquote>` | 5 pages | `> text` |
32+
| `<hr>` | 4 pages | `---` |
33+
| `<img src alt width>` | ~20 pages | `![alt](src)` |
34+
35+
#### Constructs needing custom handling
36+
37+
| HTML construct | Pages | Problem | Solution |
38+
|---|---|---|---|
39+
| `<table class="infobox">` | 14 | Floating right, complex colspan, links inside cells | Raw HTML block in Markdown; or YAML front-matter shorthand |
40+
| `<table>` with `rowspan`/`colspan` | ~12 | Markdown tables do not support merged cells | Keep as raw HTML block in Markdown |
41+
| `<table>` simple (no merge) | ~8 | Supported | Markdown pipe table syntax |
42+
| `<a class="ref">` | 6 pages | Custom CSS class on link | `[text](url){.ref}` using `attr_list` extension, or raw HTML |
43+
| `<ul id="tags">` at page bottom | 11 | Semantic tag list | YAML front-matter `tags:` list; template renders it |
44+
| `<figure>` + `<figcaption>` | 3 | No native Markdown equivalent | Raw HTML block, or `![alt](src "caption")` + custom CSS |
45+
| `<div style="background: orange;">` | 1 | Warning/callout box | `> [!WARNING]` callout syntax (GitHub-flavored) or custom class via `attr_list` |
46+
| `style="background:#bbbbbb"` on `<b>` | 4 occurrences | Inline highlighted term | Raw HTML `<b style="…">` inside Markdown |
47+
| `style="max-width:300px;"` on `<img>` | 17 occurrences | Image size constraint | `![alt](src){style="max-width:300px;"}` with `attr_list`, or raw `<img>` |
48+
| `style="display:block"` on `<a>` | 51 occurrences | All in one large table page (`Blupi_websites`) | Keep that page as raw HTML; or add `.block` CSS class |
49+
| `<main style="background: #f5b7b1;">` | 1 (error page) | Special background on error page | Front-matter `body_class: error` and template adds inline style |
50+
51+
#### Constructs that disappear (handled by template / JS)
52+
53+
| HTML construct | Reason disappears |
54+
|---|---|
55+
| `<header>` + `<nav>` | Already injected by `buildPage()` |
56+
| `<footer>` | Already injected by `buildPage()` |
57+
| `<div id="tocButton">` + `<div id="toc">` | Already generated by `loadContent()` — the template adds them |
58+
| `<body onload=…>` | Template uses `DOMContentLoaded` |
59+
| `<script>PAGE_CONFIG={…}</script>` | Template generates this from front-matter |
60+
| `<meta description/keywords/author>` | Already injected by `buildPage()` |
61+
| `<base href="…">` | Template calculates depth from file path |
62+
| `<section>` wrapper | Template wraps content in `<section>` automatically |
63+
64+
---
65+
66+
### 2.2 Proposed Markdown File Format
67+
68+
Every article becomes one `.md` file with a YAML front-matter header. The front-matter replaces `PAGE_CONFIG` and provides metadata. The rest is standard Markdown.
69+
70+
```markdown
71+
---
72+
title: "Speedy Blupi (Windows)"
73+
breadcrumb:
74+
- {label: "Blupi", href: "Blupi/index.html"}
75+
- {label: "Games", href: "Blupi/Games/index.html"}
76+
- {label: "Speedy Blupi (Windows)", href: "Blupi/Games/Speedy_Blupi_(Windows)/index.html"}
77+
subpages:
78+
- {label: "Go Up", href: "Blupi/Games/index.html"}
79+
- {label: "Blocks", href: "Blupi/Games/Speedy_Blupi_(Windows)/Blocks/index.html"}
80+
- {label: "Levels", href: "Blupi/Games/Speedy_Blupi_(Windows)/Levels/index.html"}
81+
tags:
82+
- "Games created by Daniel Roux"
83+
---
84+
85+
<!-- Raw HTML infobox (kept as-is) -->
86+
<table class="infobox"> … </table>
87+
88+
## Introduction
89+
90+
Speedy Blupi is a 2D [platformer](Article_does_not_yet_exist_or_link_is_broken/index.html) game
91+
originally developed by Swiss company [Epsitec](Blupi/Epsitec/index.html).
92+
93+
## Minimum system requirements
94+
95+
- PC Windows 95/98/98SE/Me/2000/XP/Vista/7/8/10/11
96+
- [Pentium 100](Technologies/Programming_languages/Assembly_Language/I586/Pentium_100/index.html) MHz CPU
97+
- 16 MB RAM
98+
99+
## Code example
100+
101+
```java
102+
float velocityY = 0;
103+
final float gravity = -0.5f;
104+
```
105+
106+
<!-- Simple tables as Markdown pipe syntax -->
107+
| Header A | Header B |
108+
|---|---|
109+
| value 1 | value 2 |
110+
111+
<!-- Complex tables (rowspan/colspan) kept as raw HTML -->
112+
<table>
113+
<tr><th rowspan="2">Name</th><th colspan="2">Effects</th></tr>
114+
…
115+
</table>
116+
117+
[External source](https://example.com){.ref}
118+
```
119+
120+
---
121+
122+
### 2.3 Recommended Build Tool: Python + `python-markdown`
123+
124+
**Why Python:**
125+
- Already used in this project (the transformation script is Python)
126+
- No new runtime to install
127+
- `python-markdown` library with extensions handles 90 % of constructs natively
128+
129+
**Extensions needed from `python-markdown`:**
130+
131+
| Extension | Purpose |
132+
|---|---|
133+
| `tables` | Basic pipe-table syntax |
134+
| `fenced_code` | ```` ```lang … ``` ```` code blocks |
135+
| `attr_list` | Add `{.classname}` / `{style="…"}` to any element |
136+
| `toc` | Auto-generate heading ids (already done by JS, but useful for anchors) |
137+
| `nl2br` | Convert single newlines to `<br>` (matches current heavy `<br>` usage) |
138+
| `sane_lists` | Correct list nesting |
139+
| `meta` | Read YAML-style front-matter (or use PyYAML separately) |
140+
| `md_in_html` | Allow Markdown inside raw HTML blocks |
141+
142+
**Alternative: Pandoc (single binary)**
143+
144+
Pandoc can convert Markdown → HTML with a custom `--template` flag. It supports all the above natively plus finer control over raw HTML passthrough. The downside is it requires installing the Pandoc binary (~30 MB), which is non-trivial in CI without caching.
145+
146+
---
147+
148+
### 2.4 Build Script Architecture
149+
150+
```
151+
src/
152+
About/
153+
index.md ← Markdown content + front-matter
154+
Abbreviations/
155+
index.md
156+
Blupi/
157+
index.md
158+
Games/
159+
Speedy_Blupi_(Windows)/
160+
index.md
161+
Levels/
162+
I/
163+
060/
164+
index.md
165+
…
166+
_template.html ← HTML shell (head + script refs, buildPage calls)
167+
168+
build.py ← reads src/**/*.md, writes root/**/*.html
169+
styles.css ← unchanged
170+
script.js ← unchanged (buildPage + loadContent)
171+
```
172+
173+
**`build.py` logic (per file):**
174+
175+
1. Read `src/.../index.md`
176+
2. Parse YAML front-matter (title, breadcrumb, subpages, tags, optional depth)
177+
3. Convert Markdown body → HTML fragment using `python-markdown`
178+
4. Calculate `<base href>` from file depth
179+
5. Generate `<script>PAGE_CONFIG={…}</script>` from front-matter
180+
6. Generate `<ul id="tags">` from `tags:` list (if present)
181+
7. Write the full HTML to the matching path under the root (e.g. `About/index.html`)
182+
183+
The output HTML files are byte-for-byte compatible with the current format — the same `script.js` and `styles.css` work unchanged.
184+
185+
---
186+
187+
### 2.5 What Stays as Raw HTML in Markdown
188+
189+
These constructs are kept as raw HTML blocks directly inside the `.md` files and passed through unchanged by the Markdown processor:
190+
191+
1. **`<table class="infobox">`** — all 14 occurrences; too complex and unique to convert
192+
2. **Tables with `rowspan`/`colspan`** — ~12 pages (Cheats table, Level tables, Blupi_websites)
193+
3. **`<figure><img …><figcaption>`** — 3 pages
194+
4. **`<div style="background: orange;">` callout boxes** — 1 page
195+
5. **Bold text with `style="background:#bbbbbb"`** — 4 occurrences (could add a `.highlight` CSS class instead)
196+
197+
Estimated **raw HTML percentage: ~10–15 %** of content volume across the site. The remaining 85–90 % converts cleanly to readable Markdown.
198+
199+
---
200+
201+
### 2.6 Migration Strategy (no changes to existing pages during migration)
202+
203+
1. **Phase 1 (setup):** Create `src/` directory and `build.py`. Write the HTML template. Set up GitHub Actions to run `build.py` and commit the generated HTML back to the repo on every push to `src/`.
204+
2. **Phase 2 (pilot):** Convert 5–10 small pages from HTML → Markdown, verify output is visually identical.
205+
3. **Phase 3 (bulk conversion):** Use a Python script to auto-convert the existing `index.html` files to `index.md` (reverse of `build.py`). Auto-conversion handles ~85 % of pages. Manually fix the remaining 15 % with complex tables/infoboxes.
206+
4. **Phase 4 (switch):** Once all Markdown sources are verified, the generated HTML files are the only files committed to the root. Source `.md` files live in `src/`.
207+
208+
**CI/CD pipeline (GitHub Actions):**
209+
210+
```yaml
211+
name: Build site
212+
on:
213+
push:
214+
paths: ['src/**', 'build.py', '_template.html']
215+
jobs:
216+
build:
217+
runs-on: ubuntu-latest
218+
steps:
219+
- uses: actions/checkout@v4
220+
- run: pip install markdown PyYAML
221+
- run: python build.py
222+
- uses: actions/upload-pages-artifact@v3
223+
with: {path: '.'}
224+
```
225+
226+
Or simpler: commit generated HTML directly to the repo (no separate artifact step), which keeps GitHub Pages working without changing the deployment method.
227+
228+
---
229+
230+
### 2.7 Pros and Cons Summary
231+
232+
| Aspect | Current (raw HTML) | After Markdown migration |
233+
|---|---|---|
234+
| Writing a new article | ~15-line HTML shell + content HTML | Pure Markdown text, no HTML knowledge needed |
235+
| Infoboxes | Write table HTML by hand | Still write table HTML (raw block) |
236+
| Simple tables | HTML table markup | Markdown pipe syntax |
237+
| Links | `<a href="…">label</a>` | `[label](href)` |
238+
| Build step required | No | Yes (Python script + GitHub Actions) |
239+
| Previewing in editor | Browser only | Any Markdown editor (VS Code, Obsidian, etc.) |
240+
| Raw HTML still needed | Everywhere | ~10–15 % of content (complex tables, infoboxes) |
241+
| Risk | Low (already done) | Medium (new build pipeline to maintain) |
242+
243+
---
244+
3245
## 1. Current State Analysis
4246

5247
### What the site is

0 commit comments

Comments
 (0)