cook-ssg 2.10.0 → 2.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -158,11 +158,12 @@ The build process performs the following steps, in this order:
158
158
  * Minifies HTML, CSS, and JS source (production only)
159
159
  8. **Generates fragments** - A sibling `_fragment.html` per page for SPA-style navigation (`fragments` config)
160
160
  9. **Generates formats** - Markdown copies under `/md/`, JSON under `/api/`, Atom feed, and `llms.txt` (`formats` config)
161
- 10. **Creates `sitemap.xml`** - When `sitemap.url` is set, written to the site root (`/dist`, or `/dist/<siteRoot>`); fragments excluded
162
- 11. **Creates bundled files** - `.css` and `.js` bundles are written
163
- 12. **Fingerprints assets** - Opt-in content-hash filenames with HTML and JS-import rewriting (`fingerprint` config)
164
- 13. **Applies `basePath`** - When set, prefixes root-relative URLs in built HTML for sub-path hosting (production only)
165
- 14. **Runs custom-user `after` plugins** - Runs once after file processing
161
+ 10. **Writes SocialSpec files** - With `about`, `contact` or `following` in `config/social.json`, writes `following.opml`, `about.md` and `contact.vcf` under `/.well-known/` and adds their `_headers` blocks
162
+ 11. **Creates `sitemap.xml`** - When `sitemap.url` is set, written to the site root (`/dist`, or `/dist/<siteRoot>`); fragments excluded
163
+ 12. **Creates bundled files** - `.css` and `.js` bundles are written
164
+ 13. **Fingerprints assets** - Opt-in content-hash filenames with HTML and JS-import rewriting (`fingerprint` config)
165
+ 14. **Applies `basePath`** - When set, prefixes root-relative URLs in built HTML for sub-path hosting (production only)
166
+ 15. **Runs custom-user `after` plugins** - Runs once after file processing
166
167
 
167
168
  A page that fails during the loop is reported (with its path) and skipped; the rest of the site still builds, a failure summary prints at the end, and the process exits non-zero so CI catches it.
168
169
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "cook-ssg",
3
- "version": "2.10.0",
3
+ "version": "2.11.0",
4
4
  "description": "Cook your static pages into a beautifully performing site. Static site generation the web platform way.",
5
5
  "type": "module",
