docpensieve 0.1.4 → 0.1.5
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 +5 -5
- package/src/commands/init.js +7 -0
- package/starter/03-reference/02-configuration.md +27 -0
- package/starter/03-reference/04-theme.md +1 -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
package/README.md
CHANGED
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "docpensieve",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.5",
|
|
4
4
|
"description": "DocPensieve command-line interface (init, build, check, dev, serve)",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "MIT",
|
|
@@ -24,10 +24,10 @@
|
|
|
24
24
|
"types"
|
|
25
25
|
],
|
|
26
26
|
"dependencies": {
|
|
27
|
-
"@docpensieve/components": "0.1.
|
|
28
|
-
"@docpensieve/core": "0.1.
|
|
29
|
-
"@docpensieve/shared": "0.1.
|
|
30
|
-
"@docpensieve/theme": "0.1.
|
|
27
|
+
"@docpensieve/components": "0.1.5",
|
|
28
|
+
"@docpensieve/core": "0.1.5",
|
|
29
|
+
"@docpensieve/shared": "0.1.5",
|
|
30
|
+
"@docpensieve/theme": "0.1.5",
|
|
31
31
|
"chalk": "^6.0.0",
|
|
32
32
|
"chokidar": "^5.0.0",
|
|
33
33
|
"commander": "^15.0.0"
|
package/src/commands/init.js
CHANGED
|
@@ -204,6 +204,13 @@ function renderConfig({ name, theme, siteUrl, version }) {
|
|
|
204
204
|
siteUrl ? ` siteUrl: ${quote(siteUrl)},` : " // siteUrl: 'https://example.com/my-project',",
|
|
205
205
|
" // baseUrl: '/my-project/', // only to depart from the path of siteUrl",
|
|
206
206
|
'',
|
|
207
|
+
' // Images, from the project root. logo: beside the name, in the header;',
|
|
208
|
+
' // favicon: the browser tab (.ico, .png or .svg); socialImage: the preview',
|
|
209
|
+
' // of a shared page, 1200 × 630 pixels as a rule — it needs siteUrl.',
|
|
210
|
+
" // logo: 'branding/logo.png',",
|
|
211
|
+
" // favicon: 'branding/favicon.png',",
|
|
212
|
+
" // socialImage: 'branding/social.png',",
|
|
213
|
+
'',
|
|
207
214
|
' // Language of the pages, in <html lang>. The labels of the page shell',
|
|
208
215
|
' // stay in English.',
|
|
209
216
|
" lang: 'en',",
|
|
@@ -62,6 +62,30 @@ can change.
|
|
|
62
62
|
| `scrollToTop` | `true` | Back-to-top button on every page |
|
|
63
63
|
| `jsonld` | `{ enabled: true }` | Structured data |
|
|
64
64
|
| `lang` | `'en'` | Language of the document, in `<html lang>`. The shell's labels stay English |
|
|
65
|
+
| `logo` | `''` | Image beside the project name, in the header |
|
|
66
|
+
| `favicon` | `''` | Icon of the browser tab: `.ico`, `.png` or `.svg` |
|
|
67
|
+
| `socialImage` | `''` | Preview of a shared page. Needs `siteUrl` |
|
|
68
|
+
|
|
69
|
+
## Images
|
|
70
|
+
|
|
71
|
+
```js
|
|
72
|
+
logo: 'branding/logo.png',
|
|
73
|
+
favicon: 'branding/favicon.png',
|
|
74
|
+
socialImage: 'branding/social.png',
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
The paths start from the project root. Each image is copied into every
|
|
78
|
+
version, under `assets/`, so that a version stays whole on its own branch.
|
|
79
|
+
|
|
80
|
+
- `logo` sits beside the project name, at the height of the header's text: a
|
|
81
|
+
square image reads best there. Its `alt` stays empty, since the name follows
|
|
82
|
+
it. It is also the logo of the organisation in the structured data.
|
|
83
|
+
- `favicon` is the icon of the browser tab: `.ico`, `.png` or `.svg`.
|
|
84
|
+
- `socialImage` is what a social network shows of a shared page, with its
|
|
85
|
+
title and description. 1200 × 630 pixels is the usual size, and SVG is not
|
|
86
|
+
read there. Those networks only read an absolute address, hence `siteUrl`.
|
|
87
|
+
|
|
88
|
+
A declared image that does not exist stops the build, naming the field.
|
|
65
89
|
|
|
66
90
|
## `versions`
|
|
67
91
|
|
|
@@ -127,6 +151,9 @@ internal link: if it is wrong, every link is.
|
|
|
127
151
|
| Several `current` versions | The list of those found |
|
|
128
152
|
| Unknown `framework` | The accepted values |
|
|
129
153
|
| Requested slug not found | The available slugs |
|
|
154
|
+
| An image of the wrong kind | The accepted extensions |
|
|
155
|
+
| `socialImage` without `siteUrl` | Why the address is needed |
|
|
156
|
+
| A declared image that is missing | The field and its path |
|
|
130
157
|
|
|
131
158
|
Each one stops the build with a message and a hint, without a stack trace.
|
|
132
159
|
|
|
@@ -76,6 +76,7 @@ the `dp-*` class below.
|
|
|
76
76
|
| `skip` | `dp-skip` | Skip link to the content |
|
|
77
77
|
| `header` | `dp-header` | Site header |
|
|
78
78
|
| `brand` | `dp-brand` | Project name, in the header |
|
|
79
|
+
| `brandLogo` | `dp-brand-logo` | Logo beside the project name |
|
|
79
80
|
| `versions` | `dp-versions` | Version switcher |
|
|
80
81
|
| `versionsList` | `dp-versions-list` | Open list of the switcher |
|
|
81
82
|
| `shell` | `dp-shell` | Menu / content / table of contents grid |
|
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>
|