docpensieve 0.1.4 → 0.2.0-beta.1
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 +4 -0
- package/package.json +6 -6
- package/src/commands/init.js +27 -2
- package/starter/01-guide/03-writing-pages.md +30 -0
- package/starter/01-guide/06-deployment.md +11 -0
- package/starter/02-components/01-card.mdx +2 -2
- package/starter/02-components/04-tooltip.mdx +1 -1
- package/starter/02-components/08-logo-icon.mdx +2 -2
- package/starter/02-components/index.mdx +2 -1
- package/starter/03-reference/02-configuration.md +135 -28
- package/starter/03-reference/04-theme.md +9 -7
- package/starter/03-reference/05-api.md +1033 -0
- package/starter/04-architecture.md +3 -2
- package/starter/05-whats-new.md +73 -0
- package/starter/06-migrating.md +53 -0
- package/starter/icons/blocks.svg +0 -6
- package/starter/icons/book.svg +0 -4
- package/starter/icons/branch.svg +0 -6
- package/starter/icons/compass.svg +0 -4
- package/starter/icons/lightning.svg +0 -3
- package/starter/icons/list.svg +0 -4
- package/starter/icons/shield.svg +0 -4
- package/starter/icons/star.svg +0 -3
- package/starter/index.mdx +0 -244
|
@@ -36,8 +36,9 @@ utility theme needs to know which classes were actually used.
|
|
|
36
36
|
|
|
37
37
|
## React does not leave the build
|
|
38
38
|
|
|
39
|
-
Components are rendered to HTML during the build.
|
|
40
|
-
runtime: what reaches the reader is markup and a stylesheet.
|
|
39
|
+
Components are rendered to HTML during the build. Content pages load no
|
|
40
|
+
runtime: what reaches the reader is markup and a stylesheet. The search page
|
|
41
|
+
alone adds a script, of a few kilobytes, to filter its list.
|
|
41
42
|
|
|
42
43
|
That explains the shape of the shipped components. None of them has state or
|
|
43
44
|
an event listener, because there would be nothing to bring them to life.
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: What's new in 0.2
|
|
3
|
+
description: What the 0.2 brings, what it is still to bring, and what it changes for a 0.1 project.
|
|
4
|
+
tags: [release]
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# What's new in 0.2
|
|
8
|
+
|
|
9
|
+
This version is **in preparation**. Its betas go out under the npm tag `beta`,
|
|
10
|
+
while the version installed by default stays the 0.1, documented in the 0.1
|
|
11
|
+
pages of this site:
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
npx docpensieve@beta init my-site
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
What follows describes the 0.2 as it stands, and
|
|
18
|
+
[Moving from 0.1 to 0.2](./migrating/) says what to check in a 0.1 project.
|
|
19
|
+
|
|
20
|
+
## Already there
|
|
21
|
+
|
|
22
|
+
### A menu written by hand
|
|
23
|
+
|
|
24
|
+
`sidebar: 'sidebar.json'` replaces the menu derived from the file tree with
|
|
25
|
+
one you describe — pages in the order you want, categories, links outside the
|
|
26
|
+
site. Each version reads its own file, since each has its own pages. A section
|
|
27
|
+
can keep its automatic menu with a single entry, which is how the DocPensieve
|
|
28
|
+
section stays whole without listing its pages.
|
|
29
|
+
|
|
30
|
+
See [Writing the menu by hand](./guide/writing-pages/) in the guide, and the
|
|
31
|
+
[`sidebar` field](./reference/configuration/) in the reference.
|
|
32
|
+
|
|
33
|
+
### Search engines and feed readers
|
|
34
|
+
|
|
35
|
+
With `siteUrl` set, the build writes `sitemap.xml` for search engines — and
|
|
36
|
+
`robots.txt` when the site sits at the root of its domain. `feed: true` adds an
|
|
37
|
+
RSS feed of the dated pages. See [Sitemap and feed](./reference/configuration/)
|
|
38
|
+
in the reference.
|
|
39
|
+
|
|
40
|
+
### Search
|
|
41
|
+
|
|
42
|
+
A search field in the header, and a search page in each version. The index is
|
|
43
|
+
built with the site; content pages still load no script — the search page
|
|
44
|
+
alone does, and without it the page stays the list of every page. See
|
|
45
|
+
[Search](./reference/configuration/) in the reference.
|
|
46
|
+
|
|
47
|
+
### A colour scheme of your choosing, and a logo per version
|
|
48
|
+
|
|
49
|
+
`theme.darkMode: 'dark'` keeps the site dark whatever the reader's system —
|
|
50
|
+
`'light'` keeps it light; `'class'`, the default, still follows the system.
|
|
51
|
+
Until now the field was accepted and did nothing. A version can also carry its
|
|
52
|
+
own `logo` and `favicon`, to tell a beta apart at a glance. See the
|
|
53
|
+
[configuration reference](./reference/configuration/).
|
|
54
|
+
|
|
55
|
+
### Lighter pages
|
|
56
|
+
|
|
57
|
+
The stylesheet reaches the reader minified. Every image of a page gets its
|
|
58
|
+
width and height, read from its file, so that the text no longer jumps when it
|
|
59
|
+
arrives; all but the first load lazily, and are no longer preloaded — the
|
|
60
|
+
first, often in view, keeps its normal loading. `CardImage` loads lazily too.
|
|
61
|
+
|
|
62
|
+
### The API reference, and two example projects
|
|
63
|
+
|
|
64
|
+
Every export of the five packages is in the [API reference](./reference/api/),
|
|
65
|
+
generated from the JSDoc of the sources, so that it cannot drift from the code.
|
|
66
|
+
The repository also holds two complete example projects, one per theme, built
|
|
67
|
+
and checked on every run of its tests.
|
|
68
|
+
|
|
69
|
+
## For a 0.1 project
|
|
70
|
+
|
|
71
|
+
Nothing to change: a 0.1 configuration builds as it is. `sidebar: 'auto'`
|
|
72
|
+
stays the default, and every new field is optional. A guide to moving from
|
|
73
|
+
0.1 to 0.2 will come with the release.
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Moving from 0.1 to 0.2
|
|
3
|
+
description: What the 0.2 changes on its own, what to check, and what to turn on.
|
|
4
|
+
tags: [release, migration]
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Moving from 0.1 to 0.2
|
|
8
|
+
|
|
9
|
+
A 0.1 project builds with the 0.2 as it is: every new field is optional.
|
|
10
|
+
A few things change on their own, though, and deserve a look.
|
|
11
|
+
|
|
12
|
+
## Update
|
|
13
|
+
|
|
14
|
+
```bash
|
|
15
|
+
npm install docpensieve@beta # while the 0.2 is in beta
|
|
16
|
+
npm install docpensieve@latest # once it is released
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
Through `npx` alone, `npx docpensieve@beta` runs the beta.
|
|
20
|
+
|
|
21
|
+
## What changes on its own
|
|
22
|
+
|
|
23
|
+
| What | In 0.2 |
|
|
24
|
+
| ---------------- | ------------------------------------------------------------------------------ |
|
|
25
|
+
| Search | A field in the header, and a page at `/search/` in each version |
|
|
26
|
+
| `sitemap.xml` | Written at the root of the site as soon as `siteUrl` is set |
|
|
27
|
+
| `robots.txt` | Written with it, when the site is served at the root of its domain |
|
|
28
|
+
| The stylesheet | Minified |
|
|
29
|
+
| Images | Their width and height are written; all but the first of a page load lazily |
|
|
30
|
+
| `theme.darkMode` | Now read: `'dark'` and `'light'` keep one scheme, `'class'` follows the system |
|
|
31
|
+
|
|
32
|
+
Content pages still load no script: the search page alone does.
|
|
33
|
+
|
|
34
|
+
## What to check
|
|
35
|
+
|
|
36
|
+
- **A page of yours at `/search/`** now stops the build: that address is the
|
|
37
|
+
search page's. Rename your page, or set `search: false`.
|
|
38
|
+
- **`theme.darkMode`** was accepted and ignored in 0.1. A value other than
|
|
39
|
+
`'class'` now takes effect — and an unknown one stops the build.
|
|
40
|
+
- **Your own `robots.txt`**, if you published one next to the site, is now
|
|
41
|
+
written by the build when the site sits at the root of its domain. Set
|
|
42
|
+
`sitemap: false` to keep yours.
|
|
43
|
+
|
|
44
|
+
## What to turn on
|
|
45
|
+
|
|
46
|
+
| Field | Gives |
|
|
47
|
+
| ---------------------------- | ------------------------------------------------------------- |
|
|
48
|
+
| `sidebar: 'sidebar.json'` | A menu written by hand, in each version's folder |
|
|
49
|
+
| `feed: true` | An RSS feed of the pages that carry a `date` |
|
|
50
|
+
| `versions[].logo`, `favicon` | A logo and a favicon of the version's own — a beta told apart |
|
|
51
|
+
| `search: false` | No search at all, if the site does not need one |
|
|
52
|
+
|
|
53
|
+
Every field is in the [configuration reference](./reference/configuration/).
|
package/starter/icons/blocks.svg
DELETED
|
@@ -1,6 +0,0 @@
|
|
|
1
|
-
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round">
|
|
2
|
-
<rect x="3" y="3" width="7.5" height="7.5" rx="1.5" />
|
|
3
|
-
<rect x="13.5" y="3" width="7.5" height="7.5" rx="1.5" />
|
|
4
|
-
<rect x="3" y="13.5" width="7.5" height="7.5" rx="1.5" />
|
|
5
|
-
<rect x="13.5" y="13.5" width="7.5" height="7.5" rx="1.5" />
|
|
6
|
-
</svg>
|
package/starter/icons/book.svg
DELETED
|
@@ -1,4 +0,0 @@
|
|
|
1
|
-
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
|
|
2
|
-
<path d="M4 19.5A2.5 2.5 0 0 1 6.5 17H20" />
|
|
3
|
-
<path d="M6.5 2H20v20H6.5A2.5 2.5 0 0 1 4 19.5v-15A2.5 2.5 0 0 1 6.5 2z" />
|
|
4
|
-
</svg>
|
package/starter/icons/branch.svg
DELETED
|
@@ -1,6 +0,0 @@
|
|
|
1
|
-
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round">
|
|
2
|
-
<circle cx="6" cy="5" r="2.5" />
|
|
3
|
-
<circle cx="6" cy="19" r="2.5" />
|
|
4
|
-
<circle cx="18" cy="12" r="2.5" />
|
|
5
|
-
<path d="M6 7.5v9M8.5 5h5a4 4 0 0 1 4 4v.5" />
|
|
6
|
-
</svg>
|
package/starter/icons/list.svg
DELETED
package/starter/icons/shield.svg
DELETED
package/starter/icons/star.svg
DELETED
package/starter/index.mdx
DELETED
|
@@ -1,244 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
title: DocPensieve
|
|
3
|
-
description: Static documentation site generator — Markdown and MDX in, runtime-free HTML out, one version per branch.
|
|
4
|
-
layout: home
|
|
5
|
-
authors: [Valentin Chevoleau]
|
|
6
|
-
date: 2026-09-09
|
|
7
|
-
tags: [home]
|
|
8
|
-
draft: false
|
|
9
|
-
|
|
10
|
-
jsonld:
|
|
11
|
-
type: TechArticle
|
|
12
|
-
breadcrumbs: false
|
|
13
|
-
---
|
|
14
|
-
|
|
15
|
-
<div className="dp-hero">
|
|
16
|
-
|
|
17
|
-
# DocPensieve
|
|
18
|
-
|
|
19
|
-
Your Markdown and MDX files become a static site. No runtime to load, one version per branch, structured data derived from the frontmatter.
|
|
20
|
-
|
|
21
|
-
<div className="dp-actions">
|
|
22
|
-
|
|
23
|
-
[Get started](/guide/installation/) [See the components](/components/)
|
|
24
|
-
|
|
25
|
-
</div>
|
|
26
|
-
|
|
27
|
-
</div>
|
|
28
|
-
|
|
29
|
-
<Columns>
|
|
30
|
-
<Column>
|
|
31
|
-
<Card className="h-full" href="/guide/">
|
|
32
|
-
<CardBody className="text-sm text-slate-600 dark:text-slate-400">
|
|
33
|
-
<LogoIcon src="./icons/compass.svg" size="1.75rem" className="text-indigo-600" />
|
|
34
|
-
<strong className="block mt-3 mb-1 text-base font-semibold">Guide</strong>
|
|
35
|
-
|
|
36
|
-
From installation to deployment, in order.
|
|
37
|
-
</CardBody>
|
|
38
|
-
</Card>
|
|
39
|
-
|
|
40
|
-
</Column>
|
|
41
|
-
<Column>
|
|
42
|
-
<Card className="h-full" href="/components/">
|
|
43
|
-
<CardBody className="text-sm text-slate-600 dark:text-slate-400">
|
|
44
|
-
<LogoIcon src="./icons/blocks.svg" size="1.75rem" className="text-indigo-600" />
|
|
45
|
-
<strong className="block mt-3 mb-1 text-base font-semibold">Components</strong>
|
|
46
|
-
|
|
47
|
-
Eight components usable without an import, none of them with JavaScript.
|
|
48
|
-
</CardBody>
|
|
49
|
-
</Card>
|
|
50
|
-
|
|
51
|
-
</Column>
|
|
52
|
-
<Column>
|
|
53
|
-
<Card className="h-full" href="/reference/">
|
|
54
|
-
<CardBody className="text-sm text-slate-600 dark:text-slate-400">
|
|
55
|
-
<LogoIcon src="./icons/list.svg" size="1.75rem" className="text-indigo-600" />
|
|
56
|
-
<strong className="block mt-3 mb-1 text-base font-semibold">Reference</strong>
|
|
57
|
-
|
|
58
|
-
Commands, configuration, frontmatter and theme.
|
|
59
|
-
</CardBody>
|
|
60
|
-
</Card>
|
|
61
|
-
|
|
62
|
-
</Column>
|
|
63
|
-
<Column>
|
|
64
|
-
<Card className="h-full" href="/architecture/">
|
|
65
|
-
<CardBody className="text-sm text-slate-600 dark:text-slate-400">
|
|
66
|
-
<LogoIcon src="./icons/branch.svg" size="1.75rem" className="text-indigo-600" />
|
|
67
|
-
<strong className="block mt-3 mb-1 text-base font-semibold">Architecture</strong>
|
|
68
|
-
|
|
69
|
-
How a page becomes HTML, and why it works that way.
|
|
70
|
-
</CardBody>
|
|
71
|
-
</Card>
|
|
72
|
-
|
|
73
|
-
</Column>
|
|
74
|
-
</Columns>
|
|
75
|
-
|
|
76
|
-
## In three commands
|
|
77
|
-
|
|
78
|
-
<Columns>
|
|
79
|
-
<Column span={7}>
|
|
80
|
-
|
|
81
|
-
```bash
|
|
82
|
-
npx docpensieve init my-site
|
|
83
|
-
cd my-site
|
|
84
|
-
npx docpensieve dev
|
|
85
|
-
```
|
|
86
|
-
|
|
87
|
-
The first one sets up a configuration and a documentation folder, the last one
|
|
88
|
-
opens a server that rebuilds on every save.
|
|
89
|
-
|
|
90
|
-
Nothing else to install: the <Tooltip text="Turning the sources into HTML pages ready to serve.">build</Tooltip> runs on your machine, and the produced site only needs a file host.
|
|
91
|
-
|
|
92
|
-
</Column>
|
|
93
|
-
<Column span={5}>
|
|
94
|
-
<Card className="h-full">
|
|
95
|
-
<CardHeader>What you get</CardHeader>
|
|
96
|
-
<CardBody>
|
|
97
|
-
<Tree>
|
|
98
|
-
<TreeItem label="dist" open>
|
|
99
|
-
<TreeItem label="index.html" />
|
|
100
|
-
<TreeItem label="versions.json" />
|
|
101
|
-
<TreeItem label="versions" open>
|
|
102
|
-
<TreeItem label="v1.0">
|
|
103
|
-
<TreeItem label="index.html" />
|
|
104
|
-
<TreeItem label="assets" />
|
|
105
|
-
</TreeItem>
|
|
106
|
-
</TreeItem>
|
|
107
|
-
</TreeItem>
|
|
108
|
-
</Tree>
|
|
109
|
-
</CardBody>
|
|
110
|
-
</Card>
|
|
111
|
-
</Column>
|
|
112
|
-
</Columns>
|
|
113
|
-
|
|
114
|
-
## What it costs the reader
|
|
115
|
-
|
|
116
|
-
<div className="flex flex-wrap justify-center gap-6 my-8">
|
|
117
|
-
<Skill
|
|
118
|
-
name="JavaScript"
|
|
119
|
-
level={0}
|
|
120
|
-
shape="circle"
|
|
121
|
-
color="#10b981"
|
|
122
|
-
icon={<LogoIcon src="./icons/lightning.svg" />}
|
|
123
|
-
/>
|
|
124
|
-
<Skill
|
|
125
|
-
name="Hydration"
|
|
126
|
-
level={0}
|
|
127
|
-
shape="circle"
|
|
128
|
-
color="#10b981"
|
|
129
|
-
icon={<LogoIcon src="./icons/lightning.svg" />}
|
|
130
|
-
/>
|
|
131
|
-
<Skill
|
|
132
|
-
name="HTML served as is"
|
|
133
|
-
level={100}
|
|
134
|
-
shape="circle"
|
|
135
|
-
color="#6366f1"
|
|
136
|
-
icon={<LogoIcon src="./icons/shield.svg" />}
|
|
137
|
-
/>
|
|
138
|
-
<Skill
|
|
139
|
-
name="One stylesheet per version"
|
|
140
|
-
level={100}
|
|
141
|
-
shape="circle"
|
|
142
|
-
color="#6366f1"
|
|
143
|
-
icon={<LogoIcon src="./icons/book.svg" />}
|
|
144
|
-
/>
|
|
145
|
-
</div>
|
|
146
|
-
|
|
147
|
-
Two dials at zero, and that is on purpose: React serves the **build**, not the
|
|
148
|
-
display. What reaches the reader is markup and a stylesheet.
|
|
149
|
-
|
|
150
|
-
## What sets the tool apart
|
|
151
|
-
|
|
152
|
-
<Columns>
|
|
153
|
-
<Column span={6}>
|
|
154
|
-
<Card className="h-full">
|
|
155
|
-
<CardHeader>Nothing to load</CardHeader>
|
|
156
|
-
<CardBody className="text-sm">
|
|
157
|
-
No hydration, no bundle to download before reading. A page stays readable in ten years,
|
|
158
|
-
because there is nothing that can stop working.
|
|
159
|
-
</CardBody>
|
|
160
|
-
</Card>
|
|
161
|
-
</Column>
|
|
162
|
-
<Column span={6}>
|
|
163
|
-
<Card className="h-full">
|
|
164
|
-
<CardHeader>One version per branch</CardHeader>
|
|
165
|
-
<CardBody className="text-sm">
|
|
166
|
-
Each published version lives on its own orphan branch, with its history. Going back to an
|
|
167
|
-
old version does not require rebuilding it.
|
|
168
|
-
</CardBody>
|
|
169
|
-
</Card>
|
|
170
|
-
</Column>
|
|
171
|
-
<Column span={6}>
|
|
172
|
-
<Card className="h-full">
|
|
173
|
-
<CardHeader>The frontmatter is enough</CardHeader>
|
|
174
|
-
<CardBody className="text-sm">
|
|
175
|
-
Title, description, authors and dates produce the JSON-LD, the breadcrumb and the metadata.
|
|
176
|
-
Nothing to write twice.
|
|
177
|
-
</CardBody>
|
|
178
|
-
</Card>
|
|
179
|
-
</Column>
|
|
180
|
-
<Column span={6}>
|
|
181
|
-
<Card className="h-full">
|
|
182
|
-
<CardHeader>Nothing fails silently</CardHeader>
|
|
183
|
-
<CardBody className="text-sm">
|
|
184
|
-
An unknown value, a missing parent, a dead link: each one stops the build with a message and
|
|
185
|
-
a hint.
|
|
186
|
-
</CardBody>
|
|
187
|
-
</Card>
|
|
188
|
-
</Column>
|
|
189
|
-
</Columns>
|
|
190
|
-
|
|
191
|
-
## Quality, in figures
|
|
192
|
-
|
|
193
|
-
<Columns>
|
|
194
|
-
<Column span={7}>
|
|
195
|
-
|
|
196
|
-
These gauges are not decorative: they are the repository's own measurements,
|
|
197
|
-
taken by hand — nothing updates them on its own. <Tooltip text="Share of lines executed by the test suite.">Coverage</Tooltip> and <Tooltip text="TypeScript checks the JSDoc of the source code and of the tests.">typing</Tooltip> are checked on every push.
|
|
198
|
-
|
|
199
|
-
What is not measured does not improve — and what is not checked every time
|
|
200
|
-
degrades.
|
|
201
|
-
|
|
202
|
-
</Column>
|
|
203
|
-
<Column span={5}>
|
|
204
|
-
<Skill name="Line coverage" level={97} color="#10b981" icon={<LogoIcon src="./icons/shield.svg" />} />
|
|
205
|
-
<Skill name="Branch coverage" level={87} color="#f59e0b" icon={<LogoIcon src="./icons/shield.svg" />} />
|
|
206
|
-
<Skill name="Typing of code and tests" level={100} color="#6366f1" icon={<LogoIcon src="./icons/star.svg" />} />
|
|
207
|
-
</Column>
|
|
208
|
-
</Columns>
|
|
209
|
-
|
|
210
|
-
## A page, end to end
|
|
211
|
-
|
|
212
|
-
<Columns>
|
|
213
|
-
<Column span={5}>
|
|
214
|
-
|
|
215
|
-
```mdx
|
|
216
|
-
---
|
|
217
|
-
title: Installation
|
|
218
|
-
description: Install the tool.
|
|
219
|
-
---
|
|
220
|
-
|
|
221
|
-
# Installation
|
|
222
|
-
|
|
223
|
-
Node.js 22 or later.
|
|
224
|
-
|
|
225
|
-
<Tooltip text="Complete new project">init</Tooltip>
|
|
226
|
-
sets up the configuration.
|
|
227
|
-
```
|
|
228
|
-
|
|
229
|
-
</Column>
|
|
230
|
-
<Column span={7}>
|
|
231
|
-
|
|
232
|
-
The file is read, its frontmatter detached, its content compiled to HTML.
|
|
233
|
-
Components are rendered **at build time**: `Tooltip` becomes two elements and a
|
|
234
|
-
style rule, without a line of script.
|
|
235
|
-
|
|
236
|
-
The title feeds the `<title>` tag, the description the metadata, and both
|
|
237
|
-
together the JSON-LD. The file name gives the URL, its folder the place in the
|
|
238
|
-
menu.
|
|
239
|
-
|
|
240
|
-
None of this needs configuration: [writing a page](/guide/writing-pages/) is
|
|
241
|
-
enough.
|
|
242
|
-
|
|
243
|
-
</Column>
|
|
244
|
-
</Columns>
|