vowel 0.6.3 → 0.7.0-beta.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.
Files changed (165) hide show
  1. package/README.md +23 -17
  2. package/bin.js +87 -30
  3. package/cli.js +15 -0
  4. package/config.js +102 -16
  5. package/extractDate.js +70 -6
  6. package/index.js +14 -5
  7. package/package.json +42 -7
  8. package/plugins/assets/index.js +65 -0
  9. package/plugins/atproto/index.js +132 -0
  10. package/plugins/atproto/password.js +71 -0
  11. package/plugins/atproto/publish.js +406 -0
  12. package/plugins/atproto/record.js +144 -0
  13. package/plugins/atproto/rkey.js +54 -0
  14. package/plugins/deploy-cloudflare/index.js +92 -0
  15. package/plugins/fonts/index.js +18 -21
  16. package/plugins/html/assets/bundle-BeK1Hptv.css +21 -0
  17. package/plugins/html/bundle/assets/index-BeK1Hptv.css +21 -0
  18. package/plugins/html/bundle/index.js +21145 -0
  19. package/plugins/html/editor/EditButton.svelte +152 -0
  20. package/plugins/html/editor/Editor.svelte +51 -0
  21. package/plugins/html/editor/Overlays.svelte +6 -0
  22. package/plugins/html/editor/SettingsPanel.svelte +397 -0
  23. package/plugins/html/editor/Toolbar.svelte +644 -0
  24. package/plugins/html/editor/create-session.js +250 -0
  25. package/plugins/html/editor/directives.js +128 -0
  26. package/plugins/html/editor/frontmatter.js +97 -0
  27. package/plugins/html/editor/ingest.js +339 -0
  28. package/plugins/html/editor/main.js +94 -0
  29. package/plugins/html/editor/nodes/Alert.svelte +21 -0
  30. package/plugins/html/editor/nodes/Blockquote.svelte +9 -0
  31. package/plugins/html/editor/nodes/CodeBlock.svelte +19 -0
  32. package/plugins/html/editor/nodes/Embed.svelte +19 -0
  33. package/plugins/html/editor/nodes/Emphasis.svelte +11 -0
  34. package/plugins/html/editor/nodes/Heading.svelte +15 -0
  35. package/plugins/html/editor/nodes/Highlight.svelte +11 -0
  36. package/plugins/html/editor/nodes/Image.svelte +18 -0
  37. package/plugins/html/editor/nodes/InlineCode.svelte +11 -0
  38. package/plugins/html/editor/nodes/Link.svelte +17 -0
  39. package/plugins/html/editor/nodes/List.svelte +15 -0
  40. package/plugins/html/editor/nodes/ListItem.svelte +9 -0
  41. package/plugins/html/editor/nodes/Page.svelte +21 -0
  42. package/plugins/html/editor/nodes/Paragraph.svelte +9 -0
  43. package/plugins/html/editor/nodes/Strikethrough.svelte +11 -0
  44. package/plugins/html/editor/nodes/Strong.svelte +11 -0
  45. package/plugins/html/editor/nodes/ThematicBreak.svelte +9 -0
  46. package/plugins/html/editor/nodes/index.js +18 -0
  47. package/plugins/html/editor/rollup.config.js +35 -0
  48. package/plugins/html/editor/serialize.js +157 -0
  49. package/plugins/html/editor/settings-file.js +83 -0
  50. package/plugins/html/editor/socket.js +202 -0
  51. package/plugins/html/editor/source.js +43 -0
  52. package/plugins/html/image.js +104 -0
  53. package/plugins/html/index.js +760 -0
  54. package/plugins/html/partials.js +299 -0
  55. package/plugins/html/socialLinks.js +67 -0
  56. package/plugins/html/writeRules.js +377 -0
  57. package/plugins/icons/index.js +2 -6
  58. package/plugins/images/index.js +78 -55
  59. package/plugins/markdown/brandColors.js +10 -0
  60. package/plugins/markdown/colorScheme.js +64 -0
  61. package/plugins/markdown/emoji.js +30 -0
  62. package/plugins/markdown/frontmatter.js +253 -0
  63. package/plugins/markdown/index.js +287 -1274
  64. package/plugins/markdown/links.js +97 -0
  65. package/plugins/markdown/metadata.js +308 -0
  66. package/plugins/markdown/readRules.js +143 -0
  67. package/plugins/markdown/typography.js +109 -0
  68. package/plugins/markdown/visitor.js +143 -0
  69. package/plugins/publish/index.js +34 -0
  70. package/plugins/robots/agents.js +79 -0
  71. package/plugins/robots/index.js +30 -10
  72. package/plugins/robots/robots.js +48 -0
  73. package/plugins/styles/index.js +111 -26
  74. package/plugins/styles/theme.js +116 -0
  75. package/plugins/urls/index.js +78 -0
  76. package/plugins/urls/urlMetadata.js +246 -0
  77. package/plugins/vectors/index.js +5 -9
  78. package/plugins/xml/entryContent.js +103 -0
  79. package/plugins/xml/index.js +123 -50
  80. package/secretPaths.js +170 -0
  81. package/stylesheets/DefaultStyles.css +367 -437
  82. package/stylesheets/ResetStyles.css +2 -38
  83. package/stylesheets/SyntaxHighlightingStyles.css +269 -0
  84. package/stylesheets/TypographyStyles.css +386 -128
  85. package/systemPaths.js +48 -0
  86. package/utils.js +56 -5
  87. package/.github/ISSUE_TEMPLATE/bug_report.md +0 -73
  88. package/.github/ISSUE_TEMPLATE/config.yml +0 -7
  89. package/docs-source/.cache.json +0 -9
  90. package/docs-source/.obsidian/app.json +0 -3
  91. package/docs-source/.obsidian/appearance.json +0 -3
  92. package/docs-source/.obsidian/core-plugins-migration.json +0 -30
  93. package/docs-source/.obsidian/core-plugins.json +0 -20
  94. package/docs-source/.obsidian/workspace.json +0 -168
  95. package/docs-source/.stackblitzrc +0 -3
  96. package/docs-source/.votive.db +0 -0
  97. package/docs-source/about.md +0 -3
  98. package/docs-source/blog/home.md +0 -5
  99. package/docs-source/blog/url-ui.md +0 -21
  100. package/docs-source/blog.md +0 -5
  101. package/docs-source/docs/.votive.db +0 -0
  102. package/docs-source/docs/deploy.md +0 -67
  103. package/docs-source/docs/file-structure.md +0 -31
  104. package/docs-source/docs/folder-settings.md +0 -23
  105. package/docs-source/docs/home.md +0 -55
  106. package/docs-source/docs/images.md +0 -10
  107. package/docs-source/docs/items.md +0 -13
  108. package/docs-source/docs/pages.md +0 -141
  109. package/docs-source/docs/settings.md +0 -4
  110. package/docs-source/docs/styling.md +0 -34
  111. package/docs-source/docs/taxonomies.md +0 -37
  112. package/docs-source/features/cards.md +0 -7
  113. package/docs-source/features/editing.md +0 -7
  114. package/docs-source/features/emoji.md +0 -7
  115. package/docs-source/features/frontmatter.md +0 -7
  116. package/docs-source/features/lists.md +0 -7
  117. package/docs-source/features/navigation.md +0 -7
  118. package/docs-source/features/rich-previews.md +0 -7
  119. package/docs-source/features/robots.md +0 -7
  120. package/docs-source/features/rss.md +0 -7
  121. package/docs-source/features/sitemap.md +0 -7
  122. package/docs-source/features/speed.md +0 -7
  123. package/docs-source/features/static.md +0 -7
  124. package/docs-source/features/taxonomies.md +0 -7
  125. package/docs-source/home.md +0 -42
  126. package/docs-source/output/about.html +0 -1
  127. package/docs-source/output/blog/url-ui.html +0 -8
  128. package/docs-source/output/blog.html +0 -1
  129. package/docs-source/output/default.css +0 -1
  130. package/docs-source/output/docs/deploy.html +0 -34
  131. package/docs-source/output/docs/file-structure.html +0 -24
  132. package/docs-source/output/docs/folder-settings.html +0 -20
  133. package/docs-source/output/docs/images.html +0 -2
  134. package/docs-source/output/docs/items.html +0 -6
  135. package/docs-source/output/docs/pages.html +0 -101
  136. package/docs-source/output/docs/styling.html +0 -18
  137. package/docs-source/output/docs/taxonomies.html +0 -20
  138. package/docs-source/output/docs.html +0 -28
  139. package/docs-source/output/features/cards.html +0 -1
  140. package/docs-source/output/features/editing.html +0 -1
  141. package/docs-source/output/features/emoji.html +0 -1
  142. package/docs-source/output/features/frontmatter.html +0 -1
  143. package/docs-source/output/features/lists.html +0 -1
  144. package/docs-source/output/features/navigation.html +0 -1
  145. package/docs-source/output/features/rich-previews.html +0 -1
  146. package/docs-source/output/features/robots.html +0 -1
  147. package/docs-source/output/features/rss.html +0 -1
  148. package/docs-source/output/features/sitemap.html +0 -1
  149. package/docs-source/output/features/speed.html +0 -1
  150. package/docs-source/output/features/static.html +0 -1
  151. package/docs-source/output/features/taxonomies.html +0 -1
  152. package/docs-source/output/features.html +0 -1
  153. package/docs-source/output/feed.xml +0 -1
  154. package/docs-source/output/index.html +0 -21
  155. package/docs-source/output/reset.css +0 -1
  156. package/docs-source/output/roadmap.html +0 -87
  157. package/docs-source/output/robots.txt +0 -14
  158. package/docs-source/output/sitemap.xml +0 -16
  159. package/docs-source/output/typography.css +0 -1
  160. package/docs-source/roadmap.md +0 -98
  161. package/docs-source/settings.md +0 -13
  162. package/getMetadata.js +0 -41
  163. package/jsconfig.json +0 -10
  164. package/regex.js +0 -36
  165. package/stylesheets/brand-colors.css +0 -119