6
6
  "bin": {
package/scripts/build.js CHANGED
@@ -39,6 +39,8 @@ import replaceInclude from './plugins/replace-include.js';
39
39
  import replaceInline from './plugins/replace-inline.js';
40
40
  import replaceMissingExternalLinkProtocol from './plugins/replace-external-link-protocol.js';
41
41
  import { socialData, fillSocialLinks } from './plugins/social-links.js';
42
+ import { writeSocialspecFiles } from './plugins/socialspec-files.js';
43
+ import { writeHeaderBlocks } from './plugins/headers.js';
42
44
  import replaceTemplateStrings from './plugins/replace-template-strings.js';
43
45
  import conditionalSections from './plugins/conditional-sections.js';
44
46
  import setActiveLinks from './plugins/set-active-links.js';
@@ -268,13 +270,13 @@ class Build {
268
270
  // built-in post-loop plugin so they all work with plain root paths.
269
271
  await applyBasePath();
270
272
 
271
- // Sandboxed programs: `_headers` rules (Cloudflare Pages, Netlify) appended
272
- // to the site's own `_headers`, which copySrc already placed in dist.
273
+ // Sandboxed programs and SocialSpec files: `_headers` rules (Cloudflare Pages,
274
+ // Netlify) appended to the site's own `_headers`, which copySrc already placed
275
+ // in dist. One read-modify-write for both sources.
273
276
  if (!Util.validatePageChange()) {
274
- const headersFile = path.join(siteRootDir(distPath, siteRoot), '_headers');
275
- const existing = fs.existsSync(headersFile) ? fs.readFileSync(headersFile, 'utf-8') : null;
276
- const headers = programHeaders(allPrograms(), existing);
277
- if (headers !== null) fs.writeFileSync(headersFile, headers);
277
+ const rootDir = siteRootDir(distPath, siteRoot);
278
+ const socialBlocks = writeSocialspecFiles({ data, rootDir });
279
+ writeHeaderBlocks(rootDir, [programHeaders(allPrograms(), null), socialBlocks]);
278
280
  }
279
281
 
280
282
  // CUSTOM PLUGINS: Run custom user plugins after file loop
@@ -0,0 +1,30 @@
1
+ /**
2
+ * @file headers.js
3
+ * @description One read-modify-write of the site's `_headers` (Cloudflare Pages,
4
+ * Netlify), shared by sandboxed programs and SocialSpec files. The site's own
5
+ * lines stay first and untouched; generated blocks follow in the order given.
6
+ */
7
+
8
+ import fs from 'fs-extra';
9
+ import path from 'node:path';
10
+
11
+ /**
12
+ * Append generated header blocks to the existing `_headers` text.
13
+ * @param {string|null} existing
14
+ * @param {Array<string|null>} blocks - block texts; null/empty are skipped
15
+ * @returns {string|null} null when there is nothing to add
16
+ */
17
+ export function appendHeaderBlocks(existing, blocks) {
18
+ const add = blocks.filter(Boolean);
19
+ if (!add.length) return null;
20
+ const text = add.join('\n');
21
+ return existing ? `${existing}\n${text}` : text;
22
+ }
23
+
24
+ /** Read `<rootDir>/_headers`, append the blocks, write once. No-op when none. */
25
+ export function writeHeaderBlocks(rootDir, blocks) {
26
+ const headersFile = path.join(rootDir, '_headers');
27
+ const existing = fs.existsSync(headersFile) ? fs.readFileSync(headersFile, 'utf-8') : null;
28
+ const out = appendHeaderBlocks(existing, blocks);
29
+ if (out !== null) fs.writeFileSync(headersFile, out);
30
+ }
@@ -6,8 +6,10 @@
6
6
  */
7
7
 
8
8
  import chalk from 'chalk';
9
+ import { marked } from 'marked';
9
10
  import Util from '../utils/util/util.js';
10
11
  import { getSocial } from '../utils/config/config.js';
12
+ import { resolveAboutBody } from './socialspec-files.js';
11
13
  import { normalizeAccounts, renderSocialLinks } from '../social/index.js';
12
14
 
13
15
  const TAG = '[social] ';
@@ -16,6 +18,12 @@ const SKIP_INSIDE = 'pre, code, template, textarea';
16
18
 
17
19
  let visibleAccounts = [];
18
20
 
21
+ /** The about body (or the contents of `about.file`) as HTML; undefined when there is none. */
22
+ function aboutHtml(about) {
23
+ const md = resolveAboutBody(about, process.cwd());
24
+ return md.trim() ? marked.parse(md) : undefined;
25
+ }
26
+
19
27
  /** Set `social` on the data store when a social config exists. */
20
28
  export async function socialData({ data }) {
21
29
  visibleAccounts = [];
@@ -25,6 +33,8 @@ export async function socialData({ data }) {
25
33
  for (const w of warnings) console.log(chalk.yellow(`${TAG}${w}`));
26
34
  visibleAccounts = visible;
27
35
  data.social = { ...(isObj(raw) ? raw : {}), accounts: visible, allAccounts: all };
36
+ const html = aboutHtml(isObj(raw) ? raw.about : undefined);
37
+ if (html !== undefined) data.social.aboutHtml = html;
28
38
  }
29
39
 
30
40
  /**
@@ -0,0 +1,118 @@
1
+ /**
2
+ * The about text as raw Markdown: `body` when it has text, else the contents of
3
+ * `about.file` (a path from `cwd`); '' when there is neither or the file is unreadable.
4
+ * Used by both the `social.aboutHtml` data and the about.md writer.
5
+ * @param {object} about
6
+ * @param {string} [cwd]
7
+ * @returns {string}
8
+ */
9
+ export function resolveAboutBody(about, cwd = process.cwd()) {
10
+ if (!isObj(about)) return '';
11
+ if (nonEmpty(about.body)) return about.body;
12
+ if (nonEmpty(about.file)) {
13
+ try { return fs.readFileSync(path.resolve(cwd, about.file), 'utf-8'); } catch { return ''; }
14
+ }
15
+ return '';
16
+ }
17
+
18
+ /**
19
+ * @file socialspec-files.js
20
+ * @description Writes the SocialSpec profile files under `<siteRoot>/.well-known/`
21
+ * (following.opml, about.md, contact.vcf) from the `social` config, and returns
22
+ * their `_headers` blocks. Each key is optional; a site with none writes nothing.
23
+ */
24
+
25
+ import chalk from 'chalk';
26
+ import fs from 'fs-extra';
27
+ import path from 'node:path';
28
+ import { getSocial, formats as formatsConfig } from '../utils/config/config.js';
29
+ import { renderOpml, renderAbout, renderVcard } from '../social/index.js';
30
+
31
+ const TAG = '[social] ';
32
+ const isObj = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
33
+ const nonEmpty = (v) => typeof v === 'string' && v.trim() !== '';
34
+ const warn = (msg) => console.log(chalk.yellow(`${TAG}${msg}`));
35
+ /** 'https', 'http' or null (not an absolute http(s) URL). */
36
+ const scheme = (u) => {
37
+ try {
38
+ const p = new URL(u).protocol;
39
+ return p === 'https:' ? 'https' : p === 'http:' ? 'http' : null;
40
+ } catch { return null; }
41
+ };
42
+
43
+ const TYPES = {
44
+ 'following.opml': 'text/x-opml; charset=utf-8',
45
+ 'about.md': 'text/markdown; charset=utf-8',
46
+ 'contact.vcf': 'text/vcard; charset=utf-8',
47
+ };
48
+
49
+ /** `_headers` block for one written file. */
50
+ export function socialHeaderBlock(name) {
51
+ return `/.well-known/${name}\n Content-Type: ${TYPES[name]}\n Access-Control-Allow-Origin: *\n`;
52
+ }
53
+
54
+ /**
55
+ * @param {object} opts
56
+ * @param {object} opts.data - build data (`siteUrl`, `siteTitle`)
57
+ * @param {string} opts.rootDir - the site root directory inside dist
58
+ * @param {string} [opts.cwd] - base for `about.file`
59
+ * @returns {string|null} `_headers` blocks for the files written, or null
60
+ */
61
+ export function writeSocialspecFiles({ data, rootDir, cwd = process.cwd() }) {
62
+ const raw = getSocial();
63
+ if (!isObj(raw)) return null;
64
+ const hasFollowing = Array.isArray(raw.following) && raw.following.some((e) => e && e.public !== false);
65
+ const hasAbout = isObj(raw.about);
66
+ const hasContact = isObj(raw.contact);
67
+ if (!hasFollowing && !hasAbout && !hasContact) return null;
68
+
69
+ const siteUrl = nonEmpty(data?.siteUrl) ? data.siteUrl.replace(/\/+$/, '') : '';
70
+ if (!siteUrl) warn('no siteUrl in the site data; SocialSpec URLs cannot be made absolute');
71
+ if (!formatsConfig?.feed) warn('formats.feed is not set. SocialSpec profiles start from the site feed');
72
+
73
+ const out = {};
74
+
75
+ if (hasFollowing) {
76
+ const kept = [];
77
+ for (const e of raw.following) {
78
+ if (!e || e.public === false) continue;
79
+ if (!nonEmpty(e.feedUrl)) { warn(`following "${e.title || '(untitled)'}": no feedUrl, entry skipped`); continue; }
80
+ const label = e.title || e.feedUrl;
81
+ const feed = scheme(e.feedUrl);
82
+ if (!feed) { warn(`following "${label}": feedUrl must be an absolute URL, entry skipped`); continue; }
83
+ if (feed === 'http') warn(`following "${label}": feedUrl is http, not https`);
84
+ let entry = e;
85
+ if (nonEmpty(e.siteUrl)) {
86
+ const site = scheme(e.siteUrl);
87
+ if (!site) { warn(`following "${label}": siteUrl must be an absolute URL, htmlUrl omitted`); entry = { ...e, siteUrl: undefined }; }
88
+ else if (site === 'http') warn(`following "${label}": siteUrl is http, not https`);
89
+ }
90
+ kept.push(entry);
91
+ }
92
+ const title = `${nonEmpty(data?.siteTitle) ? data.siteTitle : 'Site'} follows`;
93
+ const text = renderOpml(kept, { title });
94
+ if (text) out['following.opml'] = text;
95
+ }
96
+
97
+ if (hasAbout) {
98
+ const about = raw.about;
99
+ if (!nonEmpty(about.body) && nonEmpty(about.file) && !fs.existsSync(path.resolve(cwd, about.file))) {
100
+ warn(`about.file "${about.file}" not found`);
101
+ }
102
+ const text = renderAbout({ ...about, body: resolveAboutBody(about, cwd) }, { siteUrl });
103
+ if (text) out['about.md'] = text;
104
+ }
105
+
106
+ if (hasContact) {
107
+ const { text, warning } = renderVcard(raw.contact, { siteUrl });
108
+ if (warning) warn(warning.replace(/^social: /, ''));
109
+ if (text) out['contact.vcf'] = text;
110
+ }
111
+
112
+ const names = Object.keys(out);
113
+ if (!names.length) return null;
114
+ const dir = path.join(rootDir, '.well-known');
115
+ fs.mkdirSync(dir, { recursive: true });
116
+ for (const n of names) fs.writeFileSync(path.join(dir, n), out[n]);
117
+ return names.map(socialHeaderBlock).join('\n');
118
+ }
@@ -7,3 +7,4 @@
7
7
  export { SERVICES } from './catalog.js';
8
8
  export { parseHandle, profileUrl, normalizeAccounts } from './accounts.js';
9
9
  export { renderSocialLinks } from './render.js';
10
+ export { renderOpml, renderAbout, renderVcard } from './socialspec.js';
@@ -0,0 +1,130 @@
1
+ /**
2
+ * @file socialspec.js
3
+ * @description Pure renderers for the three SocialSpec profile files:
4
+ * `following.opml` (FollowSpec), `about.md` (AboutSpec) and `contact.vcf`
5
+ * (ContactSpec). No fs and no config reads; `about.file` is read through an
6
+ * injected `readFile`.
7
+ */
8
+
9
+ const nonEmpty = (v) => typeof v === 'string' && v.trim() !== '';
10
+
11
+ const escapeXml = (s) =>
12
+ String(s)
13
+ .replace(/&/g, '&amp;')
14
+ .replace(/</g, '&lt;')
15
+ .replace(/>/g, '&gt;')
16
+ .replace(/"/g, '&quot;');
17
+
18
+ /**
19
+ * OPML 2.0 subscription list. Public entries only, in the order given.
20
+ * @param {Array<{ title?: string, feedUrl?: string, siteUrl?: string, public?: boolean }>} following
21
+ * @param {{ title?: string }} [options]
22
+ * @returns {string|null} null when there is no public entry with a feedUrl
23
+ */
24
+ export function renderOpml(following, { title } = {}) {
25
+ if (!Array.isArray(following)) return null;
26
+ const outlines = following
27
+ .filter((e) => e && e.public !== false && nonEmpty(e.feedUrl))
28
+ .map((e) => {
29
+ const text = escapeXml(nonEmpty(e.title) ? e.title : e.feedUrl);
30
+ const html = nonEmpty(e.siteUrl) ? ` htmlUrl="${escapeXml(e.siteUrl)}"` : '';
31
+ return ` <outline type="rss" text="${text}" title="${text}" xmlUrl="${escapeXml(e.feedUrl)}"${html}/>`;
32
+ });
33
+ if (!outlines.length) return null;
34
+ const head = escapeXml(nonEmpty(title) ? title : 'Following');
35
+ return [
36
+ '<?xml version="1.0" encoding="UTF-8"?>',
37
+ '<opml version="2.0">',
38
+ ' <head>',
39
+ ` <title>${head}</title>`,
40
+ ' </head>',
41
+ ' <body>',
42
+ ...outlines,
43
+ ' </body>',
44
+ '</opml>',
45
+ '',
46
+ ].join('\n');
47
+ }
48
+
49
+ /**
50
+ * about.md: optional `summary` front matter, then the Markdown body with
51
+ * root-relative link and image targets made absolute.
52
+ * @param {{ summary?: string, body?: string, file?: string }} about `body` wins over `file`
53
+ * @param {{ siteUrl?: string, readFile?: (path: string) => string }} [options]
54
+ * @returns {string|null} null when there is no summary and no body
55
+ */
56
+ export function renderAbout(about, { siteUrl, readFile } = {}) {
57
+ if (!about || typeof about !== 'object') return null;
58
+ let body = '';
59
+ if (nonEmpty(about.body)) {
60
+ body = about.body;
61
+ } else if (nonEmpty(about.file) && typeof readFile === 'function') {
62
+ try {
63
+ body = String(readFile(about.file));
64
+ } catch {
65
+ body = '';
66
+ }
67
+ }
68
+ body = body.replace(/\r\n?/g, '\n').trim();
69
+ if (siteUrl && body) {
70
+ const base = String(siteUrl).replace(/\/+$/, '');
71
+ // `](/path` but not protocol-relative `](//host`
72
+ body = body.replace(/\]\(\/(?!\/)/g, `](${base}/`);
73
+ }
74
+ const summary = nonEmpty(about.summary) ? about.summary.trim() : '';
75
+ if (!summary && !body) return null;
76
+ // A JSON string is a valid YAML double-quoted scalar: safe for `:`, quotes, `#`, newlines.
77
+ const front = summary ? `---\nsummary: ${JSON.stringify(summary)}\n---\n\n` : '';
78
+ return `${front}${body}\n`;
79
+ }
80
+
81
+ const escapeVcardText = (s) =>
82
+ String(s)
83
+ .replace(/\\/g, '\\\\')
84
+ .replace(/\r\n|\r|\n/g, '\\n')
85
+ .replace(/,/g, '\\,')
86
+ .replace(/;/g, '\\;');
87
+
88
+ /** Fold one content line at 75 octets (RFC 6350), never splitting a character. */
89
+ function fold(line) {
90
+ if (Buffer.byteLength(line) <= 75) return line;
91
+ const parts = [];
92
+ let cur = '';
93
+ let curBytes = 0;
94
+ let limit = 75;
95
+ for (const ch of line) {
96
+ const n = Buffer.byteLength(ch);
97
+ if (curBytes + n > limit) {
98
+ parts.push(cur);
99
+ cur = '';
100
+ curBytes = 0;
101
+ limit = 74; // continuation lines carry a leading space
102
+ }
103
+ cur += ch;
104
+ curBytes += n;
105
+ }
106
+ parts.push(cur);
107
+ return parts.join('\r\n ');
108
+ }
109
+
110
+ /**
111
+ * vCard 4.0 for contact.vcf.
112
+ * @param {{ name?: string, email?: string, url?: string, org?: string, title?: string }} contact
113
+ * @param {{ siteUrl?: string }} [options] `URL` defaults to siteUrl
114
+ * @returns {{ text: string|null, warning?: string }}
115
+ */
116
+ export function renderVcard(contact, { siteUrl } = {}) {
117
+ const c = contact && typeof contact === 'object' ? contact : {};
118
+ if (!nonEmpty(c.name)) {
119
+ return { text: null, warning: 'social: contact has no name, so contact.vcf was not written (FN is required)' };
120
+ }
121
+ const lines = ['BEGIN:VCARD', 'VERSION:4.0', `FN:${escapeVcardText(c.name.trim())}`];
122
+ if (nonEmpty(c.org)) lines.push(`ORG:${escapeVcardText(c.org.trim())}`);
123
+ if (nonEmpty(c.title)) lines.push(`TITLE:${escapeVcardText(c.title.trim())}`);
124
+ if (nonEmpty(c.email)) lines.push(`EMAIL;PREF=1:${escapeVcardText(c.email.trim())}`);
125
+ const url = nonEmpty(c.url) ? c.url : siteUrl;
126
+ // URI value type: not text-escaped (RFC 6350); only strip whitespace so it cannot break a line.
127
+ if (nonEmpty(url)) lines.push(`URL:${String(url).replace(/\s+/g, '')}`);
128
+ lines.push('END:VCARD');
129
+ return { text: lines.map(fold).join('\r\n') + '\r\n' };
130
+ }