refactor: organize code into blog/, material/, shared/ folders

- Move blog-specific files to blog/
- Move material-specific files to material/
- Move shared utilities to shared/
- Delete obsolete build-blog.ts and build-material.ts
- Add types.d.ts for marked-gfm-heading-id
- Update imports and README
- Fix package.json name and remove unused main field
- Remove dead code (parsedYaml ?? {})
- Remove error field from MaterialEntry (website-only)

Author: JohannesHoppe

.github/workflows/test.yml

@@ -21,5 +21,8 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
+      - name: Typecheck
+        run: npm run typecheck
+
       - name: Run tests
         run: npm test

README.md

@@ -2,7 +2,7 @@
 
 Shared build scripts for processing Markdown blog entries into JSON.
 
-Used as a git submodule in:
+Used as a git subtree in:
 - [angular-buch/website-articles](https://github.com/angular-buch/website-articles)
 - [angular-schule/website-articles](https://github.com/angular-schule/website-articles)
 
@@ -13,15 +13,31 @@ npm install
 npm run build
 ```
 
-## Build Scripts
+## Scripts
 
-| Script           | Description                                                      |
-|------------------|------------------------------------------------------------------|
-| `build:init`     | Clears `dist/`                                                   |
-| `build:blog`     | Builds blog entries from `../blog/` → `dist/blog/`               |
-| `build:material` | Builds material entries from `../material/` → `dist/material/`   |
+| Script       | Description                          |
+|--------------|--------------------------------------|
+| `build`      | Build blog and material entries      |
+| `test`       | Run tests                            |
+| `test:watch` | Run tests in watch mode              |
+| `typecheck`  | TypeScript type checking             |
+| `watch`      | Watch mode for development           |
 
-**Note:** `build:material` gracefully exits if no `../material/` folder exists.
+## Folder Structure
+
+```
+├── build.ts                 # Main entry point
+├── blog/
+│   ├── blog.types.ts        # Blog-specific types
+│   └── blog.utils.ts        # Blog list utilities
+├── material/
+│   └── material.types.ts    # Material-specific types
+└── shared/
+    ├── base.types.ts        # Shared base types
+    ├── base.utils.ts        # File/folder utilities
+    ├── list.utils.ts        # List extraction utilities
+    └── jekyll-markdown-parser.ts  # Markdown parser
+```
 
 ## URL Placeholder
 
@@ -31,8 +47,12 @@ Generated URLs use `%%MARKDOWN_BASE_URL%%` as a placeholder:
 
 The consuming website replaces this placeholder with the actual base URL at runtime.
 
-## Tests
+## Input/Output
 
-```bash
-npm test
-```
+**Input:** `../blog/` and `../material/` folders with Markdown READMEs
+
+**Output:** `./dist/` folder with:
+- `dist/blog/list.json` - Light blog list for overview
+- `dist/blog/{slug}/entry.json` - Full blog entry
+- `dist/material/list.json` - Light material list
+- `dist/material/{slug}/entry.json` - Full material entry

blog.types.ts blog/blog.types.tsblog.types.ts renamed to blog/blog.types.ts

@@ -1,4 +1,4 @@
-import { ImageDimensions } from "./base.types";
+import { ImageDimensions } from "../shared/base.types";
 
 /**
  * Blog entry metadata for the LIGHT list (list.json).

blog.utils.spec.ts blog/blog.utils.spec.tsblog.utils.spec.ts renamed to blog/blog.utils.spec.ts

@@ -15,7 +15,9 @@ describe('makeLightBlogList', () => {
         published: '2024-01-01T00:00:00.000Z',
         language: 'en',
         header: { url: 'header.jpg', width: 800, height: 400 },
-        'darken-header': false,
+        hidden: false,
+        sticky: false,
+        darkenHeader: false,
         ...overrides.meta,
       },
       ...overrides,
@@ -68,7 +70,7 @@ describe('makeLightBlogList', () => {
           language: 'de',
           header: { url: 'img.jpg', width: 100, height: 50 },
           hidden: false,
-          'darken-header': true,
+          darkenHeader: true,
           keywords: ['angular', 'test'],
           bio: 'Some bio',
           sticky: true,
@@ -88,11 +90,11 @@ describe('makeLightBlogList', () => {
     expect(meta.header).toEqual({ url: 'img.jpg', width: 100, height: 50 });
 
     // These should NOT be included in light version
-    expect((meta as any).hidden).toBeUndefined();
-    expect((meta as any)['darken-header']).toBeUndefined();
-    expect((meta as any).keywords).toBeUndefined();
-    expect((meta as any).bio).toBeUndefined();
-    expect((meta as any).sticky).toBeUndefined();
+    expect(Object.hasOwn(meta, 'hidden')).toBe(false);
+    expect(Object.hasOwn(meta, 'darkenHeader')).toBe(false);
+    expect(Object.hasOwn(meta, 'keywords')).toBe(false);
+    expect(Object.hasOwn(meta, 'bio')).toBe(false);
+    expect(Object.hasOwn(meta, 'sticky')).toBe(false);
   });
 
   it('should include author2 and mail2 if present', () => {

blog.utils.ts blog/blog.utils.tsblog.utils.ts renamed to blog/blog.utils.ts

@@ -1,5 +1,5 @@
 import { BlogEntry, BlogEntryFull } from './blog.types';
-import { extractFirstBigParagraph } from './list.utils';
+import { extractFirstBigParagraph } from '../shared/list.utils';
 
 export function makeLightBlogList(fullList: BlogEntryFull[]): BlogEntry[] {
   return fullList

build-blog.ts

@@ -2,12 +2,12 @@ import { existsSync } from 'fs';
 import * as path from 'path';
 import { mkdirp, remove, writeJson } from 'fs-extra';
 
-import { BlogEntryFull } from './blog.types';
-import { MaterialEntry } from './material.types';
-import { copyEntriesToDist, getEntryList } from './base.utils';
-import { makeLightBlogList } from './blog.utils';
-import { makeLightList } from './list.utils';
-import { MARKDOWN_BASE_URL_PLACEHOLDER } from './jekyll-markdown-parser';
+import { BlogEntryFull } from './blog/blog.types';
+import { MaterialEntry } from './material/material.types';
+import { copyEntriesToDist, getEntryList } from './shared/base.utils';
+import { makeLightBlogList } from './blog/blog.utils';
+import { makeLightList } from './shared/list.utils';
+import { MARKDOWN_BASE_URL_PLACEHOLDER } from './shared/jekyll-markdown-parser';
 
 const DIST_FOLDER = './dist';
 const BLOG_FOLDER = '../blog';

build-material.ts

@@ -1,4 +1,4 @@
-import { EntryBase, EntryMetaBase } from "./base.types";
+import { EntryBase, EntryMetaBase } from "../shared/base.types";
 
 /**
  * Material entry metadata.

build.ts

@@ -1,7 +1,6 @@
 {
-  "name": "website-articles",
+  "name": "website-articles-build",
   "version": "1.0.0",
-  "main": "index.js",
   "scripts": {
     "build": "tsx build.ts",
     "watch": "nodemon --watch ../blog --watch ../material -e md,jpg,png,svg --exec 'npm run build'",