@@ -0,0 +1,299 @@
1
+ import path from "node:path"
2
+ import { h } from "hastscript"
3
+ import { isListedPage } from "../../utils.js"
4
+ import { isVowelStylesheet } from "../styles/theme.js"
5
+
6
+ /**
7
+ * Partials: rendered fragments shared by many pages, built once per
8
+ * pass instead of once per page.
9
+ *
10
+ * The header nav and the aside tree used to be computed inside every
11
+ * page's writeFile from a listing of every page - N listings and N²
12
+ * tracked reads per build (tasks/3-in-review/stress-test-findings.md,
13
+ * B). Now the html processor's enumerator computes the *data* for each
14
+ * partial once, from one untracked listing, and declares it as a
15
+ * virtual stub whose params are that data: votive re-expands it exactly
16
+ * when the data changes. The partial processor's readFile renders the
17
+ * data to hast and stores it as metadata; a page does one tracked read
18
+ * of its partial and walks a copy to mark the current page.
19
+ *
20
+ * Paths: `partials/nav.partial` is the header nav for pages at the
21
+ * root, `partials/nav/<folder>.partial` for pages in a folder - the
22
+ * lists for every level from the root down to that folder, and the
23
+ * project's own stylesheets along that chain (a `.css` the author wrote
24
+ * in any of those folders, with its content hash for the cache-buster).
25
+ * Both are "what this page's folder chain contributes", so they share a
26
+ * stub; the stylesheet half used to be one listing per ancestor per
27
+ * page, whose folder-membership edge restaled every page whenever any
28
+ * file was added at the root. There is
29
+ * one `partials/aside.partial`, the site tree, the same on every page.
30
+ * `partials/backlinks/<page path>.partial` is the "linked from" list
31
+ * of one page, declared only for pages something links to - a page
32
+ * with no linkers reads a miss, which votive tracks, so it is rebuilt
33
+ * the moment a linker appears.
34
+ * `.partial` is an extension nothing else claims, so a project file can
35
+ * never be read as one; the targets are virtual (write: false), which
36
+ * keeps them out of every listing, the sitemap and the feed.
37
+ */
38
+
39
+ const ASIDE_PARTIAL = path.join("partials", "aside.partial")
40
+
41
+ /** A page with more siblings than this is left out of the aside. */
42
+ const MAX_SIBLINGS = 18
43
+
44
+ /** @param {string} targetPath - the page's own target path */
45
+ function backlinksPartialPath(targetPath) {
46
+ return path.join("partials", "backlinks", `${targetPath}.partial`)
47
+ }
48
+
49
+ /** @param {string} folder - stored form (path.sep), "" for the root */
50
+ function navPartialPath(folder) {
51
+ return folder ? path.join("partials", "nav", `${folder}.partial`) : path.join("partials", "nav.partial")
52
+ }
53
+
54
+ /** A page is off when the author set the key to 0 or false. */
55
+ const isOn = (value) => value !== 0 && value !== false
56
+
57
+ /** What the header nav lists in a folder. */
58
+ function inHeaderNav(page) {
59
+ return page.path
60
+ && page.extension === ".html"
61
+ && !page.metadata.date
62
+ && page.path !== "index.html"
63
+ && page.path !== "404.html"
64
+ && page.path !== "tags.html"
65
+ && page.dir !== "tags"
66
+ && isOn(page.metadata.local_menu_item)
67
+ && isOn(page.metadata.html_file)
68
+ }
69
+
70
+ /** @param {any} a @param {any} b */
71
+ function byBreadcrumb(a, b) {
72
+ if (a.metadata.breadcrumb && b.metadata.breadcrumb) return String(a.metadata.breadcrumb).localeCompare(String(b.metadata.breadcrumb))
73
+ return 0
74
+ }
75
+
76
+ /** The folder and every ancestor, root first: "" , "a", "a/b". */
77
+ function chain(folder) {
78
+ if (!folder) return [""]
79
+ const segments = folder.split(path.sep)
80
+ return ["", ...segments.map((_, i) => segments.slice(0, i + 1).join(path.sep))]
81
+ }
82
+
83
+ /** A nav entry: where it goes and what it says. */
84
+ const item = (page) => ({ url: page.metadata.prettyURL, label: page.metadata.breadcrumb })
85
+
86
+ /**
87
+ * The aside tree: top-level pages with no date, each with the pages of
88
+ * the folder it names beneath it, recursively; the home page first.
89
+ * @param {any[]} pages
90
+ */
91
+ function asideTree(pages) {
92
+ const undated = pages.filter(page => page.path?.endsWith(".html") && !page.metadata.date)
93
+ const home = undated.find(page => page.path === "index.html" && page.dir === "")
94
+
95
+ // Indexed by folder url once: finding each node's children by filtering
96
+ // the whole list was O(N²), and the enumerator runs every pass.
97
+ const byFolder = new Map()
98
+ for (const page of undated) {
99
+ if (page.path === "index.html") continue
100
+ const url = "/" + page.dir.split(path.sep).join("/")
101
+ if (!byFolder.has(url)) byFolder.set(url, [])
102
+ byFolder.get(url).push(page)
103
+ }
104
+ // A page with more than MAX_SIBLINGS siblings is left out, and so are
105
+ // its siblings: the folder's own entry stays, and its pages are a
106
+ // listing's job, not a menu's. Per Sam: "exclude pages with 19
107
+ // siblings or more".
108
+ const children = (parent) => {
109
+ const pages = byFolder.get(parent.metadata.prettyURL) ?? []
110
+ return pages.length - 1 > MAX_SIBLINGS ? [] : pages.map(node)
111
+ }
112
+
113
+ function node(page) {
114
+ const below = children(page)
115
+ // The aside links the file, not the pretty url - kept as it was
116
+ // (see the note in the commit); the home entry is the bare path.
117
+ return { url: "/" + page.path, label: page.metadata.breadcrumb, ...(below.length ? { children: below } : {}) }
118
+ }
119
+
120
+ const top = undated
121
+ .filter(page => page.dir === "" && page.path !== "index.html" && page.path !== "404.html" && page.path !== "tags.html"
122
+ && isOn(page.metadata.global_menu_item) && isOn(page.metadata.html_file))
123
+ .map(node)
124
+
125
+ return [...(home ? [{ url: home.path, label: home.metadata.breadcrumb }] : []), ...top]
126
+ }
127
+
128
+ /**
129
+ * Who links to whom, from every page's recorded `links` (see
130
+ * plugins/markdown/links.js for the three spellings: a source path, a
131
+ * pretty url, a `[[Name]]`). Returns, per linked page, its linkers
132
+ * sorted by path. A name two pages share links both - the ambiguity
133
+ * the author wrote. The reverse index used to be a filtered listing
134
+ * per page: a full-table query with json_each per page, and a `links`
135
+ * change anywhere restaled every page.
136
+ * @param {any[]} pages - the linkers: what a listing shows
137
+ * @param {any[]} [linkable] - what can be linked to: every page, hidden
138
+ * ones included (a secret page gets its backlinks; it just never
139
+ * appears as a linker)
140
+ * @returns {Map<string, any[]>} target path -> linkers
141
+ */
142
+ function backlinkIndex(pages, linkable = pages) {
143
+ const bySource = new Map()
144
+ const byURL = new Map()
145
+ const byLabel = new Map()
146
+ for (const page of linkable) {
147
+ if (page.source) bySource.set(page.source, page)
148
+ if (page.metadata.prettyURL) byURL.set(page.metadata.prettyURL, page)
149
+ // Under every name a [[wikilink]] could reach it by: its filename
150
+ // key and its aliases (metadata.js), as readRules records them.
151
+ for (const name of [page.metadata.note_key, ...(page.metadata.note_aliases ?? [])]) {
152
+ if (!name) continue
153
+ const key = `[[${name}]]`
154
+ if (!byLabel.has(key)) byLabel.set(key, [])
155
+ byLabel.get(key).push(page)
156
+ }
157
+ }
158
+
159
+ const linkers = new Map()
160
+ const add = (linked, linker) => {
161
+ if (!linked || linked.path === linker.path) return
162
+ if (!linkers.has(linked.path)) linkers.set(linked.path, new Map())
163
+ linkers.get(linked.path).set(linker.path, linker)
164
+ }
165
+ for (const linker of pages) {
166
+ for (const link of linker.metadata.links ?? []) {
167
+ if (typeof link !== "string") continue
168
+ add(bySource.get(link), linker)
169
+ add(byURL.get(link), linker)
170
+ for (const linked of byLabel.get(link) ?? []) add(linked, linker)
171
+ }
172
+ }
173
+
174
+ return new Map([...linkers].map(([target, map]) => [target, [...map.values()].sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0)]))
175
+ }
176
+
177
+ /**
178
+ * Every partial the site needs this pass, as stubs. One untracked
179
+ * listing; the enumerator runs every pass by contract.
180
+ * @param {any} api - the enumerator's api
181
+ */
182
+ function createPartialStubs(api) {
183
+ // One listing, every pass: the pages, the linkable pages (hidden
184
+ // ones can still be linked to) and the stylesheets are three views of
185
+ // it, and a listing is the enumerator's whole cost.
186
+ const all = api.targets({ folder: "", recursive: true })
187
+ const pages = all.filter(isListedPage)
188
+ const linkable = all.filter(page => page.write !== false && page.extension === ".html")
189
+
190
+ const backlinks = [...backlinkIndex(pages, linkable)].map(([target, linkers]) => ({
191
+ path: backlinksPartialPath(target),
192
+ params: { pages: linkers.map(page => ({ url: page.metadata.prettyURL, title: page.metadata.title || page.metadata.prettyURL })) }
193
+ }))
194
+
195
+ const lists = new Map()
196
+ for (const page of pages) {
197
+ if (!inHeaderNav(page)) continue
198
+ if (!lists.has(page.dir)) lists.set(page.dir, [])
199
+ lists.get(page.dir).push(page)
200
+ }
201
+ for (const list of lists.values()) list.sort(byBreadcrumb)
202
+
203
+ // A nav partial for every folder any page lives in, and every ancestor
204
+ // of it - a folder of dated posts still shows its ancestors' lists.
205
+ const folders = new Set([""])
206
+ for (const page of pages) for (const folder of chain(page.dir)) folders.add(folder)
207
+
208
+ // The project's stylesheets by folder: a .css the author wrote (has a
209
+ // source, is not one vowel generates), with the hash its read recorded.
210
+ const sheets = new Map()
211
+ for (const sheet of all) {
212
+ if (!sheet.source || sheet.extension !== ".css" || isVowelStylesheet(sheet.path)) continue
213
+ if (!sheets.has(sheet.dir)) sheets.set(sheet.dir, [])
214
+ sheets.get(sheet.dir).push({ path: sheet.path, hash: sheet.metadata?.hash ?? "" })
215
+ }
216
+ for (const list of sheets.values()) list.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0)
217
+
218
+ const navs = [...folders].sort().map(folder => ({
219
+ path: navPartialPath(folder),
220
+ params: {
221
+ levels: chain(folder).map(level => (lists.get(level) ?? []).map(item)),
222
+ sheets: chain(folder).flatMap(level => sheets.get(level) ?? [])
223
+ }
224
+ }))
225
+
226
+ return [...navs, { path: ASIDE_PARTIAL, params: { items: asideTree(pages) } }, ...backlinks]
227
+ }
228
+
229
+ /** @type {import("votive").ProcessorExpand} */
230
+ function expandPartial({ params }) {
231
+ return { text: JSON.stringify(params) }
232
+ }
233
+
234
+ /** The header nav: one <ul> per level that has entries, root first. */
235
+ function renderNav({ levels }) {
236
+ return h("nav", levels
237
+ .filter(level => level.length)
238
+ .map(level => h("ul", level.map(({ url, label }) => h("li", h("a", { href: url }, label)))))
239
+ )
240
+ }
241
+
242
+ /** The aside tree. */
243
+ function renderAside({ items }) {
244
+ const li = ({ url, label, children }) => children
245
+ ? h("li", [h("a", { href: url }, label), h("ul", children.map(li))])
246
+ : h("li", h("a", { href: url }, label))
247
+ return h("nav", h("ul", items.map(li)))
248
+ }
249
+
250
+ /** "Linked from", outside section#content: it is generated, and the editor must not see it. */
251
+ function renderBacklinks({ pages }) {
252
+ return h("section#backlinks", [
253
+ h("ul", pages.map(({ url, title }) => h("li", h("a", { href: url }, title))))
254
+ ])
255
+ }
256
+
257
+ /**
258
+ * A partial's source is the JSON its stub was expanded to; the hast is
259
+ * rendered here and stored, so a page never renders it again. Which
260
+ * renderer is the path's business.
261
+ * @type {import("votive").ProcessorRead}
262
+ */
263
+ function readPartial(source) {
264
+ const data = JSON.parse(source.text || "{}")
265
+ const kind = source.path.split(path.sep)[1]?.replace(/\.partial$/, "")
266
+ const render = kind === "aside" ? renderAside : kind === "backlinks" ? renderBacklinks : renderNav
267
+ // A nav partial also carries its chain's stylesheets, as data: the
268
+ // page builds the <link>s, since the theme's sheets come first.
269
+ return { metadata: { hast: render(data), ...(data.sheets ? { sheets: data.sheets } : {}) }, write: false }
270
+ }
271
+
272
+ /**
273
+ * The page's copy of a nav, with the current page marked. A copy: the
274
+ * tracked read hands back a fresh parse, but a rule that relies on that
275
+ * would be fragile, and the walk mutates.
276
+ * @param {any} hast
277
+ * @param {string} url - the page's prettyURL
278
+ */
279
+ function withCurrent(hast, url) {
280
+ const copy = structuredClone(hast)
281
+ const walk = (node) => {
282
+ if (node.type === "element" && node.tagName === "a" && node.properties?.href === url) node.properties.ariaCurrent = "page"
283
+ node.children?.forEach(walk)
284
+ }
285
+ walk(copy)
286
+ return copy
287
+ }
288
+
289
+ /** @type {import("votive").VotiveProcessor} */
290
+ const partialsProcessor = {
291
+ extensions: [".partial"],
292
+ format: "text",
293
+ router: ({ name, dir, ext }) => ({ name, dir, ext }),
294
+ readFile: readPartial,
295
+ // Virtual: nothing lands on disk, and returning nothing marks it fresh.
296
+ writeFile: () => undefined
297
+ }
298
+
299
+ export { ASIDE_PARTIAL, navPartialPath, backlinksPartialPath, createPartialStubs, expandPartial, withCurrent, partialsProcessor, inHeaderNav, asideTree, backlinkIndex }
@@ -0,0 +1,67 @@
1
+ import { h } from "hastscript"
2
+
3
+ /**
4
+ * Social links, from the `social_links` setting:
5
+ *
6
+ * social_links:
7
+ * - label: GitHub
8
+ * url: https://github.com/samlfair
9
+ * icon: /icons/github.svg
10
+ * - label: Bluesky
11
+ * url: https://bsky.app/profile/littlefair.ca
12
+ *
13
+ * `icon` is a URL path from the root (`/x.svg`; `x.svg` means the same);
14
+ * `./x.svg` is the settings file's own folder. Resolved at read, in
15
+ * plugins/markdown/frontmatter.js, like `logo` and `icon`.
16
+ *
17
+ * A leaf overrides: the nearest folder that declares the label supplies
18
+ * the whole list, and nothing above it contributes. That is the one
19
+ * resolution `settings.lastNonNull()` cannot give for an array-valued
20
+ * label - it would hand back the last *link* at the deciding level -
21
+ * so the deciding slot is found from the raw sequence.
22
+ *
23
+ * No built-in icons, by decision: an author who wants one drops the SVG
24
+ * in the project and names it. With an icon the label is the image's
25
+ * alt text; without one it is the link text. The anchor carries the
26
+ * icon as `--icon-url` too, the same arrangement as `a#logo`, so a
27
+ * monochrome SVG can be masked in `currentColor` by the stylesheet.
28
+ * `rel="me"` is the identity-link convention (IndieAuth, Mastodon
29
+ * verification) and costs nothing.
30
+ */
31
+
32
+ const LABEL = "fm_social_links"
33
+
34
+ /**
35
+ * The nearest folder's whole list, or [].
36
+ * @param {any} settings - the folder-scoped view
37
+ * @returns {Array<{label?: string, url?: string, icon?: string}>}
38
+ */
39
+ function socialLinks(settings) {
40
+ const slots = settings?.raw?.(LABEL) ?? []
41
+ const decided = slots.findLast(slot => slot?.length)
42
+ return (decided ?? []).filter(link => link && typeof link === "object" && link.url)
43
+ }
44
+
45
+ /**
46
+ * A `<nav>` of the links, or null when there are none.
47
+ * @param {any} settings
48
+ */
49
+ function socialLinksNav(settings) {
50
+ const links = socialLinks(settings)
51
+ if (!links.length) return null
52
+
53
+ return h("nav.social-links", { "aria-label": "Social links" },
54
+ h("ul", links.map(({ label, url, icon }) => {
55
+ const text = label ?? url
56
+ // A URL path from the root, resolved at read (frontmatter.js).
57
+ const iconURL = icon ? String(icon) : null
58
+ return h("li", h("a", {
59
+ href: url,
60
+ rel: "me",
61
+ style: iconURL && `--icon-url: url("${iconURL}")`
62
+ }, iconURL ? h("img", { src: iconURL, alt: text }) : text))
63
+ }))
64
+ )
65
+ }
66
+
67
+ export { socialLinks, socialLinksNav }