@tinyvolt/pie 0.2.0 → 0.5.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 +8 -0
- package/init/index.js +4 -0
- package/init/postinstall.js +38 -0
- package/init/site-agents.md +18 -5
- package/package.json +4 -2
- package/pages/_topics.md +7 -0
- package/pages/about.md +1 -0
- package/pages/example.md +37 -3
- package/pages/python-editor.md +47 -16
- package/public/logo.svg +1 -1
- package/src/app.css +129 -0
- package/src/lib/markdown/features/build.ts +73 -0
- package/src/lib/markdown/features/sidebar/View.tsx +56 -0
- package/src/lib/markdown/features/sidebar/build.ts +8 -0
- package/src/lib/markdown/features/toc/build.ts +71 -0
- package/src/lib/markdown/features/views.tsx +20 -0
- package/src/lib/markdown/frontmatter.ts +28 -3
- package/src/lib/markdown/pages.ts +4 -1
- package/src/lib/markdown/render.ts +37 -5
- package/src/lib/markdown/vitePlugin.ts +27 -4
- package/src/lib/nodes/animation.ts +47 -0
- package/src/lib/nodes/components/CenteredGrid.tsx +15 -2
- package/src/lib/nodes/components/NodeCanvas.tsx +7 -1
- package/src/lib/nodes/execute.ts +5 -2
- package/src/lib/nodes/functions/Node2NodeFunc.ts +3 -2
- package/src/lib/nodes/functions/sideEffects.ts +11 -22
- package/src/lib/nodes/state/NodeStore.ts +27 -1
- package/src/lib/python/lift.ts +87 -0
- package/src/lib/python/py/pie.py +24 -1
- package/src/lib/python/runner.ts +22 -3
- package/src/lib/python/worker.ts +8 -1
- package/src/lib/site/vitePlugin.ts +3 -0
- package/src/routes/[...slug].tsx +4 -2
- package/styles/theme.css +3 -0
package/README.md
CHANGED
|
@@ -35,6 +35,14 @@ The site installs the app as the `@tinyvolt/pie` package. To update it:
|
|
|
35
35
|
npm install @tinyvolt/pie@latest
|
|
36
36
|
```
|
|
37
37
|
|
|
38
|
+
With pnpm:
|
|
39
|
+
|
|
40
|
+
```sh
|
|
41
|
+
pnpm add @tinyvolt/pie@latest
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
Updating also refreshes the site's `AGENTS.md` and `vite.config.ts`. If either differs from the new version, the old one is saved as `AGENTS.old.md` or `vite.config.old.ts`. Copy back anything you want to keep.
|
|
45
|
+
|
|
38
46
|
Requires Node 24. Package: [@tinyvolt/pie](https://www.npmjs.com/package/@tinyvolt/pie).
|
|
39
47
|
|
|
40
48
|
## Developing pie-ssg
|
package/init/index.js
CHANGED
|
@@ -74,8 +74,12 @@ const pkg = {
|
|
|
74
74
|
dependencies: { [app.name]: app.version, ...app.peerDependencies },
|
|
75
75
|
devDependencies: { '@types/node': app.devDependencies['@types/node'], typescript: app.devDependencies.typescript },
|
|
76
76
|
engines: app.engines,
|
|
77
|
+
// npm blocks dependencies' install scripts unless allowed. This lets `init/postinstall.js` refresh files on upgrade.
|
|
78
|
+
allowScripts: { [app.name]: true },
|
|
77
79
|
};
|
|
78
80
|
fs.writeFileSync(path.join(target, 'package.json'), JSON.stringify(pkg, null, 2) + '\n');
|
|
81
|
+
// The same for pnpm.
|
|
82
|
+
fs.writeFileSync(path.join(target, 'pnpm-workspace.yaml'), `allowBuilds:\n "${app.name}": true\n`);
|
|
79
83
|
|
|
80
84
|
const usesPnpm = (process.env.npm_config_user_agent ?? '').startsWith('pnpm');
|
|
81
85
|
console.log(`
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
// Runs after a site installs or upgrades `@tinyvolt/pie`: refreshes the files below from this version.
|
|
2
|
+
// A changed file is first backed up, so a user's edits are kept.
|
|
3
|
+
import fs from 'node:fs';
|
|
4
|
+
import path from 'node:path';
|
|
5
|
+
|
|
6
|
+
const root = path.resolve(import.meta.dirname, '..');
|
|
7
|
+
|
|
8
|
+
// Package path -> [path in the site, backup path in the site].
|
|
9
|
+
const FILES = {
|
|
10
|
+
'init/site-agents.md': ['AGENTS.md', 'AGENTS.old.md'],
|
|
11
|
+
'init/site-vite.config.ts': ['vite.config.ts', 'vite.config.old.ts'],
|
|
12
|
+
};
|
|
13
|
+
|
|
14
|
+
/** The folder of the nearest `package.json` at or above `dir`, or null. */
|
|
15
|
+
function findProject(dir) {
|
|
16
|
+
for (let d = dir; ; d = path.dirname(d)) {
|
|
17
|
+
if (fs.existsSync(path.join(d, 'package.json'))) return d;
|
|
18
|
+
if (d === path.dirname(d)) return null;
|
|
19
|
+
}
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
// `INIT_CWD` is where the install command was run. Skip anything that isn't a site depending on this package,
|
|
23
|
+
// such as this repo's own `pnpm install` or a one-off `npx @tinyvolt/pie init`.
|
|
24
|
+
const app = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
|
|
25
|
+
const site = process.env.INIT_CWD && findProject(process.env.INIT_CWD);
|
|
26
|
+
const sitePkg = site && JSON.parse(fs.readFileSync(path.join(site, 'package.json'), 'utf8'));
|
|
27
|
+
if (!sitePkg?.dependencies?.[app.name] && !sitePkg?.devDependencies?.[app.name]) process.exit(0);
|
|
28
|
+
|
|
29
|
+
for (const [from, [to, backup]] of Object.entries(FILES)) {
|
|
30
|
+
const target = path.join(site, to);
|
|
31
|
+
// A file the user removed stays removed.
|
|
32
|
+
if (!fs.existsSync(target)) continue;
|
|
33
|
+
const fresh = fs.readFileSync(path.join(root, from));
|
|
34
|
+
if (fresh.equals(fs.readFileSync(target))) continue;
|
|
35
|
+
fs.copyFileSync(target, path.join(site, backup));
|
|
36
|
+
fs.writeFileSync(target, fresh);
|
|
37
|
+
console.log(`@tinyvolt/pie: updated ${to}; the old one is in ${backup}.`);
|
|
38
|
+
}
|
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`. |
|
|
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. |
|
|
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
|
| `layouts/` | Optional overrides: `header.tsx` (top of every page) and `index.tsx` (homepage, `/`). |
|
|
@@ -34,10 +34,11 @@ Flat `key: value` lines. Values may be quoted. A key may appear only once.
|
|
|
34
34
|
- `title` (required): shown in the header and in every browser tab title.
|
|
35
35
|
- `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.
|
|
36
36
|
- `description`: shown in search results and link previews for a page with no `description` of its own.
|
|
37
|
+
- `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`.
|
|
37
38
|
|
|
38
39
|
## Pages
|
|
39
40
|
|
|
40
|
-
A page is a `.md` file under `pages/`. `/pages` lists every page.
|
|
41
|
+
A page is a `.md` file under `pages/`. `/pages` lists every page. A file whose name starts with `_` is not a page: it gets no URL and isn't listed.
|
|
41
42
|
|
|
42
43
|
Optional frontmatter at the very top, as flat `key: value` lines:
|
|
43
44
|
|
|
@@ -51,6 +52,11 @@ canvas: left
|
|
|
51
52
|
- `title`: the tab title. Empty means the tab shows the site title alone.
|
|
52
53
|
- `description`: shown in search results and link previews. Empty means `site.yml`'s `description`.
|
|
53
54
|
- `canvas`: `left`, `right`, `top`, `bottom` or `none` (default). Adds a canvas on that side of the page.
|
|
55
|
+
- `sidebar`: a `.md` file shown in a collapsible sidebar on the left, e.g. `sidebar: _topics.md`. The path is relative to the page's file. `none`: no sidebar, even when `site.yml` sets one. Left out: `site.yml`'s `sidebar`.
|
|
56
|
+
- It starts collapsed. A button opens it, and the rest of the page shrinks to make room. A new page starts with it collapsed.
|
|
57
|
+
- 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.
|
|
58
|
+
- 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".
|
|
59
|
+
- `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`.
|
|
54
60
|
|
|
55
61
|
Other keys are ignored. A bad value fails the build, and shows an error screen in dev.
|
|
56
62
|
|
|
@@ -71,7 +77,7 @@ pie.circle(a, r)
|
|
|
71
77
|
````
|
|
72
78
|
|
|
73
79
|
- Python runs in the browser with Pyodide 0.28.2. `pie` is already imported.
|
|
74
|
-
- All editors on one page share the same Python variables and the same canvas.
|
|
80
|
+
- All editors on one page share the same Python variables and the same canvas. Editors in the page's sidebar are separate: see `sidebar` under "Pages".
|
|
75
81
|
- `import numpy`, `scipy`, `matplotlib` and other [Pyodide packages](https://pyodide.org/en/0.28.2/usage/packages-in-pyodide.html) load on first use.
|
|
76
82
|
- `plt.show()` shows matplotlib figures under the editor.
|
|
77
83
|
- `` ```python-editor collapsed `` starts the editor collapsed: only its toolbar shows until the reader expands it. Other words after `python-editor` are ignored.
|
|
@@ -94,7 +100,10 @@ Common mistake: `center = pie.point(1, 2)` does not give the node the id `center
|
|
|
94
100
|
- Every node the call makes gets the colors, including extra nodes such as the center point of `ellipse_from_foci`.
|
|
95
101
|
- A node shows only the colors its render function draws with. A point uses only `fill`, a line only `stroke`. For `partial`'s arrow, `stroke` colors the line and `fill` the head.
|
|
96
102
|
|
|
97
|
-
|
|
103
|
+
There are three system nodes:
|
|
104
|
+
- `unit`: a scalar holding the pixels per grid unit (default 50). Changing it changes the grid unit, e.g. `pie.scalar(80, out='unit')`.
|
|
105
|
+
- `gridOpacity`: a scalar that multiplies the opacity of the grid lines and axes (default 1; 0 hides them), e.g. `pie.scalar(0.5, out='gridOpacity')`.
|
|
106
|
+
- `canvasColor`: a text holding a CSS color for the canvas background (default `''`: no background), e.g. `pie.text('#111', out='canvasColor')`.
|
|
98
107
|
|
|
99
108
|
Built-in functions:
|
|
100
109
|
|
|
@@ -122,7 +131,7 @@ These change existing nodes instead of making a new one. They run once, when cal
|
|
|
122
131
|
|
|
123
132
|
| Call | Does |
|
|
124
133
|
| --- | --- |
|
|
125
|
-
| `pie.clear()` | removes every node and resets `unit` (pixels per grid unit) to 50 |
|
|
134
|
+
| `pie.clear()` | removes every node and resets the system nodes: `unit` (pixels per grid unit) to 50, `gridOpacity` to 1, `canvasColor` to `''` |
|
|
126
135
|
| `pie.translate_point_to(p, x, y)` | moves point `p` to (x, y) |
|
|
127
136
|
| `pie.translate_point_by(p, dx, dy)` | moves point `p` by (dx, dy) |
|
|
128
137
|
| `pie.translate_scalar_to(s, value)` | sets scalar `s` to `value` |
|
|
@@ -244,11 +253,15 @@ Each must `export default` a Solid component (Solid JSX: `class`, not `className
|
|
|
244
253
|
|
|
245
254
|
Change the CSS variables in `styles/theme.css` (colors, fonts, text width), or add rules, e.g. `main h1 { color: crimson; }`.
|
|
246
255
|
|
|
256
|
+
- 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`.
|
|
257
|
+
- Table of contents: `.toc`.
|
|
258
|
+
|
|
247
259
|
## Build checks
|
|
248
260
|
|
|
249
261
|
`npm run build` fails, with a message naming the file, when:
|
|
250
262
|
|
|
251
263
|
- a page's frontmatter or `site.yml` has a bad line or value, or `site.yml` has no `title`
|
|
264
|
+
- a `sidebar` file doesn't exist or is outside the project
|
|
252
265
|
- a page's URL matches a route in `node_modules/@tinyvolt/pie/src/routes/`
|
|
253
266
|
- a `functions/` keyword is used twice
|
|
254
267
|
- a `nodes/` type name is used twice
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@tinyvolt/pie",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.5.0",
|
|
4
4
|
"description": "A Markdown-based SSG for interactive science explainers. Create a site with: npx @tinyvolt/pie init my-site",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"repository": {
|
|
@@ -30,7 +30,8 @@
|
|
|
30
30
|
"dev": "vite dev",
|
|
31
31
|
"build": "vite build",
|
|
32
32
|
"start": "node .output/server/index.mjs",
|
|
33
|
-
"preview": "vite preview"
|
|
33
|
+
"preview": "vite preview",
|
|
34
|
+
"postinstall": "node init/postinstall.js"
|
|
34
35
|
},
|
|
35
36
|
"dependencies": {
|
|
36
37
|
"@codemirror/lang-python": "6.2.1",
|
|
@@ -40,6 +41,7 @@
|
|
|
40
41
|
"@solidjs/router": "1.0.0",
|
|
41
42
|
"@solidjs/start": "2.0.6",
|
|
42
43
|
"codemirror": "6.0.2",
|
|
44
|
+
"@lezer/highlight": "1.2.5",
|
|
43
45
|
"katex": "0.19.0",
|
|
44
46
|
"marked": "18.1.1",
|
|
45
47
|
"nitro": "3.0.260610-beta"
|
package/pages/_topics.md
ADDED
package/pages/about.md
CHANGED
package/pages/example.md
CHANGED
|
@@ -1,7 +1,41 @@
|
|
|
1
1
|
---
|
|
2
|
-
|
|
2
|
+
toc: true
|
|
3
|
+
sidebar: _topics.md
|
|
3
4
|
---
|
|
5
|
+
# Table of contents test
|
|
4
6
|
|
|
5
|
-
|
|
7
|
+
### Before any h2
|
|
6
8
|
|
|
7
|
-
|
|
9
|
+
Should be a top-level entry.
|
|
10
|
+
|
|
11
|
+
## The $\nabla$ operator
|
|
12
|
+
|
|
13
|
+
Math in a heading.
|
|
14
|
+
|
|
15
|
+
### Sub *one*
|
|
16
|
+
|
|
17
|
+
Nested under the operator.
|
|
18
|
+
|
|
19
|
+
### Sub two
|
|
20
|
+
|
|
21
|
+
Also nested.
|
|
22
|
+
|
|
23
|
+
## Repeat
|
|
24
|
+
|
|
25
|
+
First "Repeat", links to `#repeat`.
|
|
26
|
+
|
|
27
|
+
## Repeat
|
|
28
|
+
|
|
29
|
+
Second "Repeat", links to `#repeat-2`.
|
|
30
|
+
|
|
31
|
+
#### Deep
|
|
32
|
+
|
|
33
|
+
Not listed: only `##` and `###` are.
|
|
34
|
+
|
|
35
|
+
## Last
|
|
36
|
+
|
|
37
|
+
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
|
|
38
|
+
|
|
39
|
+
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
|
|
40
|
+
|
|
41
|
+
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
|
package/pages/python-editor.md
CHANGED
|
@@ -1,29 +1,60 @@
|
|
|
1
1
|
---
|
|
2
|
-
|
|
3
|
-
canvas: left
|
|
2
|
+
canvas: right
|
|
4
3
|
---
|
|
5
|
-
# Python editor
|
|
6
4
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
5
|
+
# Examples of animating lifted functions
|
|
6
|
+
|
|
7
|
+
1. One lifted function. The point should trace a sine curve, not jump to the end.
|
|
8
|
+
|
|
9
|
+
```python-editor
|
|
10
|
+
import math
|
|
11
|
+
def wave(t):
|
|
12
|
+
return (t, 2 * math.sin(t))
|
|
13
|
+
wave_point = pie.lift(wave, pie.Point)
|
|
14
|
+
t = pie.scalar(0, out='t')
|
|
15
|
+
wave_point(t)
|
|
16
|
+
pie.translate_scalar_to(t, 6, animate=True)
|
|
11
17
|
```
|
|
12
18
|
|
|
13
|
-
|
|
19
|
+
2. Change `t` after the animation. The point should jump to (1, 1.68) through a normal rerun.
|
|
14
20
|
|
|
15
|
-
|
|
21
|
+
```python-editor
|
|
22
|
+
pie.scalar(1, out='t')
|
|
23
|
+
```
|
|
16
24
|
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
25
|
+
3. Two lifted functions, one feeding the other. The point should slide from (0, 1) to (6, 1).
|
|
26
|
+
|
|
27
|
+
```python-editor
|
|
28
|
+
def double(x):
|
|
29
|
+
return 2 * x
|
|
30
|
+
def on_line(x):
|
|
31
|
+
return (x, 1)
|
|
32
|
+
double_l = pie.lift(double, pie.Scalar)
|
|
33
|
+
on_line_l = pie.lift(on_line, pie.Point)
|
|
34
|
+
s = pie.scalar(0, out='s')
|
|
35
|
+
on_line_l(double_l(s))
|
|
36
|
+
pie.translate_scalar_to(s, 3, animate=True)
|
|
21
37
|
```
|
|
22
38
|
|
|
39
|
+
4. A lifted function that returns an array. Five points should spread out smoothly from [0, 1] to [0, 5].
|
|
40
|
+
|
|
23
41
|
```python-editor
|
|
24
|
-
|
|
42
|
+
import numpy as np
|
|
43
|
+
linspace = pie.lift(np.linspace, pie.Array[pie.Scalar])
|
|
44
|
+
n = pie.scalar(1, out='n')
|
|
45
|
+
pie.point(linspace(0, n, 5), -2)
|
|
46
|
+
pie.translate_scalar_to(n, 5, animate=True)
|
|
25
47
|
```
|
|
26
48
|
|
|
49
|
+
5. A lifted function that fails partway. The point should move until x = 2 and then stop. The console should show one error: `fails_above_2: ValueError: too big`.
|
|
50
|
+
|
|
27
51
|
```python-editor
|
|
28
|
-
|
|
29
|
-
|
|
52
|
+
def fails_above_2(x):
|
|
53
|
+
if x > 2:
|
|
54
|
+
raise ValueError("too big")
|
|
55
|
+
return (x, -1)
|
|
56
|
+
fails_l = pie.lift(fails_above_2, pie.Point)
|
|
57
|
+
u = pie.scalar(0, out='u')
|
|
58
|
+
fails_l(u)
|
|
59
|
+
pie.translate_scalar_to(u, 4, animate=True)
|
|
60
|
+
```
|
package/public/logo.svg
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0
|
|
1
|
+
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 21 64 45" width="256" height="180">
|
|
2
2
|
<path d="M32 29 L8 29 A24 24 0 0 0 20 49.78 Z" fill="#41DBC9"/>
|
|
3
3
|
<path d="M32 29 L44 49.78 A24 24 0 0 0 56 29 Z" fill="#41DBC9"/>
|
|
4
4
|
<path d="M32 34 L20 54.78 A24 24 0 0 0 44 54.78 Z" fill="#0B6B73"/>
|
package/src/app.css
CHANGED
|
@@ -128,6 +128,22 @@ main pre code {
|
|
|
128
128
|
background: none;
|
|
129
129
|
}
|
|
130
130
|
|
|
131
|
+
/* ```python tokens. Same colors as the editor's default theme. */
|
|
132
|
+
.tok-keyword { color: #708; }
|
|
133
|
+
.tok-atom, .tok-bool { color: #219; }
|
|
134
|
+
.tok-literal, .tok-number { color: #164; }
|
|
135
|
+
.tok-string { color: #a11; }
|
|
136
|
+
.tok-string2 { color: #e40; }
|
|
137
|
+
.tok-variableName.tok-definition { color: #00f; }
|
|
138
|
+
.tok-variableName.tok-local { color: #30a; }
|
|
139
|
+
.tok-typeName, .tok-namespace { color: #085; }
|
|
140
|
+
.tok-className { color: #167; }
|
|
141
|
+
.tok-variableName2, .tok-macroName { color: #256; }
|
|
142
|
+
.tok-propertyName.tok-definition { color: #00c; }
|
|
143
|
+
.tok-comment { color: #940; }
|
|
144
|
+
.tok-meta { color: #404740; }
|
|
145
|
+
.tok-invalid { color: #f00; }
|
|
146
|
+
|
|
131
147
|
main table {
|
|
132
148
|
border-collapse: collapse;
|
|
133
149
|
}
|
|
@@ -253,6 +269,119 @@ main .katex-display {
|
|
|
253
269
|
height: 100%;
|
|
254
270
|
}
|
|
255
271
|
|
|
272
|
+
/* A page with a sidebar: the sidebar, a line with its button, then the page. */
|
|
273
|
+
.sidebar-page {
|
|
274
|
+
display: flex;
|
|
275
|
+
flex: 1 1 auto;
|
|
276
|
+
min-height: 0;
|
|
277
|
+
}
|
|
278
|
+
|
|
279
|
+
/* Collapsed: hidden with CSS so its editors keep their code. Open: stays in view while the page scrolls. */
|
|
280
|
+
.sidebar {
|
|
281
|
+
display: none;
|
|
282
|
+
flex: 0 0 var(--sidebar-width, 16rem);
|
|
283
|
+
box-sizing: border-box;
|
|
284
|
+
position: sticky;
|
|
285
|
+
top: 0;
|
|
286
|
+
align-self: flex-start;
|
|
287
|
+
max-height: 100dvh;
|
|
288
|
+
overflow-y: auto;
|
|
289
|
+
}
|
|
290
|
+
|
|
291
|
+
.sidebar-page--open .sidebar {
|
|
292
|
+
display: block;
|
|
293
|
+
}
|
|
294
|
+
|
|
295
|
+
/* A canvas page doesn't scroll, so the sidebar fills its height and scrolls on its own. */
|
|
296
|
+
#app:has(.canvas-page) .sidebar {
|
|
297
|
+
align-self: stretch;
|
|
298
|
+
max-height: none;
|
|
299
|
+
}
|
|
300
|
+
|
|
301
|
+
.sidebar-text {
|
|
302
|
+
padding: 1rem 1.25rem 2rem;
|
|
303
|
+
}
|
|
304
|
+
|
|
305
|
+
.sidebar-edge {
|
|
306
|
+
position: relative;
|
|
307
|
+
z-index: 5;
|
|
308
|
+
flex: 0 0 1px;
|
|
309
|
+
background: var(--color-border, #ddd);
|
|
310
|
+
}
|
|
311
|
+
|
|
312
|
+
.sidebar-toggle {
|
|
313
|
+
position: sticky;
|
|
314
|
+
top: 0.75rem;
|
|
315
|
+
display: flex;
|
|
316
|
+
align-items: center;
|
|
317
|
+
justify-content: center;
|
|
318
|
+
width: 1.5rem;
|
|
319
|
+
height: 1.5rem;
|
|
320
|
+
margin-top: 0.75rem;
|
|
321
|
+
padding: 0;
|
|
322
|
+
background: var(--color-bg, #fff);
|
|
323
|
+
border: 1px solid var(--color-border, #ddd);
|
|
324
|
+
border-radius: 50%;
|
|
325
|
+
color: var(--color-subtle, #666);
|
|
326
|
+
cursor: pointer;
|
|
327
|
+
}
|
|
328
|
+
|
|
329
|
+
.sidebar-toggle:hover {
|
|
330
|
+
color: var(--color-hover, #000);
|
|
331
|
+
border-color: var(--color-border-hover, #999);
|
|
332
|
+
}
|
|
333
|
+
|
|
334
|
+
/* Fills the rest; a canvas page inside fills its height. */
|
|
335
|
+
.sidebar-page-content {
|
|
336
|
+
display: flex;
|
|
337
|
+
flex-direction: column;
|
|
338
|
+
flex: 1 1 0;
|
|
339
|
+
min-width: 0;
|
|
340
|
+
}
|
|
341
|
+
|
|
342
|
+
/* Narrow screens: the open sidebar covers the page, over a dimmed backdrop. */
|
|
343
|
+
.sidebar-page--drawer .sidebar {
|
|
344
|
+
position: fixed;
|
|
345
|
+
top: 0;
|
|
346
|
+
bottom: 0;
|
|
347
|
+
left: 0;
|
|
348
|
+
z-index: 20;
|
|
349
|
+
width: min(var(--sidebar-width, 16rem), 85vw);
|
|
350
|
+
max-height: none;
|
|
351
|
+
background: var(--color-bg, #fff);
|
|
352
|
+
box-shadow: 0 0 1rem rgb(0 0 0 / 0.2);
|
|
353
|
+
}
|
|
354
|
+
|
|
355
|
+
.sidebar-backdrop {
|
|
356
|
+
position: fixed;
|
|
357
|
+
inset: 0;
|
|
358
|
+
z-index: 19;
|
|
359
|
+
background: var(--color-backdrop, rgb(0 0 0 / 0.3));
|
|
360
|
+
}
|
|
361
|
+
|
|
362
|
+
/* `toc: true`: the table of contents, a box at the start of the page's text. */
|
|
363
|
+
.toc {
|
|
364
|
+
margin: 0 0 1.5rem;
|
|
365
|
+
padding: 0.75rem 1rem;
|
|
366
|
+
border: 1px solid var(--color-border, #ddd);
|
|
367
|
+
border-radius: 4px;
|
|
368
|
+
font-size: 0.95em;
|
|
369
|
+
}
|
|
370
|
+
|
|
371
|
+
.toc ul {
|
|
372
|
+
margin: 0;
|
|
373
|
+
padding-left: 1.25rem;
|
|
374
|
+
}
|
|
375
|
+
|
|
376
|
+
.toc a {
|
|
377
|
+
text-decoration: none;
|
|
378
|
+
}
|
|
379
|
+
|
|
380
|
+
.toc a:hover {
|
|
381
|
+
color: var(--color-hover, #000);
|
|
382
|
+
text-decoration: underline;
|
|
383
|
+
}
|
|
384
|
+
|
|
256
385
|
/* Hidden until MarkdownBody swaps it for the editor; keeps its space so the text below doesn't jump. */
|
|
257
386
|
pre:has(> code.language-python-editor) {
|
|
258
387
|
visibility: hidden;
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A feature is an optional extra that a page turns on in its frontmatter, e.g. `sidebar: _topics.md`.
|
|
3
|
+
* If the page leaves the key out, the value in `site.yml` is used.
|
|
4
|
+
*
|
|
5
|
+
* Each feature has two halves:
|
|
6
|
+
* - Build half (this file). Runs in Node when the site is generated. Its `build` turns the frontmatter value
|
|
7
|
+
* into data, e.g. the path `_topics.md` into that file's HTML. The data is saved in the page's JSON.
|
|
8
|
+
* - View half (`views.tsx`). Runs in the browser. A component that gets that data and wraps the page,
|
|
9
|
+
* e.g. draws the sidebar next to it.
|
|
10
|
+
*
|
|
11
|
+
* To add a feature: add its build half to `FEATURES` below, and its view, if it has one, to `VIEWS` in `views.tsx`.
|
|
12
|
+
* A feature that only changes the page's HTML, like `toc`, has no view.
|
|
13
|
+
*/
|
|
14
|
+
import type { MarkedExtension } from 'marked';
|
|
15
|
+
import type { Field } from '../frontmatter';
|
|
16
|
+
import { sidebar } from './sidebar/build';
|
|
17
|
+
import { toc } from './toc/build';
|
|
18
|
+
|
|
19
|
+
/** The second argument to a feature's `build`. */
|
|
20
|
+
export interface BuildContext {
|
|
21
|
+
/** The page, e.g. `pages/about.md`. */
|
|
22
|
+
file: string;
|
|
23
|
+
/** The file that set the value: the page, or `site.yml`. */
|
|
24
|
+
from: string;
|
|
25
|
+
/** The HTML of the `.md` file at `path`, relative to the folder of `from`. Throws if it's missing or outside the project. */
|
|
26
|
+
renderFile(path: string): string;
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
/** A feature's build half. `T`: its frontmatter value. `D`: the data its view gets. */
|
|
30
|
+
export interface FeatureBuild<T, D> {
|
|
31
|
+
field: Field<T>;
|
|
32
|
+
/** Returns `undefined` to turn the feature off on this page. */
|
|
33
|
+
build(value: T, ctx: BuildContext): D | undefined;
|
|
34
|
+
/** Extra markdown syntax for this page. */
|
|
35
|
+
markdown?(data: D): MarkedExtension;
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
/** Keyed by frontmatter key. */
|
|
39
|
+
const FEATURES = { sidebar, toc };
|
|
40
|
+
|
|
41
|
+
type DataOf<F> = F extends FeatureBuild<any, infer D> ? D : never;
|
|
42
|
+
|
|
43
|
+
// Today: `{ sidebar?: string; toc?: true }`.
|
|
44
|
+
export type FeatureData = { [K in keyof typeof FEATURES]?: DataOf<(typeof FEATURES)[K]> };
|
|
45
|
+
|
|
46
|
+
// Today: `{ sidebar: sidebar.field, toc: toc.field }`. `site.yml` reads these too.
|
|
47
|
+
export const FEATURE_FIELDS = Object.fromEntries(
|
|
48
|
+
Object.entries(FEATURES).map(([key, feature]) => [key, feature.field]),
|
|
49
|
+
) as { [K in keyof typeof FEATURES]: (typeof FEATURES)[K]['field'] };
|
|
50
|
+
|
|
51
|
+
/** Runs every feature's `build` for the page `file`. Throws, naming the file and key, on a bad value. */
|
|
52
|
+
export function buildFeatures(
|
|
53
|
+
file: string,
|
|
54
|
+
raw: Record<string, string>,
|
|
55
|
+
site: Record<string, unknown>,
|
|
56
|
+
renderFile: (from: string, path: string) => string,
|
|
57
|
+
): { data: FeatureData; extensions: MarkedExtension[] } {
|
|
58
|
+
const data: Record<string, unknown> = {};
|
|
59
|
+
const extensions: MarkedExtension[] = [];
|
|
60
|
+
for (const [key, feature] of Object.entries(FEATURES) as [string, FeatureBuild<unknown, unknown>][]) {
|
|
61
|
+
const from = Object.hasOwn(raw, key) ? file : 'site.yml';
|
|
62
|
+
try {
|
|
63
|
+
const value = from === file ? feature.field.parse(raw[key]) : site[key];
|
|
64
|
+
const built = feature.build(value, { file, from, renderFile: path => renderFile(from, path) });
|
|
65
|
+
if (built === undefined) continue;
|
|
66
|
+
data[key] = built;
|
|
67
|
+
if (feature.markdown) extensions.push(feature.markdown(built));
|
|
68
|
+
} catch (e) {
|
|
69
|
+
throw new Error(`${from}: \`${key}\` ${(e as Error).message}`);
|
|
70
|
+
}
|
|
71
|
+
}
|
|
72
|
+
return { data: data as FeatureData, extensions };
|
|
73
|
+
}
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
import { createSignal, onCleanup, onMount, Show, type JSX } from 'solid-js';
|
|
2
|
+
import { Chevron } from '~/components/icons';
|
|
3
|
+
import { MarkdownBody } from '../../components/MarkdownBody';
|
|
4
|
+
|
|
5
|
+
// Used when `theme.css` doesn't set `--sidebar-drawer-below`.
|
|
6
|
+
const DRAWER_BELOW = '768px';
|
|
7
|
+
|
|
8
|
+
/**
|
|
9
|
+
* `children` with a sidebar on the left showing `data`, the sidebar file's HTML. It starts collapsed; opening it squeezes `children`.
|
|
10
|
+
* On screens narrower than `--sidebar-drawer-below`, it opens over the page instead,
|
|
11
|
+
* and a tap outside it or on one of its links closes it.
|
|
12
|
+
* Its Python editors share variables only with each other, and have no canvas.
|
|
13
|
+
*/
|
|
14
|
+
export function SidebarView(props: { data: string; children: JSX.Element }) {
|
|
15
|
+
const [open, setOpen] = createSignal(false);
|
|
16
|
+
const [drawer, setDrawer] = createSignal(false);
|
|
17
|
+
|
|
18
|
+
onMount(() => {
|
|
19
|
+
const below = getComputedStyle(document.documentElement).getPropertyValue('--sidebar-drawer-below').trim() || DRAWER_BELOW;
|
|
20
|
+
const query = matchMedia(`(width < ${below})`);
|
|
21
|
+
const update = () => setDrawer(query.matches);
|
|
22
|
+
update();
|
|
23
|
+
query.addEventListener('change', update);
|
|
24
|
+
onCleanup(() => query.removeEventListener('change', update));
|
|
25
|
+
});
|
|
26
|
+
|
|
27
|
+
// In the drawer, following a link closes it, even a link to a place on this page.
|
|
28
|
+
const closeOnLink = (e: MouseEvent) => {
|
|
29
|
+
if (drawer() && (e.target as Element).closest('a')) setOpen(false);
|
|
30
|
+
};
|
|
31
|
+
const label = () => (open() ? 'Hide sidebar' : 'Show sidebar');
|
|
32
|
+
|
|
33
|
+
return (
|
|
34
|
+
<div class="sidebar-page" classList={{ 'sidebar-page--open': open(), 'sidebar-page--drawer': drawer() }}>
|
|
35
|
+
<aside id="sidebar" class="sidebar" onClick={closeOnLink}>
|
|
36
|
+
<MarkdownBody class="sidebar-text" html={props.data} />
|
|
37
|
+
</aside>
|
|
38
|
+
<div class="sidebar-edge">
|
|
39
|
+
<button
|
|
40
|
+
class="sidebar-toggle"
|
|
41
|
+
onClick={() => setOpen(!open())}
|
|
42
|
+
aria-expanded={open()}
|
|
43
|
+
aria-controls="sidebar"
|
|
44
|
+
aria-label={label()}
|
|
45
|
+
title={label()}
|
|
46
|
+
>
|
|
47
|
+
<Chevron direction={open() ? 'left' : 'right'} />
|
|
48
|
+
</button>
|
|
49
|
+
</div>
|
|
50
|
+
<Show when={drawer() && open()}>
|
|
51
|
+
<div class="sidebar-backdrop" onClick={() => setOpen(false)} />
|
|
52
|
+
</Show>
|
|
53
|
+
<div class="sidebar-page-content">{props.children}</div>
|
|
54
|
+
</div>
|
|
55
|
+
);
|
|
56
|
+
}
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
import { markdownFile } from '../../frontmatter';
|
|
2
|
+
import type { FeatureBuild } from '../build';
|
|
3
|
+
|
|
4
|
+
/** `sidebar: _topics.md`: that file's HTML, shown in a sidebar. `none`: no sidebar, even when `site.yml` sets one. */
|
|
5
|
+
export const sidebar: FeatureBuild<string, string> = {
|
|
6
|
+
field: markdownFile(),
|
|
7
|
+
build: (file, ctx) => (file === '' || file === 'none' ? undefined : ctx.renderFile(file)),
|
|
8
|
+
};
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
import type { MarkedExtension } from 'marked';
|
|
2
|
+
import { boolean } from '../../frontmatter';
|
|
3
|
+
import type { FeatureBuild } from '../build';
|
|
4
|
+
|
|
5
|
+
/** Heading levels listed: `##` and `###`. */
|
|
6
|
+
const LEVELS = [2, 3];
|
|
7
|
+
|
|
8
|
+
interface Entry {
|
|
9
|
+
depth: number;
|
|
10
|
+
id: string;
|
|
11
|
+
/** The heading's text as HTML, e.g. with its math rendered. */
|
|
12
|
+
html: string;
|
|
13
|
+
}
|
|
14
|
+
|
|
15
|
+
/** `The $\nabla$ operator` -> `the-nabla-operator`. */
|
|
16
|
+
function slug(text: string): string {
|
|
17
|
+
return text.toLowerCase().replace(/[^\p{L}\p{N}\s-]/gu, '').trim().replace(/\s+/g, '-') || 'section';
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
/** The entries as a list. Each `###` is nested under the `##` before it; a `###` before any `##` stands on its own. */
|
|
21
|
+
function tocHtml(entries: Entry[]): string {
|
|
22
|
+
const groups: { entry: Entry; children: Entry[] }[] = [];
|
|
23
|
+
for (const entry of entries) {
|
|
24
|
+
const last = groups.at(-1);
|
|
25
|
+
if (entry.depth === 3 && last?.entry.depth === 2) last.children.push(entry);
|
|
26
|
+
else groups.push({ entry, children: [] });
|
|
27
|
+
}
|
|
28
|
+
const link = (e: Entry) => `<a href="#${e.id}">${e.html}</a>`;
|
|
29
|
+
const items = groups.map(({ entry, children }) => {
|
|
30
|
+
const sublist = children.length === 0 ? '' : `<ul>${children.map(c => `<li>${link(c)}</li>`).join('')}</ul>`;
|
|
31
|
+
return `<li>${link(entry)}${sublist}</li>`;
|
|
32
|
+
});
|
|
33
|
+
return `<nav class="toc"><ul>${items.join('')}</ul></nav>\n`;
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
/**
|
|
37
|
+
* `toc: true`: a table of contents of the page's `##` and `###` headings, after its leading `#` title,
|
|
38
|
+
* or at the very start if the page doesn't begin with one. Every heading gets an `id` to link to.
|
|
39
|
+
* No list when the page has no such heading.
|
|
40
|
+
*/
|
|
41
|
+
export const toc: FeatureBuild<boolean, true> = {
|
|
42
|
+
field: boolean(false),
|
|
43
|
+
build: on => (on ? true : undefined),
|
|
44
|
+
// The list is made while the page renders, from the headings as they're rendered, so each entry's text
|
|
45
|
+
// and `id` match its heading's.
|
|
46
|
+
markdown() {
|
|
47
|
+
const entries: Entry[] = [];
|
|
48
|
+
const used = new Map<string, number>();
|
|
49
|
+
return {
|
|
50
|
+
renderer: {
|
|
51
|
+
heading(token) {
|
|
52
|
+
const base = slug(token.text);
|
|
53
|
+
const count = (used.get(base) ?? 0) + 1;
|
|
54
|
+
used.set(base, count);
|
|
55
|
+
const id = count === 1 ? base : `${base}-${count}`;
|
|
56
|
+
const html = this.parser.parseInline(token.tokens);
|
|
57
|
+
if (LEVELS.includes(token.depth)) entries.push({ depth: token.depth, id, html });
|
|
58
|
+
return `<h${token.depth} id="${id}">${html}</h${token.depth}>\n`;
|
|
59
|
+
},
|
|
60
|
+
},
|
|
61
|
+
hooks: {
|
|
62
|
+
postprocess(html) {
|
|
63
|
+
if (entries.length === 0) return html;
|
|
64
|
+
const title = /^\s*<h1[\s>][\s\S]*?<\/h1>\n?/.exec(html);
|
|
65
|
+
const at = title ? title[0].length : 0;
|
|
66
|
+
return html.slice(0, at) + tocHtml(entries) + html.slice(at);
|
|
67
|
+
},
|
|
68
|
+
},
|
|
69
|
+
} satisfies MarkedExtension;
|
|
70
|
+
},
|
|
71
|
+
};
|