@cube-drone/marquee-markup 0.2.0 → 0.3.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 +152 -55
- package/package.json +7 -7
package/README.md
CHANGED
|
@@ -1,6 +1,12 @@
|
|
|
1
|
+
<img src="https://raw.githubusercontent.com/cube-drone/marqueemarkup/main/marquee-logo.png" alt="Marquee Markup" width="96" align="right">
|
|
2
|
+
|
|
1
3
|
# @cube-drone/marquee-markup
|
|
2
4
|
|
|
3
|
-
Marquee
|
|
5
|
+
The [Marquee](https://github.com/cube-drone/marqueemarkup) Markup Language.
|
|
6
|
+
|
|
7
|
+
Marquee source in, complete styled HTML out, with the stylesheet, fonts, and emoji table along for the ride.
|
|
8
|
+
|
|
9
|
+
This is the package you want unless you know why you want a smaller one.
|
|
4
10
|
|
|
5
11
|
```
|
|
6
12
|
npm install @cube-drone/marquee-markup
|
|
@@ -13,62 +19,153 @@ import { readFileSync, writeFileSync } from "node:fs";
|
|
|
13
19
|
writeFileSync("hello.html", marquee(readFileSync("hello.mq", "utf8")));
|
|
14
20
|
```
|
|
15
21
|
|
|
16
|
-
|
|
17
|
-
|
|
22
|
+
To learn the *language*, read [WRITING.md](https://github.com/cube-drone/marqueemarkup/blob/main/WRITING.md)
|
|
23
|
+
or see it live at [marquee.cube-drone.com](https://marquee.cube-drone.com). This document is
|
|
24
|
+
the contract for the *tools*.
|
|
18
25
|
|
|
19
|
-
|
|
26
|
+
## The CLI
|
|
20
27
|
|
|
21
28
|
```
|
|
22
|
-
npx marquee
|
|
23
|
-
npx marquee
|
|
24
|
-
npx marquee
|
|
29
|
+
npx marquee <file.mq> render one page to stdout
|
|
30
|
+
npx marquee <file.mq> -o out.html ...or to a file
|
|
31
|
+
npx marquee <site-dir> <out-dir> build a whole site
|
|
25
32
|
```
|
|
26
33
|
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
the
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
34
|
+
| flag | effect |
|
|
35
|
+
|---|---|
|
|
36
|
+
| `--nofetch` | skip the network fetch-ahead pass. Default is ON: bare web links become real OpenGraph preview cards, fetched once at build time. With `--nofetch`, unrecognized links stay plain links and the build touches no network |
|
|
37
|
+
| `--envelope` | wrap plain documents in a 650px centered column for readability. Documents whose top-level content is `:::page` directives are left alone (the author took layout control) |
|
|
38
|
+
| `--darkmode` | force `color-scheme: dark`. Default: pages follow the reader's OS theme |
|
|
39
|
+
| `--noreadable` | disable the color-readability rescue (see `readable` below). Default is ON for pages |
|
|
40
|
+
|
|
41
|
+
Every flag is a library option first; the CLI is sugar over the functions below.
|
|
42
|
+
|
|
43
|
+
## Functions
|
|
44
|
+
|
|
45
|
+
### What Happens if the Marquee is unparseable?
|
|
46
|
+
|
|
47
|
+
I have good news for you: if you give it _text_ you are very likely to be in the clear:
|
|
48
|
+
this language is designed to _always_ be parseable. **any input renders: nothing throws**.
|
|
49
|
+
|
|
50
|
+
The only exception in the whole API is an unknown dialect version declaration
|
|
51
|
+
(`#!marquee 99`), which throws `UnsupportedVersionError` — so that old versions of Marquee
|
|
52
|
+
don't try to parse documents it doesn't understand yet.
|
|
53
|
+
|
|
54
|
+
### `marquee(source, options?) => string`
|
|
55
|
+
|
|
56
|
+
* parse
|
|
57
|
+
* render
|
|
58
|
+
* inline the stylesheet
|
|
59
|
+
* inline exactly the font faces the page actually uses (as base64, by default)
|
|
60
|
+
* wrap in a complete `<!doctype html>` page shell.
|
|
61
|
+
|
|
62
|
+
The returned string is self-contained (thanks to all of the inlining): you should be able to deliver it as a complete .html file.
|
|
63
|
+
|
|
64
|
+
Turbolinks (bare URLs alone in a paragraph) render through the _fetchless_ plugin chain:
|
|
65
|
+
which is to say, we don't go chasing after OpenGraph data to expand them.
|
|
66
|
+
|
|
67
|
+
YouTube/Spotify links become embeds (these won't work if you don't serve the file from _somewhere_),
|
|
68
|
+
|
|
69
|
+
image/audio/video links become the media, everything else degrades to a plain link.
|
|
70
|
+
|
|
71
|
+
### `marqueeFetch(source, options?) => Promise<string>`
|
|
72
|
+
|
|
73
|
+
In the above function we didn't fetch OpenGraph data (how could we? we were running in sync mode).
|
|
74
|
+
`marqueeFetch` does the same thing but it _does, in fact, go fetch that OpenGraph data!_.
|
|
75
|
+
|
|
76
|
+
`marquee()` plus the network: before rendering, runs every composed turbolink plugin's async
|
|
77
|
+
`resolve()` phase over the document's link targets — concurrently across targets, with the
|
|
78
|
+
OpenGraph plugin joining the chain automatically (10-second timeout per fetch). Gathered
|
|
79
|
+
summaries render as preview cards; failed or timed-out fetches degrade to plain links.
|
|
80
|
+
|
|
81
|
+
**Trust contract:** this function *executes plugin fetch code*. The default chain is safe;
|
|
82
|
+
if you pass your own turbolink `plugins`, you are vouching for them. Rendering itself remains synchronous and
|
|
83
|
+
fetchless — all network happens in the resolve phase, before render, never during.
|
|
84
|
+
|
|
85
|
+
### `marqueeFragment(source, options?) => { body, css, title, fontTokens }`
|
|
86
|
+
|
|
87
|
+
The pieces, for embedding in your own page:
|
|
88
|
+
|
|
89
|
+
- `body: string` — one `<div class="mq-doc">…</div>` fragment
|
|
90
|
+
- `css: string` — everything the body needs styled: the Marquee stylesheet, the composed
|
|
91
|
+
plugins' skins, and font faces per the `fonts` option
|
|
92
|
+
- `title: string` — the `title` option, else the document's `:::meta title`, else `"Marquee"`
|
|
93
|
+
- `fontTokens: string[]` — which font faces the body actually wears (feed to
|
|
94
|
+
`fontFilePath()` if you're hosting font files yourself)
|
|
95
|
+
|
|
96
|
+
### `marqueeBody(source, options?) => string` / `marqueeHead(source, options?) => string`
|
|
97
|
+
|
|
98
|
+
The fragment, pre-split for template stitching: `marqueeBody` returns just the body
|
|
99
|
+
fragment; `marqueeHead` returns `<title>…</title>\n<style>…</style>`, paste-ready for a
|
|
100
|
+
`<head>`.
|
|
101
|
+
|
|
102
|
+
### `buildSite(siteDir, outDir, options?) => SiteReport`
|
|
103
|
+
|
|
104
|
+
A folder of `.mq` files in, a static website out. The contract, precisely:
|
|
105
|
+
|
|
106
|
+
- **Every `<id>.mq` becomes `<id>.html`**, except files named `_*.mq`, which are *partials*:
|
|
107
|
+
includable via `:::include doc=_nav:::` but not rendered as pages. Includes resolve beside
|
|
108
|
+
the including file; included documents may not themselves include (cycles are therefore
|
|
109
|
+
unrepresentable); a missing include renders a visible placeholder, never an error.
|
|
110
|
+
- **Relative doc-id links resolve to built pages**: `[Menu](menu)` becomes `href="menu.html"`.
|
|
111
|
+
- **Relative media is copied** into `<out>/media/` (deduplicated, name-collision-safe) and
|
|
112
|
+
embeds re-point to the copies. Remote (`https:`) media is left as-is: readers fetch it.
|
|
113
|
+
- **Fonts ship as real files**: only the faces the site's pages actually use are copied to
|
|
114
|
+
`<out>/fonts/`, with a generated `css/fonts.css` pointing at them — cacheable across pages,
|
|
115
|
+
never base64.
|
|
116
|
+
- **Stylesheets are files**: `css/marquee.css` and `css/turbolink.css` (the composed plugin
|
|
117
|
+
chain's skins), linked from every page shell.
|
|
118
|
+
- Page titles come from each document's `:::meta title`, falling back to the file's id.
|
|
119
|
+
- Returns `{ pages: string[], mediaFiles: number, fontFaces: string[], outDir: string }`.
|
|
120
|
+
|
|
121
|
+
### `buildSiteFetch(siteDir, outDir, options?) => Promise<SiteReport>`
|
|
122
|
+
|
|
123
|
+
`buildSite()` with the fetch-ahead pass: gathers turbolink targets across *all* the site's
|
|
124
|
+
`.mq` files (partials included), resolves them once, builds with the results. Same trust
|
|
125
|
+
contract as `marqueeFetch`.
|
|
126
|
+
|
|
127
|
+
## Options
|
|
128
|
+
|
|
129
|
+
`MarqueeOptions` — every field optional:
|
|
130
|
+
|
|
131
|
+
| option | type | default | contract |
|
|
132
|
+
|---|---|---|---|
|
|
133
|
+
| `title` | `string` | document's `:::meta title`, else `"Marquee"` | the page `<title>` |
|
|
134
|
+
| `fonts` | `"inline" \| "external" \| "none"` | `"inline"` | `inline`: used faces embedded as base64 (self-contained page). `external`: `@font-face` rules point at `<fontBase><token>.woff2` — you copy the files (`fontTokens` names them, `fontFilePath()` locates them). `none`: no faces; font names degrade to their fallback stacks |
|
|
135
|
+
| `fontBase` | `string` | `"fonts/"` | URL prefix for `fonts: "external"` |
|
|
136
|
+
| `emoji` | `Record<string, string \| { image, alt? }>` | `{}` | your emoji table, layered over the defaults; yours win on collision. String values are replacement text; `{ image, alt? }` renders a character-sized inline `<img>` (the custom-emoji mechanism — the image URL is embedder-trusted, like every hook) |
|
|
137
|
+
| `emojiDefaults` | `boolean` | `true` | the standard gemoji table (`:sparkles:` and ~1,900 friends) loads implicitly. `false`: unlisted shortcodes stay literal `:slug:` |
|
|
138
|
+
| `colorScheme` | `"light" \| "dark"` | follow the reader's OS | forces the page shell's `color-scheme`. Applies to whole pages only; fragments follow their host |
|
|
139
|
+
| `envelope` | `boolean` | `false` | wrap the document in a 650px centered readability column. Defers to documents that *are* a `:::page` |
|
|
140
|
+
| `readable` | `boolean` | `true` for pages, `false` for fragments | the color-readability rescue: author colors keep their hue but their lightness is clamped toward the canvas's opposite (via CSS relative color syntax), so dark-red text survives dark mode. Containers that paint their own background are left alone; browsers without support see raw colors. Fragments default off because a host theming by class rather than OS preference would get the clamp backwards |
|
|
141
|
+
| `plugins` | `TurbolinkPlugin[]` | the fetchless default set | the turbolink chain, in priority order. In fetch mode, `opengraphPlugin` is appended unless already present |
|
|
142
|
+
| `profile` | `Partial<Profile>` | — | override any embedder policy hook (allowed URL schemes, media resolution, emoji, directives). Wins over everything above |
|
|
143
|
+
|
|
144
|
+
`SiteOptions` (for `buildSite`/`buildSiteFetch`) accepts `emoji`, `emojiDefaults`,
|
|
145
|
+
`colorScheme`, `envelope`, `readable`, `plugins`, and `profile` with identical meanings,
|
|
146
|
+
applied per-page.
|
|
147
|
+
|
|
148
|
+
## Safety, stated plainly
|
|
149
|
+
|
|
150
|
+
- Author bytes never reach output except through escaping; targets only through the profile's
|
|
151
|
+
scheme allowlist; the AST is the contract — nothing `innerHTML`-shaped exists.
|
|
152
|
+
- Unknown vocabulary degrades visibly (placeholders, literal text) and **never eats content**.
|
|
153
|
+
- The rendered page contains **zero JavaScript**. Effects are CSS, honor
|
|
154
|
+
`prefers-reduced-motion`, and reveal effects cannot hide text where animations don't run.
|
|
155
|
+
- The only code execution surface is plugin `resolve()` in the fetch functions, and only for
|
|
156
|
+
plugins you composed.
|
|
157
|
+
|
|
158
|
+
## Reaching deeper
|
|
159
|
+
|
|
160
|
+
Everything underneath is re-exported, so outgrowing the convenience never means switching
|
|
161
|
+
packages: `parse` and the AST types (`Node`, `Attrs`, `Reason`), `render` / `renderMarquee` /
|
|
162
|
+
`bareWebProfile` / `Profile` and the escapes, `marqueeCss`, `standardEmoji`, the font helpers
|
|
163
|
+
(`FONT_MANIFEST`, `fontFilePath`, `inlineFontFaces`, `externalFontFaces`), and the whole
|
|
164
|
+
turbolink toolkit (`TurbolinkPlugin`, `composeTurbolinks`, `resolveTargets`,
|
|
165
|
+
`turbolinkTargets`, `turbolinkStyles`, `renderCard`, `defaultPlugins`, `opengraphPlugin`).
|
|
166
|
+
The leaner-diet packages behind them: `@cube-drone/marquee-parser`, `-html-renderer`,
|
|
167
|
+
`-css`, `-fonts`, `-emoji`, `-turbolink` — same code, à la carte. This package deliberately
|
|
168
|
+
includes the ~1.3MB font grab bag; that's what batteries-included means.
|
|
169
|
+
|
|
170
|
+
Same version number across every package and the Rust crates = passed the same published
|
|
171
|
+
conformance corpus, by definition. License: MPL-2.0.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@cube-drone/marquee-markup",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.3.0",
|
|
4
4
|
"description": "Marquee, batteries included: parse + render to HTML in one motion, fonts and styles along for the ride, plus the `marquee` CLI",
|
|
5
5
|
"license": "MPL-2.0",
|
|
6
6
|
"repository": {
|
|
@@ -38,12 +38,12 @@
|
|
|
38
38
|
"prepack": "npm run build"
|
|
39
39
|
},
|
|
40
40
|
"dependencies": {
|
|
41
|
-
"@cube-drone/marquee-css": "^0.
|
|
42
|
-
"@cube-drone/marquee-emoji": "^0.
|
|
43
|
-
"@cube-drone/marquee-fonts": "^0.
|
|
44
|
-
"@cube-drone/marquee-html-renderer": "^0.
|
|
45
|
-
"@cube-drone/marquee-parser": "^0.
|
|
46
|
-
"@cube-drone/marquee-turbolink": "^0.
|
|
41
|
+
"@cube-drone/marquee-css": "^0.3.0",
|
|
42
|
+
"@cube-drone/marquee-emoji": "^0.3.0",
|
|
43
|
+
"@cube-drone/marquee-fonts": "^0.3.0",
|
|
44
|
+
"@cube-drone/marquee-html-renderer": "^0.3.0",
|
|
45
|
+
"@cube-drone/marquee-parser": "^0.3.0",
|
|
46
|
+
"@cube-drone/marquee-turbolink": "^0.3.0"
|
|
47
47
|
},
|
|
48
48
|
"devDependencies": {
|
|
49
49
|
"@types/node": "^24.0.0",
|