@cube-drone/marquee-markup 0.1.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/LICENSE +373 -0
- package/README.md +74 -0
- package/bin/marquee.ts +116 -0
- package/dist/bin/marquee.d.ts +2 -0
- package/dist/bin/marquee.js +108 -0
- package/dist/src/build-site.d.ts +39 -0
- package/dist/src/build-site.js +174 -0
- package/dist/src/index.d.ts +104 -0
- package/dist/src/index.js +177 -0
- package/package.json +52 -0
- package/src/build-site.ts +249 -0
- package/src/index.ts +298 -0
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
import { type EmojiResolution, type Profile } from "@cube-drone/marquee-html-renderer";
|
|
2
|
+
import { type TurbolinkPlugin } from "@cube-drone/marquee-turbolink";
|
|
3
|
+
export interface SiteOptions {
|
|
4
|
+
/** Force the site's theme; default follows the reader's OS. */
|
|
5
|
+
colorScheme?: "light" | "dark";
|
|
6
|
+
/** Wrap pages in a 650px centered readability envelope (default false;
|
|
7
|
+
* opt-in so it can't interfere with a host stack's layout). Documents
|
|
8
|
+
* that ARE a `:::page` are left alone. */
|
|
9
|
+
envelope?: boolean;
|
|
10
|
+
/** Best-effort color-readability rescue: clamp author colors' lightness
|
|
11
|
+
* toward the canvas's opposite (see MarqueeOptions.readable). Defaults
|
|
12
|
+
* ON - the site's shell declares the color-scheme, so the clamp
|
|
13
|
+
* direction is trustworthy; pass false to opt out. */
|
|
14
|
+
readable?: boolean;
|
|
15
|
+
/** Turbolink expanders; defaults to the fetchless default set. */
|
|
16
|
+
plugins?: TurbolinkPlugin[];
|
|
17
|
+
/** Your emoji: slug -> replacement text or `{ image, alt? }`, layered
|
|
18
|
+
* over the default table (profile.emoji wins over everything). */
|
|
19
|
+
emoji?: Record<string, EmojiResolution>;
|
|
20
|
+
/** The implicit emoji table (default true): gemoji's standard shortcodes.
|
|
21
|
+
* Set false and unlisted slugs stay literal. */
|
|
22
|
+
emojiDefaults?: boolean;
|
|
23
|
+
/** Overrides layered on the assembled per-site profile. */
|
|
24
|
+
profile?: Partial<Profile>;
|
|
25
|
+
}
|
|
26
|
+
export interface SiteReport {
|
|
27
|
+
pages: string[];
|
|
28
|
+
mediaFiles: number;
|
|
29
|
+
fontFaces: string[];
|
|
30
|
+
outDir: string;
|
|
31
|
+
}
|
|
32
|
+
/** Synchronous, fetchless site build - turbolinks with nothing gathered
|
|
33
|
+
* degrade to plain links. */
|
|
34
|
+
export declare function buildSite(siteDirArg: string, outDirArg: string, opts?: SiteOptions): SiteReport;
|
|
35
|
+
/** buildSite(), plus the network: gathers every page's turbolink targets,
|
|
36
|
+
* runs the composed plugins' async resolve() phase once (OpenGraph joins
|
|
37
|
+
* the chain automatically - and this executes plugin fetch code, so trust
|
|
38
|
+
* your chain), then builds with the gathered data. */
|
|
39
|
+
export declare function buildSiteFetch(siteDirArg: string, outDirArg: string, opts?: SiteOptions): Promise<SiteReport>;
|
|
@@ -0,0 +1,174 @@
|
|
|
1
|
+
// buildSite(): render a folder of .mq files into a static website. This is
|
|
2
|
+
// the batteries-included *embedder*, so it implements the embedder half of
|
|
3
|
+
// the spec:
|
|
4
|
+
// - :::include doc=X::: resolves X.mq beside the including page. Included
|
|
5
|
+
// documents may not include (the v0 depth cap), which also makes cycles
|
|
6
|
+
// unrepresentable. Files named _*.mq are includable partials, not pages.
|
|
7
|
+
// - Relative doc-id links ([Menu](menu)) resolve to the built pages
|
|
8
|
+
// (menu.html) - the base-URI duty, done at build time.
|
|
9
|
+
// - Relative media is copied into <out>/media/ and re-pointed.
|
|
10
|
+
// - Turbolinks get the plugin chain (fetchless defaults unless overridden).
|
|
11
|
+
// - <title> comes from :::meta title, dogfooding document metadata.
|
|
12
|
+
// - Fonts ship as files, and only the faces the site's pages actually use.
|
|
13
|
+
// Stylesheets and fonts are real cacheable files - this is a website, not a
|
|
14
|
+
// single-file page (that's what marquee() is for).
|
|
15
|
+
import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
|
|
16
|
+
import { basename, join, resolve } from "node:path";
|
|
17
|
+
import { parse } from "@cube-drone/marquee-parser";
|
|
18
|
+
import { bareWebProfile, escapeText, render, usedFontTokens, } from "@cube-drone/marquee-html-renderer";
|
|
19
|
+
import { marqueeCss } from "@cube-drone/marquee-css";
|
|
20
|
+
import { standardEmoji } from "@cube-drone/marquee-emoji";
|
|
21
|
+
import { externalFontFaces, fontFilePath } from "@cube-drone/marquee-fonts";
|
|
22
|
+
import { composeTurbolinks, defaultPlugins, opengraphPlugin, resolveTargets, turbolinkStyles, turbolinkTargets, } from "@cube-drone/marquee-turbolink";
|
|
23
|
+
import { docIsPage, envelopeCss, metaTitle, readabilityCss } from "./index.js";
|
|
24
|
+
/** Synchronous, fetchless site build - turbolinks with nothing gathered
|
|
25
|
+
* degrade to plain links. */
|
|
26
|
+
export function buildSite(siteDirArg, outDirArg, opts = {}) {
|
|
27
|
+
return buildSiteCore(siteDirArg, outDirArg, opts, opts.plugins ?? defaultPlugins, undefined);
|
|
28
|
+
}
|
|
29
|
+
/** buildSite(), plus the network: gathers every page's turbolink targets,
|
|
30
|
+
* runs the composed plugins' async resolve() phase once (OpenGraph joins
|
|
31
|
+
* the chain automatically - and this executes plugin fetch code, so trust
|
|
32
|
+
* your chain), then builds with the gathered data. */
|
|
33
|
+
export async function buildSiteFetch(siteDirArg, outDirArg, opts = {}) {
|
|
34
|
+
const base = opts.plugins ?? defaultPlugins;
|
|
35
|
+
const plugins = base.some((p) => p.name === opengraphPlugin.name)
|
|
36
|
+
? base
|
|
37
|
+
: [...base, opengraphPlugin];
|
|
38
|
+
const siteDir = resolve(siteDirArg);
|
|
39
|
+
const targets = [];
|
|
40
|
+
for (const file of readdirSync(siteDir).filter((f) => f.endsWith(".mq"))) {
|
|
41
|
+
targets.push(...turbolinkTargets(parse(readFileSync(join(siteDir, file), "utf8"))));
|
|
42
|
+
}
|
|
43
|
+
const resolved = await resolveTargets(targets, plugins);
|
|
44
|
+
return buildSiteCore(siteDirArg, outDirArg, opts, plugins, resolved);
|
|
45
|
+
}
|
|
46
|
+
function buildSiteCore(siteDirArg, outDirArg, opts, plugins, resolved) {
|
|
47
|
+
const siteDir = resolve(siteDirArg);
|
|
48
|
+
const outDir = resolve(outDirArg);
|
|
49
|
+
const emojiTable = {
|
|
50
|
+
...(opts.emojiDefaults === false ? {} : standardEmoji),
|
|
51
|
+
...opts.emoji,
|
|
52
|
+
};
|
|
53
|
+
const mqFiles = readdirSync(siteDir).filter((f) => f.endsWith(".mq"));
|
|
54
|
+
const pageIds = mqFiles.filter((f) => !f.startsWith("_")).map((f) => basename(f, ".mq"));
|
|
55
|
+
// -- media: relative embeds copied in once, re-pointed at media/<name>
|
|
56
|
+
const copiedMedia = new Map();
|
|
57
|
+
function siteMediaUrl(path) {
|
|
58
|
+
let name = copiedMedia.get(path);
|
|
59
|
+
if (name === undefined) {
|
|
60
|
+
name = basename(path);
|
|
61
|
+
for (let n = 2; [...copiedMedia.values()].includes(name); n += 1) {
|
|
62
|
+
const dot = basename(path).lastIndexOf(".");
|
|
63
|
+
name = dot <= 0 ? `${basename(path)}-${n}` : `${basename(path).slice(0, dot)}-${n}${basename(path).slice(dot)}`;
|
|
64
|
+
}
|
|
65
|
+
mkdirSync(join(outDir, "media"), { recursive: true });
|
|
66
|
+
copyFileSync(path, join(outDir, "media", name));
|
|
67
|
+
copiedMedia.set(path, name);
|
|
68
|
+
}
|
|
69
|
+
return `media/${encodeURIComponent(name)}`;
|
|
70
|
+
}
|
|
71
|
+
// -- the embedder profile; `depth` enforces "includes may not include"
|
|
72
|
+
function siteProfile(depth) {
|
|
73
|
+
return {
|
|
74
|
+
...bareWebProfile,
|
|
75
|
+
media(target) {
|
|
76
|
+
if (!/^[A-Za-z][A-Za-z0-9+.-]*:/.test(target)) {
|
|
77
|
+
const path = resolve(siteDir, target.split(/[?#]/, 1)[0]);
|
|
78
|
+
if (existsSync(path)) {
|
|
79
|
+
// Kind-by-extension via the default profile (dummy https host -
|
|
80
|
+
// only the extension matters to it).
|
|
81
|
+
const base = bareWebProfile.media(`https://local/${basename(path)}`);
|
|
82
|
+
if (base !== null) {
|
|
83
|
+
return { kind: base.kind, url: siteMediaUrl(path) };
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
return null;
|
|
87
|
+
}
|
|
88
|
+
return bareWebProfile.media(target);
|
|
89
|
+
},
|
|
90
|
+
turbolink: composeTurbolinks(plugins, resolved),
|
|
91
|
+
emoji: (slug) => emojiTable[slug] ?? null,
|
|
92
|
+
directive(name, attrs, _children) {
|
|
93
|
+
if (name !== "include" || depth > 0) {
|
|
94
|
+
return null; // deep include -> unknown vocabulary -> inert placeholder
|
|
95
|
+
}
|
|
96
|
+
const doc = attrs["doc"];
|
|
97
|
+
if (doc === undefined || !/^[A-Za-z0-9_.-]+$/.test(doc)) {
|
|
98
|
+
return null;
|
|
99
|
+
}
|
|
100
|
+
const path = join(siteDir, `${doc}.mq`);
|
|
101
|
+
if (!existsSync(path)) {
|
|
102
|
+
return null; // missing include: the placeholder says so, words survive
|
|
103
|
+
}
|
|
104
|
+
const included = parse(readFileSync(path, "utf8"));
|
|
105
|
+
if (included.type !== "document") {
|
|
106
|
+
return null;
|
|
107
|
+
}
|
|
108
|
+
const inner = siteProfile(depth + 1);
|
|
109
|
+
return included.children.map((child) => render(child, inner)).join("");
|
|
110
|
+
},
|
|
111
|
+
...opts.profile,
|
|
112
|
+
};
|
|
113
|
+
}
|
|
114
|
+
function shell(title, body) {
|
|
115
|
+
return `<!doctype html>
|
|
116
|
+
<html lang="en">
|
|
117
|
+
<head>
|
|
118
|
+
<meta charset="utf-8">
|
|
119
|
+
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
120
|
+
<title>${escapeText(title)}</title>
|
|
121
|
+
<link rel="stylesheet" href="css/marquee.css">
|
|
122
|
+
<link rel="stylesheet" href="css/fonts.css">
|
|
123
|
+
<link rel="stylesheet" href="css/turbolink.css">
|
|
124
|
+
<style>/* the embedder's page, the embedder's reset: full-bleed backgrounds
|
|
125
|
+
(marquee.css never touches body - it must embed politely in host pages),
|
|
126
|
+
and the reader's OS theme decides light or dark unless the build forced one */
|
|
127
|
+
:root { color-scheme: ${opts.colorScheme ?? "light dark"}; }
|
|
128
|
+
body { margin: 0; }${opts.envelope === true ? `\n${envelopeCss}` : ""}${opts.readable === false ? "" : `\n${readabilityCss(opts.colorScheme)}`}</style>
|
|
129
|
+
</head>
|
|
130
|
+
<body>
|
|
131
|
+
${body}
|
|
132
|
+
</body>
|
|
133
|
+
</html>
|
|
134
|
+
`;
|
|
135
|
+
}
|
|
136
|
+
// -- build
|
|
137
|
+
mkdirSync(join(outDir, "css"), { recursive: true });
|
|
138
|
+
writeFileSync(join(outDir, "css/marquee.css"), marqueeCss);
|
|
139
|
+
writeFileSync(join(outDir, "css/turbolink.css"), turbolinkStyles(plugins));
|
|
140
|
+
const profile = siteProfile(0);
|
|
141
|
+
const usedFonts = new Set();
|
|
142
|
+
for (const id of pageIds) {
|
|
143
|
+
const source = readFileSync(join(siteDir, `${id}.mq`), "utf8");
|
|
144
|
+
const doc = parse(source);
|
|
145
|
+
let body = render(doc, profile);
|
|
146
|
+
// Doc-id links become page links: the base-URI duty, resolved at build.
|
|
147
|
+
for (const target of pageIds) {
|
|
148
|
+
body = body.replaceAll(`href="${target}"`, `href="${target}.html"`);
|
|
149
|
+
}
|
|
150
|
+
for (const token of usedFontTokens(body)) {
|
|
151
|
+
usedFonts.add(token);
|
|
152
|
+
}
|
|
153
|
+
// The envelope defers to a document that IS a page.
|
|
154
|
+
if (opts.envelope === true && !docIsPage(doc)) {
|
|
155
|
+
body = `<div class="mq-envelope">${body}</div>`;
|
|
156
|
+
}
|
|
157
|
+
writeFileSync(join(outDir, `${id}.html`), shell(metaTitle(doc) ?? id, body));
|
|
158
|
+
}
|
|
159
|
+
// Fonts: only the faces this site actually uses. Readers never fetch
|
|
160
|
+
// unused @font-face rules anyway (font loading is lazy), but a deploy
|
|
161
|
+
// artifact shouldn't haul the whole library to serve four faces.
|
|
162
|
+
mkdirSync(join(outDir, "fonts"), { recursive: true });
|
|
163
|
+
const shipped = [];
|
|
164
|
+
for (const token of [...usedFonts].sort()) {
|
|
165
|
+
const path = fontFilePath(token);
|
|
166
|
+
if (path === null) {
|
|
167
|
+
continue; // standard stacks and unfetched faces: fallbacks handle it
|
|
168
|
+
}
|
|
169
|
+
copyFileSync(path, join(outDir, "fonts", `${token}.woff2`));
|
|
170
|
+
shipped.push(token);
|
|
171
|
+
}
|
|
172
|
+
writeFileSync(join(outDir, "css/fonts.css"), `/* fonts.css - generated per site: only the faces these pages use. */\n\n${externalFontFaces(shipped, "../fonts/")}\n`);
|
|
173
|
+
return { pages: pageIds, mediaFiles: copiedMedia.size, fontFaces: shipped, outDir };
|
|
174
|
+
}
|
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
import { type Node } from "@cube-drone/marquee-parser";
|
|
2
|
+
import { type EmojiResolution, type Profile } from "@cube-drone/marquee-html-renderer";
|
|
3
|
+
import { type TurbolinkPlugin } from "@cube-drone/marquee-turbolink";
|
|
4
|
+
export interface MarqueeOptions {
|
|
5
|
+
/** Page title; defaults to the document's `:::meta title`, then "Marquee". */
|
|
6
|
+
title?: string;
|
|
7
|
+
/** Font delivery: "inline" (default) carries the used faces as base64;
|
|
8
|
+
* "external" emits @font-face urls under `fontBase` (copy the files
|
|
9
|
+
* yourself - `fontTokens` in the fragment return + `fontFilePath()` tell
|
|
10
|
+
* you which); "none" lets names degrade to their fallback stacks. */
|
|
11
|
+
fonts?: "inline" | "external" | "none";
|
|
12
|
+
/** Base path for fonts: "external" urls (default "fonts/"). */
|
|
13
|
+
fontBase?: string;
|
|
14
|
+
/** Your emoji: slug -> replacement text, or `{ image, alt? }` for a
|
|
15
|
+
* custom-emoji image (rendered as an inline `<img class="mq-emoji">`,
|
|
16
|
+
* character-sized). Entries layer over the default table and win on
|
|
17
|
+
* collision. (For dynamic resolution, use `profile.emoji` instead - a
|
|
18
|
+
* profile override wins over everything.) */
|
|
19
|
+
emoji?: Record<string, EmojiResolution>;
|
|
20
|
+
/** The implicit emoji table (default true): gemoji's standard shortcodes,
|
|
21
|
+
* from @cube-drone/marquee-emoji. Set false and unlisted slugs stay
|
|
22
|
+
* literal `:slug:`. */
|
|
23
|
+
emojiDefaults?: boolean;
|
|
24
|
+
/** Force the page's theme. Default: follow the reader's OS
|
|
25
|
+
* (`color-scheme: light dark`). Applies to the page shell, so it only
|
|
26
|
+
* affects `marquee()`/`marqueeFetch()` - fragments follow their host. */
|
|
27
|
+
colorScheme?: "light" | "dark";
|
|
28
|
+
/** Wrap the rendered document in a 650px centered envelope, purely for
|
|
29
|
+
* readability (default false - it could interfere with a host stack's
|
|
30
|
+
* own layout, so it's opt-in). A document that IS a `:::page` (its
|
|
31
|
+
* top-level content is page directives) is left alone even when this is
|
|
32
|
+
* on: the author took layout control, the envelope defers. */
|
|
33
|
+
envelope?: boolean;
|
|
34
|
+
/** Best-effort color-readability rescue: author colors keep their hue
|
|
35
|
+
* but their lightness is clamped toward the canvas's opposite -
|
|
36
|
+
* lightened on dark canvases, darkened on light. Containers that paint
|
|
37
|
+
* their own background (schemes, `background=` knobs) own their contrast
|
|
38
|
+
* and are left alone. Defaults ON for whole pages (marquee/marqueeFetch/
|
|
39
|
+
* buildSite - our shell declared the color-scheme, so the clamp direction
|
|
40
|
+
* is trustworthy) and OFF for bare fragments (a host theming by class
|
|
41
|
+
* rather than OS preference would get the clamp backwards - opt in when
|
|
42
|
+
* your canvas follows prefers-color-scheme). */
|
|
43
|
+
readable?: boolean;
|
|
44
|
+
/** Turbolink expanders; defaults to the fetchless default set. */
|
|
45
|
+
plugins?: TurbolinkPlugin[];
|
|
46
|
+
/** Overrides layered on the assembled profile (schemes, media policy...). */
|
|
47
|
+
profile?: Partial<Profile>;
|
|
48
|
+
}
|
|
49
|
+
/** The document's own `:::meta title`, if it declares one. */
|
|
50
|
+
export declare function metaTitle(doc: Node): string | undefined;
|
|
51
|
+
interface Fragment {
|
|
52
|
+
body: string;
|
|
53
|
+
css: string;
|
|
54
|
+
title: string;
|
|
55
|
+
fontTokens: string[];
|
|
56
|
+
}
|
|
57
|
+
/** Parse and render to embeddable pieces: what goes in the body, the CSS
|
|
58
|
+
* that belongs in the head (stylesheet + composed plugin skins + fonts per
|
|
59
|
+
* options), the title, and which font faces the page wears. */
|
|
60
|
+
export declare function marqueeFragment(source: string, opts?: MarqueeOptions): Fragment;
|
|
61
|
+
/** The readability envelope: omnibus convenience, not renderer contract
|
|
62
|
+
* (mq-* classes in marquee.css are the renderers'; this one is ours). */
|
|
63
|
+
export declare const envelopeCss = ".mq-envelope { max-width: 650px; margin-inline: auto; padding-inline: 1rem; }";
|
|
64
|
+
/** The `readable` option's stylesheet: CSS relative color syntax clamps the
|
|
65
|
+
* *lightness* of author colors (hue and chroma survive) toward whatever the
|
|
66
|
+
* canvas isn't - floor 0.72 on dark canvases, ceiling 0.55 on light. The
|
|
67
|
+
* clamp bounds ride inherited custom properties, so containers that paint
|
|
68
|
+
* their own background (schemes, `background=` knobs) reset them to no-ops
|
|
69
|
+
* for their whole subtree: they own their contrast. A painted background
|
|
70
|
+
* with NO chosen text color additionally gets black-or-white text computed
|
|
71
|
+
* from the background's own lightness. Browsers without relative-color
|
|
72
|
+
* support ignore all of it and fall back to the raw colors. */
|
|
73
|
+
export declare function readabilityCss(colorScheme?: "light" | "dark"): string;
|
|
74
|
+
/** Does the document take layout into its own hands? Only when it IS a
|
|
75
|
+
* page: every top-level block (ignoring `:::meta` and comments) is a
|
|
76
|
+
* `:::page` directive. A document that merely *contains* a page demo among
|
|
77
|
+
* prose is still an unstructured document, and the envelope applies. */
|
|
78
|
+
export declare function docIsPage(doc: Node): boolean;
|
|
79
|
+
/** Just the stuff that goes inside <body>: the rendered document fragment. */
|
|
80
|
+
export declare function marqueeBody(source: string, opts?: MarqueeOptions): string;
|
|
81
|
+
/** Just the stuff that goes inside <head>: title + one <style> block. */
|
|
82
|
+
export declare function marqueeHead(source: string, opts?: MarqueeOptions): string;
|
|
83
|
+
/** The one smooth motion: Marquee source in, a complete self-contained
|
|
84
|
+
* HTML page out. Synchronous and fetchless - turbolinks with nothing
|
|
85
|
+
* gathered degrade to plain links. */
|
|
86
|
+
export declare function marquee(source: string, opts?: MarqueeOptions): string;
|
|
87
|
+
/** marquee(), plus the network: runs the composed plugins' async resolve()
|
|
88
|
+
* phase ahead of the render - OpenGraph summaries for bare web links
|
|
89
|
+
* (opengraphPlugin joins the chain automatically), plus whatever gathering
|
|
90
|
+
* your own plugins declare. That means this function EXECUTES plugin fetch
|
|
91
|
+
* code: compose the chain from plugins you trust, because a malicious one
|
|
92
|
+
* runs here too. Rendering itself stays sync and fetchless; a failed fetch
|
|
93
|
+
* degrades to the plain link. */
|
|
94
|
+
export declare function marqueeFetch(source: string, opts?: MarqueeOptions): Promise<string>;
|
|
95
|
+
export { buildSite, buildSiteFetch, type SiteReport } from "./build-site.ts";
|
|
96
|
+
export { parse, UnsupportedVersionError } from "@cube-drone/marquee-parser";
|
|
97
|
+
export type { Attrs, Node, Reason } from "@cube-drone/marquee-parser";
|
|
98
|
+
export { FONTS, bareWebProfile, escapeAttr, escapeText, render, renderMarquee, usedFontTokens, } from "@cube-drone/marquee-html-renderer";
|
|
99
|
+
export type { EmojiResolution, MediaResolution, Profile, TurbolinkLevel } from "@cube-drone/marquee-html-renderer";
|
|
100
|
+
export { marqueeCss } from "@cube-drone/marquee-css";
|
|
101
|
+
export { standardEmoji } from "@cube-drone/marquee-emoji";
|
|
102
|
+
export { FONT_MANIFEST, externalFontFaces, fontFilePath, inlineFontFaces, } from "@cube-drone/marquee-fonts";
|
|
103
|
+
export { composeTurbolinks, defaultPlugins, opengraphPlugin, renderCard, resolveTargets, turbolinkStyles, turbolinkTargets, } from "@cube-drone/marquee-turbolink";
|
|
104
|
+
export type { TurbolinkContext, TurbolinkPlugin, TurbolinkSummary } from "@cube-drone/marquee-turbolink";
|
|
@@ -0,0 +1,177 @@
|
|
|
1
|
+
// @cube-drone/marquee-markup: Marquee, batteries included.
|
|
2
|
+
//
|
|
3
|
+
// import { marquee } from "@cube-drone/marquee-markup";
|
|
4
|
+
// writeFileSync("hello.html", marquee("# hello *world*"));
|
|
5
|
+
//
|
|
6
|
+
// One motion: parse, render, style, inline the fonts the page actually
|
|
7
|
+
// wears, wrap in a page shell. `marqueeFragment()` gives embedders the
|
|
8
|
+
// pieces instead; `buildSite()` renders a folder of .mq files into a
|
|
9
|
+
// website (shared nav/footer includes, per-site font subsetting).
|
|
10
|
+
//
|
|
11
|
+
// Everything underneath is re-exported, so outgrowing the convenience never
|
|
12
|
+
// means switching packages: the same parse/render/Profile/plugin machinery
|
|
13
|
+
// from @cube-drone/marquee-parser, -html-renderer, -css, -fonts, and
|
|
14
|
+
// @cube-drone/marquee-turbolink is all reachable from here.
|
|
15
|
+
import { parse } from "@cube-drone/marquee-parser";
|
|
16
|
+
import { bareWebProfile, escapeText, render, usedFontTokens, } from "@cube-drone/marquee-html-renderer";
|
|
17
|
+
import { marqueeCss } from "@cube-drone/marquee-css";
|
|
18
|
+
import { standardEmoji } from "@cube-drone/marquee-emoji";
|
|
19
|
+
import { externalFontFaces, inlineFontFaces } from "@cube-drone/marquee-fonts";
|
|
20
|
+
import { composeTurbolinks, defaultPlugins, opengraphPlugin, resolveTargets, turbolinkStyles, turbolinkTargets, } from "@cube-drone/marquee-turbolink";
|
|
21
|
+
function assembleProfile(opts, plugins, resolved) {
|
|
22
|
+
const emoji = {
|
|
23
|
+
...(opts.emojiDefaults === false ? {} : standardEmoji),
|
|
24
|
+
...opts.emoji,
|
|
25
|
+
};
|
|
26
|
+
return {
|
|
27
|
+
...bareWebProfile,
|
|
28
|
+
turbolink: composeTurbolinks(plugins, resolved),
|
|
29
|
+
emoji: (slug) => emoji[slug] ?? null,
|
|
30
|
+
...opts.profile,
|
|
31
|
+
};
|
|
32
|
+
}
|
|
33
|
+
/** The fetch-mode plugin chain: yours (or the defaults) with the OpenGraph
|
|
34
|
+
* expander appended, unless you already composed one in. */
|
|
35
|
+
function fetchChain(opts) {
|
|
36
|
+
const base = opts.plugins ?? defaultPlugins;
|
|
37
|
+
return base.some((p) => p.name === opengraphPlugin.name) ? base : [...base, opengraphPlugin];
|
|
38
|
+
}
|
|
39
|
+
/** The document's own `:::meta title`, if it declares one. */
|
|
40
|
+
export function metaTitle(doc) {
|
|
41
|
+
if (doc.type !== "document") {
|
|
42
|
+
return undefined;
|
|
43
|
+
}
|
|
44
|
+
for (const child of doc.children) {
|
|
45
|
+
if (child.type === "directive" && child.name === "meta" && child.attrs["title"] !== undefined) {
|
|
46
|
+
return child.attrs["title"];
|
|
47
|
+
}
|
|
48
|
+
}
|
|
49
|
+
return undefined;
|
|
50
|
+
}
|
|
51
|
+
/** Parse and render to embeddable pieces: what goes in the body, the CSS
|
|
52
|
+
* that belongs in the head (stylesheet + composed plugin skins + fonts per
|
|
53
|
+
* options), the title, and which font faces the page wears. */
|
|
54
|
+
export function marqueeFragment(source, opts = {}) {
|
|
55
|
+
return fragmentCore(parse(source), opts, opts.plugins ?? defaultPlugins);
|
|
56
|
+
}
|
|
57
|
+
/** The readability envelope: omnibus convenience, not renderer contract
|
|
58
|
+
* (mq-* classes in marquee.css are the renderers'; this one is ours). */
|
|
59
|
+
export const envelopeCss = `.mq-envelope { max-width: 650px; margin-inline: auto; padding-inline: 1rem; }`;
|
|
60
|
+
/** The `readable` option's stylesheet: CSS relative color syntax clamps the
|
|
61
|
+
* *lightness* of author colors (hue and chroma survive) toward whatever the
|
|
62
|
+
* canvas isn't - floor 0.72 on dark canvases, ceiling 0.55 on light. The
|
|
63
|
+
* clamp bounds ride inherited custom properties, so containers that paint
|
|
64
|
+
* their own background (schemes, `background=` knobs) reset them to no-ops
|
|
65
|
+
* for their whole subtree: they own their contrast. A painted background
|
|
66
|
+
* with NO chosen text color additionally gets black-or-white text computed
|
|
67
|
+
* from the background's own lightness. Browsers without relative-color
|
|
68
|
+
* support ignore all of it and fall back to the raw colors. */
|
|
69
|
+
export function readabilityCss(colorScheme) {
|
|
70
|
+
const dark = `.mq-doc { --mq-rl-min: 0.72; --mq-rl-max: 1; }`;
|
|
71
|
+
const light = `.mq-doc { --mq-rl-min: 0; --mq-rl-max: 0.55; }`;
|
|
72
|
+
const mode = colorScheme === "dark"
|
|
73
|
+
? dark
|
|
74
|
+
: colorScheme === "light"
|
|
75
|
+
? light
|
|
76
|
+
: `@media (prefers-color-scheme: dark) { ${dark} }\n@media (prefers-color-scheme: light) { ${light} }`;
|
|
77
|
+
return `${mode}
|
|
78
|
+
.mq-doc [style*="--mq-color"] { color: oklch(from var(--mq-color) clamp(var(--mq-rl-min, 0), l, var(--mq-rl-max, 1)) c h); }
|
|
79
|
+
.mq-doc [style*="--mq-bg"]:not([style*="--mq-color"]) { color: oklch(from var(--mq-bg) calc(1 - clamp(0, (l - 0.5) * 999, 1)) 0 h); }
|
|
80
|
+
.mq-doc [class*="mq-scheme-"], .mq-doc [style*="--mq-bg"] { --mq-rl-min: 0; --mq-rl-max: 1; }`;
|
|
81
|
+
}
|
|
82
|
+
/** Does the document take layout into its own hands? Only when it IS a
|
|
83
|
+
* page: every top-level block (ignoring `:::meta` and comments) is a
|
|
84
|
+
* `:::page` directive. A document that merely *contains* a page demo among
|
|
85
|
+
* prose is still an unstructured document, and the envelope applies. */
|
|
86
|
+
export function docIsPage(doc) {
|
|
87
|
+
if (doc.type !== "document") {
|
|
88
|
+
return false;
|
|
89
|
+
}
|
|
90
|
+
const blocks = doc.children.filter((c) => c.type !== "comment" && !(c.type === "directive" && c.name === "meta"));
|
|
91
|
+
return blocks.length > 0 && blocks.every((c) => c.type === "directive" && c.name === "page");
|
|
92
|
+
}
|
|
93
|
+
function fragmentCore(doc, opts, plugins, resolved) {
|
|
94
|
+
const profile = assembleProfile(opts, plugins, resolved);
|
|
95
|
+
let body = render(doc, profile);
|
|
96
|
+
const enveloped = opts.envelope === true && !docIsPage(doc);
|
|
97
|
+
if (enveloped) {
|
|
98
|
+
body = `<div class="mq-envelope">${body}</div>`;
|
|
99
|
+
}
|
|
100
|
+
const fontTokens = usedFontTokens(body);
|
|
101
|
+
let css = `${marqueeCss}\n${turbolinkStyles(plugins)}`;
|
|
102
|
+
if (enveloped) {
|
|
103
|
+
css += `\n${envelopeCss}`;
|
|
104
|
+
}
|
|
105
|
+
if (opts.readable === true) {
|
|
106
|
+
css += `\n${readabilityCss(opts.colorScheme)}`;
|
|
107
|
+
}
|
|
108
|
+
const fonts = opts.fonts ?? "inline";
|
|
109
|
+
const faces = fonts === "inline"
|
|
110
|
+
? inlineFontFaces(fontTokens)
|
|
111
|
+
: fonts === "external"
|
|
112
|
+
? externalFontFaces(fontTokens, opts.fontBase ?? "fonts/")
|
|
113
|
+
: "";
|
|
114
|
+
if (faces !== "") {
|
|
115
|
+
css += `\n${faces}`;
|
|
116
|
+
}
|
|
117
|
+
return { body, css, title: opts.title ?? metaTitle(doc) ?? "Marquee", fontTokens };
|
|
118
|
+
}
|
|
119
|
+
/** Just the stuff that goes inside <body>: the rendered document fragment. */
|
|
120
|
+
export function marqueeBody(source, opts = {}) {
|
|
121
|
+
return marqueeFragment(source, opts).body;
|
|
122
|
+
}
|
|
123
|
+
/** Just the stuff that goes inside <head>: title + one <style> block. */
|
|
124
|
+
export function marqueeHead(source, opts = {}) {
|
|
125
|
+
const { css, title } = marqueeFragment(source, opts);
|
|
126
|
+
return `<title>${escapeText(title)}</title>\n<style>\n${css}\n</style>`;
|
|
127
|
+
}
|
|
128
|
+
function pageShell({ body, css, title }, colorScheme) {
|
|
129
|
+
return `<!doctype html>
|
|
130
|
+
<html lang="en">
|
|
131
|
+
<head>
|
|
132
|
+
<meta charset="utf-8">
|
|
133
|
+
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
134
|
+
<title>${escapeText(title)}</title>
|
|
135
|
+
<style>
|
|
136
|
+
/* The page is ours, so it follows the reader's OS theme unless the caller
|
|
137
|
+
forced one. marquee.css never declares color-scheme itself - embedded
|
|
138
|
+
fragments defer to their host - and its own neutrals are translucent, so
|
|
139
|
+
they ride either canvas. */
|
|
140
|
+
:root { color-scheme: ${colorScheme ?? "light dark"}; }
|
|
141
|
+
body { margin: 0; }
|
|
142
|
+
${css}
|
|
143
|
+
</style>
|
|
144
|
+
</head>
|
|
145
|
+
<body>
|
|
146
|
+
${body}
|
|
147
|
+
</body>
|
|
148
|
+
</html>
|
|
149
|
+
`;
|
|
150
|
+
}
|
|
151
|
+
/** The one smooth motion: Marquee source in, a complete self-contained
|
|
152
|
+
* HTML page out. Synchronous and fetchless - turbolinks with nothing
|
|
153
|
+
* gathered degrade to plain links. */
|
|
154
|
+
export function marquee(source, opts = {}) {
|
|
155
|
+
return pageShell(marqueeFragment(source, { readable: true, ...opts }), opts.colorScheme);
|
|
156
|
+
}
|
|
157
|
+
/** marquee(), plus the network: runs the composed plugins' async resolve()
|
|
158
|
+
* phase ahead of the render - OpenGraph summaries for bare web links
|
|
159
|
+
* (opengraphPlugin joins the chain automatically), plus whatever gathering
|
|
160
|
+
* your own plugins declare. That means this function EXECUTES plugin fetch
|
|
161
|
+
* code: compose the chain from plugins you trust, because a malicious one
|
|
162
|
+
* runs here too. Rendering itself stays sync and fetchless; a failed fetch
|
|
163
|
+
* degrades to the plain link. */
|
|
164
|
+
export async function marqueeFetch(source, opts = {}) {
|
|
165
|
+
const plugins = fetchChain(opts);
|
|
166
|
+
const doc = parse(source);
|
|
167
|
+
const resolved = await resolveTargets(turbolinkTargets(doc), plugins);
|
|
168
|
+
return pageShell(fragmentCore(doc, { readable: true, ...opts }, plugins, resolved), opts.colorScheme);
|
|
169
|
+
}
|
|
170
|
+
export { buildSite, buildSiteFetch } from "./build-site.js";
|
|
171
|
+
// The full toolbox, re-exported: growth never requires switching packages.
|
|
172
|
+
export { parse, UnsupportedVersionError } from "@cube-drone/marquee-parser";
|
|
173
|
+
export { FONTS, bareWebProfile, escapeAttr, escapeText, render, renderMarquee, usedFontTokens, } from "@cube-drone/marquee-html-renderer";
|
|
174
|
+
export { marqueeCss } from "@cube-drone/marquee-css";
|
|
175
|
+
export { standardEmoji } from "@cube-drone/marquee-emoji";
|
|
176
|
+
export { FONT_MANIFEST, externalFontFaces, fontFilePath, inlineFontFaces, } from "@cube-drone/marquee-fonts";
|
|
177
|
+
export { composeTurbolinks, defaultPlugins, opengraphPlugin, renderCard, resolveTargets, turbolinkStyles, turbolinkTargets, } from "@cube-drone/marquee-turbolink";
|
package/package.json
ADDED
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@cube-drone/marquee-markup",
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "Marquee, batteries included: parse + render to HTML in one motion, fonts and styles along for the ride, plus the `marquee` CLI",
|
|
5
|
+
"license": "MPL-2.0",
|
|
6
|
+
"repository": {
|
|
7
|
+
"type": "git",
|
|
8
|
+
"url": "git+https://github.com/cube-drone/marqueemarkup.git",
|
|
9
|
+
"directory": "ts/marquee-markup"
|
|
10
|
+
},
|
|
11
|
+
"type": "module",
|
|
12
|
+
"engines": {
|
|
13
|
+
"node": ">=22.6.0"
|
|
14
|
+
},
|
|
15
|
+
"files": [
|
|
16
|
+
"dist",
|
|
17
|
+
"src",
|
|
18
|
+
"bin",
|
|
19
|
+
"README.md"
|
|
20
|
+
],
|
|
21
|
+
"publishConfig": {
|
|
22
|
+
"access": "public"
|
|
23
|
+
},
|
|
24
|
+
"exports": {
|
|
25
|
+
".": {
|
|
26
|
+
"marquee-src": "./src/index.ts",
|
|
27
|
+
"types": "./dist/src/index.d.ts",
|
|
28
|
+
"default": "./dist/src/index.js"
|
|
29
|
+
}
|
|
30
|
+
},
|
|
31
|
+
"bin": {
|
|
32
|
+
"marquee": "./dist/bin/marquee.js"
|
|
33
|
+
},
|
|
34
|
+
"scripts": {
|
|
35
|
+
"test": "node --conditions=marquee-src --test test/*.test.ts",
|
|
36
|
+
"check": "tsc --noEmit",
|
|
37
|
+
"build": "tsc -p tsconfig.build.json",
|
|
38
|
+
"prepack": "npm run build"
|
|
39
|
+
},
|
|
40
|
+
"dependencies": {
|
|
41
|
+
"@cube-drone/marquee-css": "^0.1.0",
|
|
42
|
+
"@cube-drone/marquee-emoji": "^0.1.0",
|
|
43
|
+
"@cube-drone/marquee-fonts": "^0.1.0",
|
|
44
|
+
"@cube-drone/marquee-html-renderer": "^0.1.0",
|
|
45
|
+
"@cube-drone/marquee-parser": "^0.1.0",
|
|
46
|
+
"@cube-drone/marquee-turbolink": "^0.1.0"
|
|
47
|
+
},
|
|
48
|
+
"devDependencies": {
|
|
49
|
+
"@types/node": "^24.0.0",
|
|
50
|
+
"typescript": "^5.9.0"
|
|
51
|
+
}
|
|
52
|
+
}
|