@tinyvolt/pie 0.7.0 → 0.8.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/init/site-agents.md +17 -4
- package/package.json +1 -1
- package/pages/_terms.md +12 -0
- package/pages/about.md +1 -0
- package/pages/example.md +3 -2
- package/src/app.css +100 -0
- package/src/lib/markdown/features/build.ts +17 -11
- package/src/lib/markdown/features/glossary/View.tsx +64 -0
- package/src/lib/markdown/features/glossary/build.ts +89 -0
- package/src/lib/markdown/features/sidebar/build.ts +2 -1
- package/src/lib/markdown/features/tags/build.ts +22 -0
- package/src/lib/markdown/features/tags/pages.ts +42 -0
- package/src/lib/markdown/features/tags/url.ts +12 -0
- package/src/lib/markdown/features/views.tsx +2 -0
- package/src/lib/markdown/frontmatter.ts +14 -0
- package/src/lib/markdown/pages.ts +7 -4
- package/src/lib/markdown/render.ts +12 -2
- package/src/lib/markdown/vitePlugin.ts +14 -5
- package/src/routes/_tags/[tag].tsx +47 -0
- package/src/routes/_tags/index.tsx +22 -0
package/init/site-agents.md
CHANGED
|
@@ -16,7 +16,7 @@ npm run preview # preview the build with vite
|
|
|
16
16
|
|
|
17
17
|
| Folder / file | What it holds |
|
|
18
18
|
| --- | --- |
|
|
19
|
-
| `pages/` | Markdown pages. `pages/a/b.md` is served at `/a/b`. A file whose name starts with `_`, e.g. `pages/_topics.md`, gets no URL; use it as a sidebar. |
|
|
19
|
+
| `pages/` | Markdown pages. `pages/a/b.md` is served at `/a/b`. A file whose name starts with `_`, e.g. `pages/_topics.md`, gets no URL; use it as a sidebar or a glossary. |
|
|
20
20
|
| `functions/` | Your own TypeScript functions, called from Python as `pie.<keyword>(...)`. |
|
|
21
21
|
| `nodes/` | Your own node types: what a node holds and how it is drawn. |
|
|
22
22
|
| `ui/` | Your own UIs for nodes, called from Python as `pie.ui.<name>(...)`. |
|
|
@@ -35,7 +35,7 @@ Flat `key: value` lines. Values may be quoted. A key may appear only once.
|
|
|
35
35
|
- `title` (required): shown in the header and in every browser tab title.
|
|
36
36
|
- `url`: where the site is deployed, e.g. `https://example.com`. Needed for `sitemap.xml`, `robots.txt`, canonical links and `og:url`; without it the build skips them and warns.
|
|
37
37
|
- `description`: shown in search results and link previews for a page with no `description` of its own.
|
|
38
|
-
- `sidebar`, `toc`: the value for every page that doesn't set the key itself (see "Pages"). A `sidebar` path here is relative to the project root, e.g. `sidebar: pages/_topics.md`.
|
|
38
|
+
- `sidebar`, `toc`, `glossary`: the value for every page that doesn't set the key itself (see "Pages"). A `sidebar` or `glossary` path here is relative to the project root, e.g. `sidebar: pages/_topics.md`.
|
|
39
39
|
|
|
40
40
|
## Pages
|
|
41
41
|
|
|
@@ -58,12 +58,22 @@ canvas: left
|
|
|
58
58
|
- On screens narrower than `--sidebar-drawer-below` (768px by default), it opens over the page instead. Tapping outside it or on one of its links closes it.
|
|
59
59
|
- Its frontmatter is ignored. Its Python editors share variables only with each other, and have no canvas: a `pie.*` call there raises "this page has no canvas".
|
|
60
60
|
- `toc`: `true` or `false`. `true` adds a table of contents of the page's `##` and `###` headings, after its leading `#` title, or at the very start if it has none. Each `###` is nested under the `##` before it. Every heading gets an `id`, and duplicate headings get `-2`, `-3`, …. No list if the page has no `##` or `###`. Left out: `site.yml`'s `toc`, else `false`.
|
|
61
|
+
- `glossary`: a `.md` file of terms, e.g. `glossary: _terms.md`. The path is relative to the page's file. `none`: no glossary, even when `site.yml` sets one. Left out: `site.yml`'s `glossary`.
|
|
62
|
+
- In that file, each `##` heading is a term, and the text up to the next `##` is its definition, in any markdown. Its `#` heading names the section at the end of the page; without one, the section is called "Glossary". Other text before the first `##` is ignored.
|
|
63
|
+
- In the page, `[[term]]` marks a term, and `[[shown|term]]` shows other words. Matching ignores case. `[[...]]` inside code is left alone.
|
|
64
|
+
- Hovering a term shows a popup with the first 4 lines of its definition and a "more" link. On touch screens, a tap shows it and a tap anywhere else hides it.
|
|
65
|
+
- "more" opens a collapsed section at the end of the page and scrolls to the term. The section lists only the terms the page uses, in the file's order.
|
|
66
|
+
- `[[...]]` only works in the page's own text. In a sidebar file, in the glossary file, or on a page without a glossary, it shows as written, brackets included.
|
|
67
|
+
- `tags`: hashtags separated by spaces or commas, e.g. `tags: #math #linear-algebra`. A tag is made of letters, digits, `_`, `+` and `-`, and is turned into lower case. A word that isn't a tag, e.g. `math` without its `#`, is skipped without an error.
|
|
68
|
+
- The page shows its tags as links at the end of its text. Each opens `/_tags/<tag>`, which lists the pages with that tag, sorted by title. A page without a `title` is listed by its URL.
|
|
69
|
+
- `/_tags` lists every tag and how many pages have it. Only the tag pages link to it.
|
|
70
|
+
- Only a page's own frontmatter counts: `tags` in `site.yml` does nothing.
|
|
61
71
|
|
|
62
72
|
Other keys are ignored. A bad value fails the build, and shows an error screen in dev.
|
|
63
73
|
|
|
64
74
|
Math uses KaTeX: `$…$` inline, and `$$…$$` on its own lines for a display block.
|
|
65
75
|
|
|
66
|
-
A page's URL must not match a route in `node_modules/@tinyvolt/pie/src/routes/` (`/`, `/pages
|
|
76
|
+
A page's URL must not match a route in `node_modules/@tinyvolt/pie/src/routes/` (`/`, `/pages`, `/_tags`, `/_tags/<tag>`). For example, `pages/pages.md` fails the build.
|
|
67
77
|
|
|
68
78
|
## Python editors
|
|
69
79
|
|
|
@@ -332,6 +342,8 @@ Change the CSS variables in `styles/theme.css` (colors, fonts, text width), or a
|
|
|
332
342
|
|
|
333
343
|
- Sidebar: `--sidebar-width` (default `16rem`), `--sidebar-drawer-below` (default `768px`; narrower screens open it over the page) and `--color-backdrop` (behind it when it opens over the page). Its parts have the classes `.sidebar`, `.sidebar-text`, `.sidebar-edge`, `.sidebar-toggle` and `.sidebar-backdrop`.
|
|
334
344
|
- Table of contents: `.toc`.
|
|
345
|
+
- Glossary: `.term` (a term in the text), `.term-popup` (its popup), which holds `.term-popup-text` and `.term-more` (the "more" link), and `.glossary` (the section at the end of the page).
|
|
346
|
+
- Tags: `.tags` (the links at the end of a page) and `.tagged-description` (a page's description on a tag's page).
|
|
335
347
|
- UIs (`pie.ui.*`):
|
|
336
348
|
- `.python-editor-uis`: a block's UIs below its editor.
|
|
337
349
|
- `.python-editor-ui`: one UI, wherever it is. It holds `.python-editor-ui-grip` (the ⋮⋮ drag grip), `.python-editor-ui-label` (the `label`) and `.python-editor-ui-body` (the UI itself).
|
|
@@ -345,7 +357,8 @@ Change the CSS variables in `styles/theme.css` (colors, fonts, text width), or a
|
|
|
345
357
|
`npm run build` fails, with a message naming the file, when:
|
|
346
358
|
|
|
347
359
|
- a page's frontmatter or `site.yml` has a bad line or value, or `site.yml` has no `title`
|
|
348
|
-
- a `sidebar` file doesn't exist or is outside the project
|
|
360
|
+
- a `sidebar` or `glossary` file doesn't exist or is outside the project
|
|
361
|
+
- a page uses a `[[term]]` its glossary file doesn't have, or that file has a term twice, ignoring case
|
|
349
362
|
- a page's URL matches a route in `node_modules/@tinyvolt/pie/src/routes/`
|
|
350
363
|
- a `functions/` keyword is used twice
|
|
351
364
|
- a `nodes/` type name is used twice
|
package/package.json
CHANGED
package/pages/_terms.md
ADDED
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
## Gradient
|
|
2
|
+
The vector of partial derivatives of a function, $\nabla f = (\partial f / \partial x_1, \dots, \partial f / \partial x_n)$. It points in the direction in which the function grows fastest, and its length is how fast it grows in that direction.
|
|
3
|
+
|
|
4
|
+
At a minimum or maximum, the gradient is zero. Gradient descent uses this: it steps against the gradient, again and again, until the steps get tiny.
|
|
5
|
+
|
|
6
|
+
A third paragraph, so the popup has to cut the text off. It should end in "…" after four lines.
|
|
7
|
+
|
|
8
|
+
## Node
|
|
9
|
+
One shape or value on the canvas.
|
|
10
|
+
|
|
11
|
+
## Slider
|
|
12
|
+
A UI that sets a [[node]]'s value by dragging.
|
package/pages/about.md
CHANGED
package/pages/example.md
CHANGED
|
@@ -2,13 +2,14 @@
|
|
|
2
2
|
toc: true
|
|
3
3
|
sidebar: _topics.md
|
|
4
4
|
canvas: right
|
|
5
|
+
glossary: _terms.md
|
|
5
6
|
---
|
|
6
7
|
|
|
7
8
|
## Heading
|
|
8
9
|
|
|
9
|
-
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
|
|
10
|
+
Lorem ipsum dolor sit amet, consectetur adipiscing elit, the [[gradient]] of a long sentence that wraps onto the next line near the edge of the text, [[Gradient]].
|
|
10
11
|
|
|
11
|
-
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
|
|
12
|
+
Lorem ipsum dolor [[nodes|node]] sit amet, consectetur adipiscing elit, [[slider]].
|
|
12
13
|
|
|
13
14
|
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
|
|
14
15
|
|
package/src/app.css
CHANGED
|
@@ -385,6 +385,106 @@ main .katex-display {
|
|
|
385
385
|
text-decoration: underline;
|
|
386
386
|
}
|
|
387
387
|
|
|
388
|
+
/* `tags: #math`: the page's tags, at the end of its text. */
|
|
389
|
+
.tags {
|
|
390
|
+
display: flex;
|
|
391
|
+
flex-wrap: wrap;
|
|
392
|
+
gap: 0.25rem 0.75rem;
|
|
393
|
+
margin: 2rem 0 1rem;
|
|
394
|
+
font-size: 0.95em;
|
|
395
|
+
}
|
|
396
|
+
|
|
397
|
+
.tags a {
|
|
398
|
+
text-decoration: none;
|
|
399
|
+
}
|
|
400
|
+
|
|
401
|
+
.tags a:hover {
|
|
402
|
+
color: var(--color-hover, #000);
|
|
403
|
+
text-decoration: underline;
|
|
404
|
+
}
|
|
405
|
+
|
|
406
|
+
/* A page's description in the list of pages with a tag. */
|
|
407
|
+
.tagged-description {
|
|
408
|
+
margin: 0;
|
|
409
|
+
color: var(--color-muted, #555);
|
|
410
|
+
font-size: 0.95em;
|
|
411
|
+
}
|
|
412
|
+
|
|
413
|
+
/* `glossary: _terms.md`: a term in the text. */
|
|
414
|
+
.term {
|
|
415
|
+
text-decoration: underline dotted;
|
|
416
|
+
text-underline-offset: 0.15em;
|
|
417
|
+
cursor: pointer;
|
|
418
|
+
}
|
|
419
|
+
|
|
420
|
+
/* GlossaryView sets its top or bottom, and `--term-left`. It stays on screen, at most 22rem wide. */
|
|
421
|
+
.term-popup {
|
|
422
|
+
--term-popup-width: min(22rem, 100vw - 2rem);
|
|
423
|
+
display: none;
|
|
424
|
+
position: fixed;
|
|
425
|
+
z-index: 30;
|
|
426
|
+
left: clamp(1rem, var(--term-left), 100vw - 1rem - var(--term-popup-width));
|
|
427
|
+
box-sizing: border-box;
|
|
428
|
+
width: var(--term-popup-width);
|
|
429
|
+
padding: 0.5rem 0.75rem;
|
|
430
|
+
background: var(--color-bg, #fff);
|
|
431
|
+
border: 1px solid var(--color-border, #ddd);
|
|
432
|
+
border-radius: 4px;
|
|
433
|
+
box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
|
|
434
|
+
font-size: 0.9rem;
|
|
435
|
+
font-style: normal;
|
|
436
|
+
font-weight: normal;
|
|
437
|
+
cursor: auto;
|
|
438
|
+
}
|
|
439
|
+
|
|
440
|
+
@media (hover: hover) {
|
|
441
|
+
.term:hover > .term-popup {
|
|
442
|
+
display: block;
|
|
443
|
+
}
|
|
444
|
+
}
|
|
445
|
+
|
|
446
|
+
.term--open > .term-popup {
|
|
447
|
+
display: block;
|
|
448
|
+
}
|
|
449
|
+
|
|
450
|
+
/* The first 4 lines of the definition, then "…". */
|
|
451
|
+
.term-popup-text {
|
|
452
|
+
display: -webkit-box;
|
|
453
|
+
-webkit-box-orient: vertical;
|
|
454
|
+
-webkit-line-clamp: 4;
|
|
455
|
+
line-clamp: 4;
|
|
456
|
+
overflow: hidden;
|
|
457
|
+
}
|
|
458
|
+
|
|
459
|
+
.term-popup-text > * {
|
|
460
|
+
margin: 0;
|
|
461
|
+
}
|
|
462
|
+
|
|
463
|
+
.term-more {
|
|
464
|
+
color: var(--color-muted, #555);
|
|
465
|
+
}
|
|
466
|
+
|
|
467
|
+
/* The page's glossary, at its end, collapsed. */
|
|
468
|
+
.glossary {
|
|
469
|
+
margin: 2rem 0 0;
|
|
470
|
+
padding-top: 1rem;
|
|
471
|
+
border-top: 1px solid var(--color-border, #ddd);
|
|
472
|
+
}
|
|
473
|
+
|
|
474
|
+
.glossary summary {
|
|
475
|
+
cursor: pointer;
|
|
476
|
+
font-weight: 600;
|
|
477
|
+
}
|
|
478
|
+
|
|
479
|
+
.glossary dt {
|
|
480
|
+
margin-top: 1rem;
|
|
481
|
+
font-weight: 600;
|
|
482
|
+
}
|
|
483
|
+
|
|
484
|
+
.glossary dd {
|
|
485
|
+
margin: 0.25rem 0 0;
|
|
486
|
+
}
|
|
487
|
+
|
|
388
488
|
/* Hidden until MarkdownBody swaps it for the editor; keeps its space so the text below doesn't jump. */
|
|
389
489
|
pre:has(> code.language-python-editor) {
|
|
390
490
|
visibility: hidden;
|
|
@@ -13,7 +13,9 @@
|
|
|
13
13
|
*/
|
|
14
14
|
import type { MarkedExtension } from 'marked';
|
|
15
15
|
import type { Field } from '../frontmatter';
|
|
16
|
+
import { glossary } from './glossary/build';
|
|
16
17
|
import { sidebar } from './sidebar/build';
|
|
18
|
+
import { tags } from './tags/build';
|
|
17
19
|
import { toc } from './toc/build';
|
|
18
20
|
|
|
19
21
|
/** The second argument to a feature's `build`. */
|
|
@@ -22,8 +24,8 @@ export interface BuildContext {
|
|
|
22
24
|
file: string;
|
|
23
25
|
/** The file that set the value: the page, or `site.yml`. */
|
|
24
26
|
from: string;
|
|
25
|
-
/** The
|
|
26
|
-
|
|
27
|
+
/** The markdown of the `.md` file at `path`, relative to the folder of `from`, without its frontmatter. Throws if it's missing or outside the project. */
|
|
28
|
+
readFile(path: string): string;
|
|
27
29
|
}
|
|
28
30
|
|
|
29
31
|
/** A feature's build half. `T`: its frontmatter value. `D`: the data its view gets. */
|
|
@@ -31,19 +33,22 @@ export interface FeatureBuild<T, D> {
|
|
|
31
33
|
field: Field<T>;
|
|
32
34
|
/** Returns `undefined` to turn the feature off on this page. */
|
|
33
35
|
build(value: T, ctx: BuildContext): D | undefined;
|
|
34
|
-
/** Extra markdown syntax for this page. */
|
|
35
|
-
markdown?(
|
|
36
|
+
/** Extra markdown syntax for this page. Called only when `build` didn't turn the feature off. */
|
|
37
|
+
markdown?(value: T, ctx: BuildContext): MarkedExtension;
|
|
36
38
|
}
|
|
37
39
|
|
|
38
|
-
/**
|
|
39
|
-
|
|
40
|
+
/**
|
|
41
|
+
* Keyed by frontmatter key. The last feature's `postprocess` runs first, so `tags`, being after `glossary`,
|
|
42
|
+
* ends the page's text and the glossary comes after it.
|
|
43
|
+
*/
|
|
44
|
+
const FEATURES = { sidebar, toc, glossary, tags };
|
|
40
45
|
|
|
41
46
|
type DataOf<F> = F extends FeatureBuild<any, infer D> ? D : never;
|
|
42
47
|
|
|
43
|
-
// Today: `{ sidebar?: string; toc?: true }`.
|
|
48
|
+
// Today: `{ sidebar?: string; toc?: true; glossary?: true; tags?: true }`.
|
|
44
49
|
export type FeatureData = { [K in keyof typeof FEATURES]?: DataOf<(typeof FEATURES)[K]> };
|
|
45
50
|
|
|
46
|
-
// Today: `{ sidebar: sidebar.field, toc: toc.field }`. `site.yml` reads these too.
|
|
51
|
+
// Today: `{ sidebar: sidebar.field, toc: toc.field, glossary: glossary.field, tags: tags.field }`. `site.yml` reads these too.
|
|
47
52
|
export const FEATURE_FIELDS = Object.fromEntries(
|
|
48
53
|
Object.entries(FEATURES).map(([key, feature]) => [key, feature.field]),
|
|
49
54
|
) as { [K in keyof typeof FEATURES]: (typeof FEATURES)[K]['field'] };
|
|
@@ -53,7 +58,7 @@ export function buildFeatures(
|
|
|
53
58
|
file: string,
|
|
54
59
|
raw: Record<string, string>,
|
|
55
60
|
site: Record<string, unknown>,
|
|
56
|
-
|
|
61
|
+
readFile: (from: string, path: string) => string,
|
|
57
62
|
): { data: FeatureData; extensions: MarkedExtension[] } {
|
|
58
63
|
const data: Record<string, unknown> = {};
|
|
59
64
|
const extensions: MarkedExtension[] = [];
|
|
@@ -61,10 +66,11 @@ export function buildFeatures(
|
|
|
61
66
|
const from = Object.hasOwn(raw, key) ? file : 'site.yml';
|
|
62
67
|
try {
|
|
63
68
|
const value = from === file ? feature.field.parse(raw[key]) : site[key];
|
|
64
|
-
const
|
|
69
|
+
const ctx: BuildContext = { file, from, readFile: path => readFile(from, path) };
|
|
70
|
+
const built = feature.build(value, ctx);
|
|
65
71
|
if (built === undefined) continue;
|
|
66
72
|
data[key] = built;
|
|
67
|
-
if (feature.markdown) extensions.push(feature.markdown(
|
|
73
|
+
if (feature.markdown) extensions.push(feature.markdown(value, ctx));
|
|
68
74
|
} catch (e) {
|
|
69
75
|
throw new Error(`${from}: \`${key}\` ${(e as Error).message}`);
|
|
70
76
|
}
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
import { onCleanup, onMount, type JSX } from 'solid-js';
|
|
2
|
+
|
|
3
|
+
/** A popup for `term`: the start of its definition, copied from the page's glossary, and a "more" link to all of it. */
|
|
4
|
+
function makePopup(term: HTMLElement): HTMLElement {
|
|
5
|
+
const id = term.dataset.term!;
|
|
6
|
+
const definition = document.getElementById(id)!.nextElementSibling!;
|
|
7
|
+
const popup = document.createElement('div');
|
|
8
|
+
popup.className = 'term-popup';
|
|
9
|
+
popup.innerHTML = `<div class="term-popup-text">${definition.innerHTML}</div><a class="term-more" href="#${id}">more</a>`;
|
|
10
|
+
return popup;
|
|
11
|
+
}
|
|
12
|
+
|
|
13
|
+
/** Gives `term` its popup if it has none, and puts it under the term, or over it when the term is in the lower half of the screen. */
|
|
14
|
+
function place(term: HTMLElement) {
|
|
15
|
+
const popup = term.querySelector<HTMLElement>(':scope > .term-popup') ?? term.appendChild(makePopup(term));
|
|
16
|
+
const rect = term.getBoundingClientRect();
|
|
17
|
+
const height = document.documentElement.clientHeight;
|
|
18
|
+
const below = rect.bottom < height / 2;
|
|
19
|
+
popup.style.top = below ? `${rect.bottom}px` : '';
|
|
20
|
+
popup.style.bottom = below ? '' : `${height - rect.top}px`;
|
|
21
|
+
popup.style.setProperty('--term-left', `${rect.left}px`);
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
/**
|
|
25
|
+
* `children`, whose glossary terms show a popup on hover. A tap on a term also shows it, for touch screens,
|
|
26
|
+
* and a tap anywhere else hides it. The popup's "more" opens the page's glossary at the term.
|
|
27
|
+
*/
|
|
28
|
+
export function GlossaryView(props: { data: true; children: JSX.Element }) {
|
|
29
|
+
onMount(() => {
|
|
30
|
+
const onPointerOver = (e: PointerEvent) => {
|
|
31
|
+
const term = (e.target as Element).closest<HTMLElement>('.term');
|
|
32
|
+
if (term) place(term);
|
|
33
|
+
};
|
|
34
|
+
|
|
35
|
+
// Capture: runs before the router follows a "more" link, so the glossary is open when it scrolls to the term.
|
|
36
|
+
const onClick = (e: MouseEvent) => {
|
|
37
|
+
const target = e.target as Element;
|
|
38
|
+
const inPopup = target.closest('.term-popup') !== null;
|
|
39
|
+
const more = target.closest('.term-more') !== null;
|
|
40
|
+
if (inPopup && !more) return;
|
|
41
|
+
if (more) document.querySelector<HTMLDetailsElement>('.glossary')!.open = true;
|
|
42
|
+
const term = inPopup ? null : target.closest<HTMLElement>('.term');
|
|
43
|
+
for (const open of document.querySelectorAll('.term--open')) if (open !== term) open.classList.remove('term--open');
|
|
44
|
+
if (term) {
|
|
45
|
+
place(term);
|
|
46
|
+
term.classList.toggle('term--open');
|
|
47
|
+
}
|
|
48
|
+
};
|
|
49
|
+
|
|
50
|
+
// A popup is fixed to the screen, so it's moved to follow its term.
|
|
51
|
+
const onScroll = () => document.querySelectorAll<HTMLElement>('.term--open, .term:hover').forEach(place);
|
|
52
|
+
|
|
53
|
+
document.addEventListener('pointerover', onPointerOver);
|
|
54
|
+
document.addEventListener('click', onClick, true);
|
|
55
|
+
document.addEventListener('scroll', onScroll, true);
|
|
56
|
+
onCleanup(() => {
|
|
57
|
+
document.removeEventListener('pointerover', onPointerOver);
|
|
58
|
+
document.removeEventListener('click', onClick, true);
|
|
59
|
+
document.removeEventListener('scroll', onScroll, true);
|
|
60
|
+
});
|
|
61
|
+
});
|
|
62
|
+
|
|
63
|
+
return props.children;
|
|
64
|
+
}
|
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
import { Lexer, type MarkedExtension } from 'marked';
|
|
2
|
+
import { markdownFile } from '../../frontmatter';
|
|
3
|
+
import { renderInline, renderMarkdown } from '../../render';
|
|
4
|
+
import type { FeatureBuild } from '../build';
|
|
5
|
+
|
|
6
|
+
interface Term {
|
|
7
|
+
/** The `id` of its entry in the page's glossary, e.g. `term-3`. */
|
|
8
|
+
id: string;
|
|
9
|
+
/** Its heading as HTML, e.g. with its math rendered. */
|
|
10
|
+
name: string;
|
|
11
|
+
/** Its definition as HTML. */
|
|
12
|
+
html: string;
|
|
13
|
+
}
|
|
14
|
+
|
|
15
|
+
/** Matching ignores case. */
|
|
16
|
+
const key = (name: string) => name.trim().toLowerCase();
|
|
17
|
+
|
|
18
|
+
/** The section's title when the glossary file has no `#` heading. */
|
|
19
|
+
const DEFAULT_TITLE = 'Glossary';
|
|
20
|
+
|
|
21
|
+
/**
|
|
22
|
+
* The glossary file `file`. `title`: its `#` heading, as HTML. `terms`: by `key`, in the file's order.
|
|
23
|
+
* Each `##` heading is a term, and the text up to the next one is its definition.
|
|
24
|
+
* Other text before the first `##` is ignored.
|
|
25
|
+
*/
|
|
26
|
+
function parseGlossary(file: string, markdown: string): { title: string; terms: Map<string, Term> } {
|
|
27
|
+
let title = DEFAULT_TITLE;
|
|
28
|
+
const sections: { name: string; body: string }[] = [];
|
|
29
|
+
for (const token of Lexer.lex(markdown)) {
|
|
30
|
+
if (token.type === 'heading' && token.depth === 2) sections.push({ name: token.text, body: '' });
|
|
31
|
+
else if (sections.length > 0) sections[sections.length - 1].body += token.raw;
|
|
32
|
+
else if (token.type === 'heading' && token.depth === 1) title = renderInline(token.text);
|
|
33
|
+
}
|
|
34
|
+
const terms = new Map<string, Term>();
|
|
35
|
+
sections.forEach(({ name, body }, i) => {
|
|
36
|
+
if (terms.has(key(name))) throw new Error(`file ${file} has the term ${JSON.stringify(name)} twice`);
|
|
37
|
+
terms.set(key(name), { id: `term-${i + 1}`, name: renderInline(name), html: renderMarkdown(body) });
|
|
38
|
+
});
|
|
39
|
+
return { title, terms };
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
/** The page's glossary, collapsed: the terms it uses, in the glossary file's order. */
|
|
43
|
+
function glossaryHtml(title: string, terms: Term[]): string {
|
|
44
|
+
const entries = terms.map(t => `<dt id="${t.id}">${t.name}</dt><dd>${t.html}</dd>`).join('');
|
|
45
|
+
return `<details class="glossary"><summary>${title}</summary><dl>${entries}</dl></details>\n`;
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
/**
|
|
49
|
+
* `glossary: _terms.md`: `[[term]]` and `[[shown|term]]` in the page become terms with a popup (see `View.tsx`),
|
|
50
|
+
* and the page ends with a collapsed glossary of the terms it uses. A term missing from the file fails the build.
|
|
51
|
+
*/
|
|
52
|
+
export const glossary: FeatureBuild<string, true> = {
|
|
53
|
+
field: markdownFile(),
|
|
54
|
+
build: file => (file === '' || file === 'none' ? undefined : true),
|
|
55
|
+
markdown(file, ctx) {
|
|
56
|
+
const { title, terms } = parseGlossary(file, ctx.readFile(file));
|
|
57
|
+
const used = new Set<Term>();
|
|
58
|
+
return {
|
|
59
|
+
extensions: [
|
|
60
|
+
{
|
|
61
|
+
name: 'term',
|
|
62
|
+
level: 'inline',
|
|
63
|
+
start(src) {
|
|
64
|
+
const at = src.indexOf('[[');
|
|
65
|
+
return at === -1 ? undefined : at;
|
|
66
|
+
},
|
|
67
|
+
tokenizer(src) {
|
|
68
|
+
const match = /^\[\[([^[\]|]+)(?:\|([^[\]|]+))?\]\]/.exec(src);
|
|
69
|
+
if (!match) return undefined;
|
|
70
|
+
const [raw, shown, name = shown] = match;
|
|
71
|
+
const term = terms.get(key(name));
|
|
72
|
+
if (!term) throw new Error(`[[${name}]]: ${file} has no such term`);
|
|
73
|
+
used.add(term);
|
|
74
|
+
return { type: 'term', raw, term, tokens: this.lexer.inlineTokens(shown) };
|
|
75
|
+
},
|
|
76
|
+
renderer(token) {
|
|
77
|
+
return `<span class="term" data-term="${token.term.id}">${this.parser.parseInline(token.tokens!)}</span>`;
|
|
78
|
+
},
|
|
79
|
+
},
|
|
80
|
+
],
|
|
81
|
+
hooks: {
|
|
82
|
+
postprocess(html) {
|
|
83
|
+
if (used.size === 0) return html;
|
|
84
|
+
return html + glossaryHtml(title, [...terms.values()].filter(t => used.has(t)));
|
|
85
|
+
},
|
|
86
|
+
},
|
|
87
|
+
} satisfies MarkedExtension;
|
|
88
|
+
},
|
|
89
|
+
};
|
|
@@ -1,8 +1,9 @@
|
|
|
1
1
|
import { markdownFile } from '../../frontmatter';
|
|
2
|
+
import { renderMarkdown } from '../../render';
|
|
2
3
|
import type { FeatureBuild } from '../build';
|
|
3
4
|
|
|
4
5
|
/** `sidebar: _topics.md`: that file's HTML, shown in a sidebar. `none`: no sidebar, even when `site.yml` sets one. */
|
|
5
6
|
export const sidebar: FeatureBuild<string, string> = {
|
|
6
7
|
field: markdownFile(),
|
|
7
|
-
build: (file, ctx) => (file === '' || file === 'none' ? undefined : ctx.
|
|
8
|
+
build: (file, ctx) => (file === '' || file === 'none' ? undefined : renderMarkdown(ctx.readFile(file))),
|
|
8
9
|
};
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
import type { MarkedExtension } from 'marked';
|
|
2
|
+
import { hashtags } from '../../frontmatter';
|
|
3
|
+
import { escapeHtml } from '../../render';
|
|
4
|
+
import type { FeatureBuild } from '../build';
|
|
5
|
+
import { tagUrl } from './url';
|
|
6
|
+
|
|
7
|
+
/**
|
|
8
|
+
* `tags: #math #linear-algebra`: the page's tags, as links at the end of its text. Each link opens the page
|
|
9
|
+
* listing the pages with that tag, in `src/routes/_tags/`. Only a page's own frontmatter counts, not `site.yml`.
|
|
10
|
+
*/
|
|
11
|
+
export const tags: FeatureBuild<string[], true> = {
|
|
12
|
+
field: hashtags(),
|
|
13
|
+
build: (tags, ctx) => (ctx.from === ctx.file && tags.length > 0 ? true : undefined),
|
|
14
|
+
markdown(tags) {
|
|
15
|
+
const links = tags.map(tag => `<a href="${escapeHtml(tagUrl(tag))}">#${escapeHtml(tag)}</a>`).join('');
|
|
16
|
+
return {
|
|
17
|
+
hooks: {
|
|
18
|
+
postprocess: html => `${html}<nav class="tags">${links}</nav>\n`,
|
|
19
|
+
},
|
|
20
|
+
} satisfies MarkedExtension;
|
|
21
|
+
},
|
|
22
|
+
};
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
import { slugOf } from '../../pages';
|
|
2
|
+
import { tagSegment } from './url';
|
|
3
|
+
|
|
4
|
+
/** One `pages/**\/*.md` imported with `?tags`, as `vitePlugin.ts` turns it into a module at build time. */
|
|
5
|
+
export interface PageTags {
|
|
6
|
+
title: string;
|
|
7
|
+
description: string;
|
|
8
|
+
tags: string[];
|
|
9
|
+
}
|
|
10
|
+
|
|
11
|
+
export interface TaggedPage {
|
|
12
|
+
slug: string;
|
|
13
|
+
/** The page's `title`, or its slug if it has none. */
|
|
14
|
+
title: string;
|
|
15
|
+
description: string;
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
// Eager: a tag's page needs every page's tags at once. Only the routes in `src/routes/_tags/` import this file.
|
|
19
|
+
const modules = import.meta.glob<PageTags>(['/pages/**/*.md', '!/pages/**/_*.md'], {
|
|
20
|
+
eager: true,
|
|
21
|
+
query: '?tags',
|
|
22
|
+
import: 'default',
|
|
23
|
+
});
|
|
24
|
+
|
|
25
|
+
const byTag = new Map<string, TaggedPage[]>();
|
|
26
|
+
for (const [path, { title, description, tags }] of Object.entries(modules)) {
|
|
27
|
+
const slug = slugOf(path);
|
|
28
|
+
for (const tag of tags) {
|
|
29
|
+
if (!byTag.has(tag)) byTag.set(tag, []);
|
|
30
|
+
byTag.get(tag)!.push({ slug, title: title || slug, description });
|
|
31
|
+
}
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
/** Every tag, sorted, with its pages sorted by title. */
|
|
35
|
+
export const allTags = [...byTag]
|
|
36
|
+
.map(([tag, pages]) => ({ tag, pages: pages.sort((a, b) => a.title.localeCompare(b.title)) }))
|
|
37
|
+
.sort((a, b) => a.tag.localeCompare(b.tag));
|
|
38
|
+
|
|
39
|
+
/** The tag whose page has `segment` as the last part of its URL, which is still encoded, e.g. `caf%C3%A9`. */
|
|
40
|
+
export function tagAt(segment: string) {
|
|
41
|
+
return allTags.find(({ tag }) => tagSegment(tag) === segment);
|
|
42
|
+
}
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
/** The page listing every tag. Starts with `_` so it can't be taken by a site's own page. */
|
|
2
|
+
export const TAGS_URL = '/_tags';
|
|
3
|
+
|
|
4
|
+
/** The last part of the URL of the page for `tag`. Not `encodeURIComponent`: prerendering would encode its `%2B` again. */
|
|
5
|
+
export function tagSegment(tag: string): string {
|
|
6
|
+
return encodeURI(tag);
|
|
7
|
+
}
|
|
8
|
+
|
|
9
|
+
/** The page listing the pages with `tag`. */
|
|
10
|
+
export function tagUrl(tag: string): string {
|
|
11
|
+
return `${TAGS_URL}/${tagSegment(tag)}`;
|
|
12
|
+
}
|
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
// The view part of every feature: runs in the browser. Each feature's build part is in `build.ts`.
|
|
2
2
|
import type { Component, JSX } from 'solid-js';
|
|
3
3
|
import type { FeatureData } from './build';
|
|
4
|
+
import { GlossaryView } from './glossary/View';
|
|
4
5
|
import { SidebarView } from './sidebar/View';
|
|
5
6
|
|
|
6
7
|
/** A feature's view: wraps the page, given the feature's data. */
|
|
@@ -9,6 +10,7 @@ type FeatureView<D> = Component<{ data: D; children: JSX.Element }>;
|
|
|
9
10
|
/** Every feature's view, by key, outermost first. A feature with no view, like `toc`, is left out. */
|
|
10
11
|
const VIEWS: { [K in keyof FeatureData]: FeatureView<NonNullable<FeatureData[K]>> } = {
|
|
11
12
|
sidebar: SidebarView,
|
|
13
|
+
glossary: GlossaryView,
|
|
12
14
|
};
|
|
13
15
|
|
|
14
16
|
/** `body` wrapped in the view of every feature that is on for the page, the first in `VIEWS` outermost. */
|
|
@@ -45,6 +45,20 @@ export function markdownFile(): Field<string> {
|
|
|
45
45
|
};
|
|
46
46
|
}
|
|
47
47
|
|
|
48
|
+
/**
|
|
49
|
+
* Words written `#tag`, separated by spaces or commas, lowercased and without repeats. Other words are ignored.
|
|
50
|
+
* A tag has only letters, numbers, `-`, `_` and `+`: it's also a URL, and prerendering can't reach one with `/`, `?` or `.`.
|
|
51
|
+
*/
|
|
52
|
+
export function hashtags(): Field<string[]> {
|
|
53
|
+
return {
|
|
54
|
+
default: [],
|
|
55
|
+
parse(raw) {
|
|
56
|
+
const words = raw.split(/[\s,]+/).map(word => /^#([\p{L}\p{N}_+-]+)$/u.exec(word)?.[1].toLowerCase());
|
|
57
|
+
return [...new Set(words.filter(tag => tag !== undefined))];
|
|
58
|
+
},
|
|
59
|
+
};
|
|
60
|
+
}
|
|
61
|
+
|
|
48
62
|
/** Every frontmatter field a page can set. Keys not listed here are ignored. */
|
|
49
63
|
const FIELDS = {
|
|
50
64
|
canvas: oneOf(['left', 'right', 'top', 'bottom', 'none'], 'none'),
|
|
@@ -12,10 +12,13 @@ export interface Page {
|
|
|
12
12
|
// A file whose name starts with `_` is not a page; it can still be used by a feature, e.g. as a sidebar.
|
|
13
13
|
const loaders = import.meta.glob<Page>(['/pages/**/*.md', '!/pages/**/_*.md'], { import: 'default' });
|
|
14
14
|
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
15
|
+
/** `/pages/a/b.md` -> `a/b`. */
|
|
16
|
+
export function slugOf(path: string): string {
|
|
17
|
+
return path.replace(/^\/pages\//, '').replace(/\.md$/, '');
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
// Slug -> loader.
|
|
21
|
+
const bySlug = new Map(Object.entries(loaders).map(([path, load]) => [slugOf(path), load]));
|
|
19
22
|
|
|
20
23
|
export const slugs = [...bySlug.keys()];
|
|
21
24
|
|
|
@@ -7,7 +7,7 @@ function renderMath(formula: string, displayMode: boolean): string {
|
|
|
7
7
|
return katex.renderToString(formula, { displayMode, throwOnError: false });
|
|
8
8
|
}
|
|
9
9
|
|
|
10
|
-
function escapeHtml(text: string): string {
|
|
10
|
+
export function escapeHtml(text: string): string {
|
|
11
11
|
return text.replace(/&/g, '&').replace(/</g, '<').replace(/>/g, '>').replace(/"/g, '"');
|
|
12
12
|
}
|
|
13
13
|
|
|
@@ -90,5 +90,15 @@ const marked = new Marked(BASE);
|
|
|
90
90
|
/** `extensions`: markdown syntax the page's features add. */
|
|
91
91
|
export function renderMarkdown(markdown: string, extensions: MarkedExtension[] = []): string {
|
|
92
92
|
const parser = extensions.length === 0 ? marked : new Marked(BASE, ...extensions);
|
|
93
|
-
|
|
93
|
+
try {
|
|
94
|
+
return parser.parse(markdown) as string;
|
|
95
|
+
} catch (e) {
|
|
96
|
+
// marked adds "Please report this to …" to every error, even a feature's, e.g. an unknown glossary term.
|
|
97
|
+
throw new Error((e as Error).message.replace(/\nPlease report this to .*$/, ''));
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
/** One line of markdown as HTML, without the `<p>` around it. */
|
|
102
|
+
export function renderInline(markdown: string): string {
|
|
103
|
+
return marked.parseInline(markdown) as string;
|
|
94
104
|
}
|
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
import fs from 'node:fs';
|
|
2
2
|
import path from 'node:path';
|
|
3
3
|
import type { Plugin } from 'vite';
|
|
4
|
-
import { buildFeatures } from './features/build';
|
|
4
|
+
import { buildFeatures, FEATURE_FIELDS } from './features/build';
|
|
5
|
+
import type { PageTags } from './features/tags/pages';
|
|
5
6
|
import { parseFrontmatter } from './frontmatter';
|
|
6
7
|
import type { Page } from './pages';
|
|
7
8
|
import { renderMarkdown } from './render';
|
|
@@ -11,6 +12,7 @@ import { parseSite } from '../site/vitePlugin';
|
|
|
11
12
|
/**
|
|
12
13
|
* Turns each `pages/**\/*.md` into a module whose default export is a `Page`, at build time,
|
|
13
14
|
* so the browser gets finished HTML and never runs the markdown tools.
|
|
15
|
+
* With `?tags`, the module's default export is a `PageTags` instead, so the tag pages don't load every page's HTML.
|
|
14
16
|
* Bad frontmatter, or a feature's bad value, fails the build; in dev it shows Vite's error screen.
|
|
15
17
|
*/
|
|
16
18
|
export function markdownPages(): Plugin {
|
|
@@ -23,16 +25,23 @@ export function markdownPages(): Plugin {
|
|
|
23
25
|
root = config.root;
|
|
24
26
|
},
|
|
25
27
|
transform(markdown, id) {
|
|
26
|
-
const
|
|
28
|
+
const [filePath, query] = id.split('?');
|
|
29
|
+
const file = path.relative(root, filePath);
|
|
27
30
|
if (!file.startsWith(`pages${path.sep}`) || !file.endsWith('.md')) return;
|
|
28
31
|
const { frontmatter, raw, body } = parseFrontmatter(file, markdown);
|
|
29
32
|
|
|
33
|
+
if (new URLSearchParams(query).has('tags')) {
|
|
34
|
+
const { title, description } = frontmatter;
|
|
35
|
+
const page: PageTags = { title, description, tags: FEATURE_FIELDS.tags.parse(raw.tags ?? '') };
|
|
36
|
+
return { code: `export default ${JSON.stringify(page)};`, map: null };
|
|
37
|
+
}
|
|
38
|
+
|
|
30
39
|
// Features read `site.yml` for the keys a page leaves out, so editing it rebuilds every page.
|
|
31
40
|
const siteFile = path.join(root, 'site.yml');
|
|
32
41
|
this.addWatchFile(siteFile);
|
|
33
42
|
const site = parseSite('site.yml', fs.readFileSync(siteFile, 'utf8'));
|
|
34
43
|
|
|
35
|
-
const
|
|
44
|
+
const readFile = (from: string, mdPath: string) => {
|
|
36
45
|
const target = path.resolve(root, path.dirname(from), mdPath);
|
|
37
46
|
const relative = path.relative(root, target);
|
|
38
47
|
if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
|
|
@@ -41,10 +50,10 @@ export function markdownPages(): Plugin {
|
|
|
41
50
|
const shown = relative.split(path.sep).join('/');
|
|
42
51
|
if (!fs.existsSync(target)) throw new Error(`file ${shown} does not exist`);
|
|
43
52
|
this.addWatchFile(target);
|
|
44
|
-
return
|
|
53
|
+
return parseFrontmatter(shown, fs.readFileSync(target, 'utf8')).body;
|
|
45
54
|
};
|
|
46
55
|
|
|
47
|
-
const { data, extensions } = buildFeatures(file, raw, site,
|
|
56
|
+
const { data, extensions } = buildFeatures(file, raw, site, readFile);
|
|
48
57
|
const page: Page = { frontmatter, html: renderMarkdown(body, extensions), features: data };
|
|
49
58
|
return { code: `export default ${JSON.stringify(page)};`, map: null };
|
|
50
59
|
},
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
import { useParams } from '@solidjs/router';
|
|
2
|
+
import { HttpStatusCode } from '@solidjs/start';
|
|
3
|
+
import { For, Show } from 'solid-js';
|
|
4
|
+
import { PageMeta } from '~/components/PageMeta';
|
|
5
|
+
import { PageTitle } from '~/components/PageTitle';
|
|
6
|
+
import { tagAt } from '~/lib/markdown/features/tags/pages';
|
|
7
|
+
import { TAGS_URL } from '~/lib/markdown/features/tags/url';
|
|
8
|
+
|
|
9
|
+
export default function Tag() {
|
|
10
|
+
const params = useParams();
|
|
11
|
+
|
|
12
|
+
return (
|
|
13
|
+
<Show
|
|
14
|
+
when={tagAt(params.tag ?? '')}
|
|
15
|
+
keyed
|
|
16
|
+
fallback={
|
|
17
|
+
<main>
|
|
18
|
+
<PageTitle>Page Not Found</PageTitle>
|
|
19
|
+
<HttpStatusCode code={404} />
|
|
20
|
+
<h1>Page Not Found</h1>
|
|
21
|
+
</main>
|
|
22
|
+
}
|
|
23
|
+
>
|
|
24
|
+
{({ tag, pages }) => (
|
|
25
|
+
<main>
|
|
26
|
+
<PageMeta title={`#${tag}`} />
|
|
27
|
+
<h1>#{tag}</h1>
|
|
28
|
+
<ul>
|
|
29
|
+
<For each={pages}>
|
|
30
|
+
{page => (
|
|
31
|
+
<li>
|
|
32
|
+
<a href={`/${page.slug}`}>{page.title}</a>
|
|
33
|
+
<Show when={page.description}>
|
|
34
|
+
<p class="tagged-description">{page.description}</p>
|
|
35
|
+
</Show>
|
|
36
|
+
</li>
|
|
37
|
+
)}
|
|
38
|
+
</For>
|
|
39
|
+
</ul>
|
|
40
|
+
<p>
|
|
41
|
+
<a href={TAGS_URL}>All tags</a>
|
|
42
|
+
</p>
|
|
43
|
+
</main>
|
|
44
|
+
)}
|
|
45
|
+
</Show>
|
|
46
|
+
);
|
|
47
|
+
}
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
import { For } from 'solid-js';
|
|
2
|
+
import { PageMeta } from '~/components/PageMeta';
|
|
3
|
+
import { allTags } from '~/lib/markdown/features/tags/pages';
|
|
4
|
+
import { tagUrl } from '~/lib/markdown/features/tags/url';
|
|
5
|
+
|
|
6
|
+
export default function Tags() {
|
|
7
|
+
return (
|
|
8
|
+
<main>
|
|
9
|
+
<PageMeta title="Tags" />
|
|
10
|
+
<h1>Tags</h1>
|
|
11
|
+
<ul>
|
|
12
|
+
<For each={allTags}>
|
|
13
|
+
{({ tag, pages }) => (
|
|
14
|
+
<li>
|
|
15
|
+
<a href={tagUrl(tag)}>#{tag}</a> ({pages.length})
|
|
16
|
+
</li>
|
|
17
|
+
)}
|
|
18
|
+
</For>
|
|
19
|
+
</ul>
|
|
20
|
+
</main>
|
|
21
|
+
);
|
|
22
|
+
}
|