Skip to content

Commit 76e9994

Browse files
bcomnesbcomnes
committed
Add block diagram
1 parent 03ffd27 commit 76e9994

File tree

1 file changed

+158
-0
lines changed

1 file changed

+158
-0
lines changed

‎README.md‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1167,6 +1167,164 @@ Look at [examples](./examples/) and `domstack` [dependents](https://github.com/b
11671167

11681168
These tools are treated as implementation details, but they may be exposed more in the future. The idea is that they can be swapped out for better tools in the future if they don't make it.
11691169

1170+
### Build Process Flow
1171+
1172+
The following diagram illustrates the DomStack build process:
1173+
1174+
```
1175+
┌─────────────┐
1176+
│ START │
1177+
└──────┬──────┘
1178+
│
1179+
▼
1180+
┌──────────────────┐
1181+
│ identifyPages() │
1182+
│ │
1183+
│ • Find pages │
1184+
│ • Find layouts │
1185+
│ • Find templates │
1186+
│ • Find globals │
1187+
│ • Find settings │
1188+
└────────┬─────────┘
1189+
│
1190+
│
1191+
┌───────────────────┼───────────────────┐
1192+
│ │ │
1193+
▼ ▼ ▼
1194+
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
1195+
│ buildEsbuild() │ │ buildStatic() │ │ buildCopy() │
1196+
│ │ │ │ │ │
1197+
│ • Bundle JS/CSS │ │ • Copy static │ │ • Copy extra │
1198+
│ • Generate │ │ files │ │ directories │
1199+
│ metafile │ │ (if enabled) │ │ from opts │
1200+
└────────┬────────┘ └────────┬────────┘ └────────┬────────┘
1201+
│ │ │
1202+
└───────────────────┼───────────────────┘
1203+
│
1204+
▼
1205+
┌──────────────────┐
1206+
│ buildPages() │
1207+
│ │
1208+
│ • Process HTML │
1209+
│ • Process MD │
1210+
│ • Process JS │
1211+
│ • Apply layouts │
1212+
└────────┬─────────┘
1213+
│
1214+
▼
1215+
┌──────────────────┐
1216+
│ Return Results │
1217+
│ │
1218+
│ • siteData │
1219+
│ • esbuildResults │
1220+
│ • staticResults │
1221+
│ • copyResults │
1222+
│ • pageResults │
1223+
│ • warnings │
1224+
└──────────────────┘
1225+
```
1226+
1227+
The build process follows these key steps:
1228+
1229+
1. **Page identification** - Scans the source directory to identify all pages, layouts, templates, and global assets
1230+
2. **Destination preparation** - Ensures the destination directory is ready for the build output
1231+
3. **Parallel asset processing** - Three operations run concurrently:
1232+
- JavaScript and CSS bundling via esbuild
1233+
- Static file copying (when enabled)
1234+
- Additional directory copying (from `--copy` options)
1235+
4. **Page building** - Processes all pages, applying layouts and generating final HTML
1236+
1237+
This architecture allows for efficient parallel processing of independent tasks while maintaining the correct build order dependencies.
1238+
1239+
#### buildPages() Detail
1240+
1241+
The `buildPages()` step processes pages in parallel with a concurrency limit:
1242+
1243+
```
1244+
┌──────────────────┐
1245+
│ buildPages() │
1246+
└────────┬─────────┘
1247+
│
1248+
┌────────▼─────────┐
1249+
│ Resolve Once: │
1250+
│ • Global vars │
1251+
│ • All layouts │
1252+
└────────┬─────────┘
1253+
│
1254+
┌────────────▼───────────────┐
1255+
│ Parallel Page Queue │
1256+
│(Concurrency: min(CPUs, 24))│
1257+
└────────────┬───────────────┘
1258+
│
1259+
┌────────────────────┼────────────────────┐
1260+
│ │ │
1261+
▼ ▼ ▼
1262+
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
1263+
│ MD Page Task │ │ HTML Page Task │ │ JS Page Task │
1264+
├─────────────────┤ ├─────────────────┤ ├─────────────────┤
1265+
│ ┌─────────────┐ │ │ ┌─────────────┐ │ │ ┌─────────────┐ │
1266+
│ │1. Read .md │ │ │ │1. Read .html│ │ │ │1. Import .js│ │
1267+
│ │ file │ │ │ │ file │ │ │ │ module │ │
1268+
│ └──────┬──────┘ │ │ └──────┬──────┘ │ │ └──────┬──────┘ │
1269+
│ ▼ │ │ ▼ │ │ ▼ │
1270+
│ ┌─────────────┐ │ │ ┌─────────────┐ │ │ ┌─────────────┐ │
1271+
│ │2. Extract │ │ │ │2. Variable │ │ │ │2. Variable │ │
1272+
│ │ frontmatter │ │ │ │ Resolution │ │ │ │ Resolution │ │
1273+
│ └──────┬──────┘ │ │ └──────┬──────┘ │ │ └──────┬──────┘ │
1274+
│ ▼ │ │ ▼ │ │ ▼ │
1275+
│ ┌─────────────┐ │ │ ┌─────────────┐ │ │ ┌─────────────┐ │
1276+
│ │ Frontmatter │ │ │ │page.vars.js │ │ │ │ Exported │ │
1277+
│ │ vars │ │ │ │ │ │ │ │ vars │ │
1278+
│ └──────┬──────┘ │ │ └──────┬──────┘ │ │ └──────┬──────┘ │
1279+
│ ▼ │ │ ▼ │ │ ▼ │
1280+
│ ┌─────────────┐ │ │ ┌─────────────┐ │ │ ┌─────────────┐ │
1281+
│ │page.vars.js │ │ │ │ postVars │ │ │ │page.vars.js │ │
1282+
│ │ │ │ │ │ │ │ │ │ │ │
1283+
│ └──────┬──────┘ │ │ └──────┬──────┘ │ │ └──────┬──────┘ │
1284+
│ ▼ │ │ ▼ │ │ ▼ │
1285+
│ ┌─────────────┐ │ │ ┌─────────────┐ │ │ ┌─────────────┐ │
1286+
│ │ postVars │ │ │ │3. Handlebars│ │ │ │ postVars │ │
1287+
│ │ │ │ │ │ (if enabled)│ │ │ │ │ │
1288+
│ └──────┬──────┘ │ │ └──────┬──────┘ │ │ └──────┬──────┘ │
1289+
│ ▼ │ │ ▼ │ │ ▼ │
1290+
│ ┌─────────────┐ │ │ ┌─────────────┐ │ │ ┌─────────────┐ │
1291+
│ │3. Render MD │ │ │ │4. Render │ │ │ │3. Execute │ │
1292+
│ │ to HTML │ │ │ │ with layout│ │ │ │ page func │ │
1293+
│ └──────┬──────┘ │ │ └──────┬──────┘ │ │ └──────┬──────┘ │
1294+
│ ▼ │ │ ▼ │ │ ▼ │
1295+
│ ┌─────────────┐ │ │ ┌─────────────┐ │ │ ┌─────────────┐ │
1296+
│ │4. Extract │ │ │ │5. Write HTML│ │ │ │4. Render │ │
1297+
│ │ title (h1) │ │ │ │ │ │ │ │ with layout│ │
1298+
│ └──────┬──────┘ │ │ └─────────────┘ │ │ └──────┬──────┘ │
1299+
│ ▼ │ │ │ │ ▼ │
1300+
│ ┌─────────────┐ │ │ │ │ ┌─────────────┐ │
1301+
│ │5. Render │ │ │ │ │ │5. Write HTML│ │
1302+
│ │ with layout│ │ │ │ │ │ │ │
1303+
│ └──────┬──────┘ │ │ │ │ └─────────────┘ │
1304+
│ ▼ │ │ │ │ │
1305+
│ ┌─────────────┐ │ │ │ │ │
1306+
│ │6. Write HTML│ │ │ │ │ │
1307+
│ └─────────────┘ │ │ │ │ │
1308+
└─────────────────┘ └─────────────────┘ └─────────────────┘
1309+
│ │ │
1310+
└──────────────────────┼──────────────────────┘
1311+
│
1312+
▼
1313+
┌──────────────────┐
1314+
│ Complete when │
1315+
│ all pages done │
1316+
└──────────────────┘
1317+
```
1318+
1319+
Variable Resolution Layers:
1320+
- **Global vars** - Site-wide variables from `global.vars.js` (resolved once)
1321+
- **Layout vars** - Layout-specific variables from layout functions (resolved once)
1322+
- **Page-specific vars** vary by type:
1323+
- **MD pages**: frontmatter → page.vars.js → postVars
1324+
- **HTML pages**: page.vars.js → postVars
1325+
- **JS pages**: exported vars → page.vars.js → postVars
1326+
- **postVars** - Post-processing function that can modify variables based on all resolved data
1327+
11701328
## Roadmap
11711329

11721330
`domstack` works and has a rudimentary watch command, but hasn't been battle tested yet.

0 commit comments

Comments
 (0)