docpensieve 0.4.0-beta.2 → 0.4.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/bin/docpensieve.js +5 -2
- package/package.json +5 -5
- package/src/commands/build.js +9 -1
- package/src/commands/dev.js +9 -1
- package/src/commands/init.js +19 -3
- package/starter/01-guide/01-installation.md +2 -3
- package/starter/01-guide/02-first-site.md +7 -1
- package/starter/01-guide/03-writing-pages.md +4 -0
- package/starter/01-guide/04-versions.md +4 -0
- package/starter/01-guide/05-themes.mdx +47 -13
- package/starter/01-guide/07-migrate-from-0-3.md +125 -0
- package/starter/01-guide/08-navigation.mdx +12 -0
- package/starter/01-guide/09-when-it-breaks.md +176 -0
- package/starter/01-guide/10-languages.md +160 -0
- package/starter/02-components/01-card.mdx +2 -2
- package/starter/02-components/02-columns.mdx +3 -0
- package/starter/02-components/03-time-timer.mdx +4 -0
- package/starter/02-components/04-tooltip.mdx +40 -0
- package/starter/02-components/05-tree.mdx +4 -0
- package/starter/02-components/06-scroll-to-top.mdx +3 -0
- package/starter/02-components/07-skill.mdx +30 -0
- package/starter/02-components/08-logo-icon.mdx +24 -0
- package/starter/02-components/09-for-theme.mdx +3 -0
- package/starter/02-components/11-menu.mdx +129 -0
- package/starter/02-components/12-admonition.mdx +154 -0
- package/starter/03-reference/02-configuration.md +50 -32
- package/starter/03-reference/03-frontmatter.md +3 -0
- package/starter/03-reference/04-theme.md +80 -69
- package/starter/03-reference/05-api.md +158 -12
- package/starter/03-reference/index.mdx +3 -0
- package/starter/04-architecture.md +3 -0
- package/starter/05-whats-new.md +73 -19
- package/starter/examples.css +15 -0
- package/starter/01-guide/07-migrate-to-beta.md +0 -27
|
@@ -49,28 +49,31 @@ can change.
|
|
|
49
49
|
|
|
50
50
|
## The fields
|
|
51
51
|
|
|
52
|
-
| Field | Default | Effect
|
|
53
|
-
| ------------------ | ------------------- |
|
|
54
|
-
| `projectName` | `'Documentation'` | Name shown in the header and in the JSON-LD
|
|
55
|
-
| `siteUrl` | `''` | Public URL. Used for the `canonical` and the JSON-LD
|
|
56
|
-
| `baseUrl` | `'/'` | Deployment prefix. Derived from `siteUrl` when omitted
|
|
57
|
-
| `outDir` | `'dist'` | Output folder, relative to the root
|
|
58
|
-
| `versions` | `[]` | At least one entry
|
|
59
|
-
| `theme` | see below | Styling
|
|
60
|
-
| `sidebar` | `'auto'` | `'auto'`: the menu follows the file tree. Or a `.json` file of each version folder
|
|
61
|
-
| `authors` | `''` | A `.json` file describing the authors, in each version folder that has one
|
|
62
|
-
| `headerLinks` | `[]` | Links of the header, beside the version switcher
|
|
63
|
-
| `foldedSidebar` | `false` | Categories of the menu fold, opened where the reader stands
|
|
64
|
-
| `
|
|
65
|
-
| `
|
|
66
|
-
| `
|
|
67
|
-
| `
|
|
68
|
-
| `
|
|
69
|
-
| `
|
|
70
|
-
| `
|
|
71
|
-
| `
|
|
72
|
-
| `
|
|
73
|
-
| `
|
|
52
|
+
| Field | Default | Effect |
|
|
53
|
+
| ------------------ | ------------------- | -------------------------------------------------------------------------------------------------- |
|
|
54
|
+
| `projectName` | `'Documentation'` | Name shown in the header and in the JSON-LD |
|
|
55
|
+
| `siteUrl` | `''` | Public URL. Used for the `canonical` and the JSON-LD |
|
|
56
|
+
| `baseUrl` | `'/'` | Deployment prefix. Derived from `siteUrl` when omitted |
|
|
57
|
+
| `outDir` | `'dist'` | Output folder, relative to the root |
|
|
58
|
+
| `versions` | `[]` | At least one entry |
|
|
59
|
+
| `theme` | see below | Styling |
|
|
60
|
+
| `sidebar` | `'auto'` | `'auto'`: the menu follows the file tree. Or a `.json` file of each version folder |
|
|
61
|
+
| `authors` | `''` | A `.json` file describing the authors, in each version folder that has one |
|
|
62
|
+
| `headerLinks` | `[]` | Links of the header, beside the version switcher |
|
|
63
|
+
| `foldedSidebar` | `false` | Categories of the menu fold, opened where the reader stands |
|
|
64
|
+
| `admonitions` | `{}` | Kinds of admonition the project adds to the six shipped, each a label, a tone and an optional icon |
|
|
65
|
+
| `stickyHeader` | `true` | The header stays at the top of the screen; `false` lets it scroll away |
|
|
66
|
+
| `globalComponents` | `true` | Shipped components available without an import |
|
|
67
|
+
| `scrollToTop` | `true` | Back-to-top button on every page |
|
|
68
|
+
| `jsonld` | `{ enabled: true }` | Structured data |
|
|
69
|
+
| `lang` | `'en'` | Language of the site: `<html lang>`, and the wording of the shell |
|
|
70
|
+
| `ui` | `{}` | Wording of the shell, by language — corrects a word, or adds a language |
|
|
71
|
+
| `logo` | `''` | Image beside the project name, in the header |
|
|
72
|
+
| `favicon` | `''` | Icon of the browser tab: `.ico`, `.png` or `.svg` |
|
|
73
|
+
| `socialImage` | `''` | Preview of a shared page. Needs `siteUrl` |
|
|
74
|
+
| `sitemap` | `true` | `sitemap.xml` of the published versions, once `siteUrl` is set |
|
|
75
|
+
| `feed` | `false` | RSS feed of the dated pages. Needs `siteUrl` |
|
|
76
|
+
| `search` | `true` | Search field in the header, and a search page built with the site |
|
|
74
77
|
|
|
75
78
|
## Images
|
|
76
79
|
|
|
@@ -141,16 +144,17 @@ versions: [
|
|
|
141
144
|
],
|
|
142
145
|
```
|
|
143
146
|
|
|
144
|
-
| Field
|
|
145
|
-
|
|
|
146
|
-
| `slug`
|
|
147
|
-
| `name`
|
|
148
|
-
| `folder`
|
|
149
|
-
| `current`
|
|
150
|
-
| `archived`
|
|
151
|
-
| `prerelease`
|
|
152
|
-
| `logo`
|
|
153
|
-
| `favicon`
|
|
147
|
+
| Field | Role |
|
|
148
|
+
| -------------- | ------------------------------------------------------------------------------------------------------------------------------ |
|
|
149
|
+
| `slug` | URL and branch identifier. A number (`v1.0`) freezes the address; a channel (`latest`, `beta`) keeps it right as versions move |
|
|
150
|
+
| `name` | Label shown in the switcher |
|
|
151
|
+
| `folder` | Source folder, relative to the root |
|
|
152
|
+
| `current` | Version served by default. At most one |
|
|
153
|
+
| `archived` | Version kept but no longer maintained. Banner, but stays indexed |
|
|
154
|
+
| `prerelease` | Version in preparation. Banner **and** `noindex` |
|
|
155
|
+
| `logo` | This version's logo, instead of the project's — a beta told apart at a glance |
|
|
156
|
+
| `favicon` | This version's favicon, instead of the project's |
|
|
157
|
+
| `translations` | Folder of each translation, by language code: `{ fr: 'docs/v1.0-fr' }` |
|
|
154
158
|
|
|
155
159
|
## `theme`
|
|
156
160
|
|
|
@@ -251,6 +255,20 @@ The panel is declared here, not derived from the menu of the documentation: the
|
|
|
251
255
|
two can stand side by side with different links, or the site can go without a
|
|
252
256
|
sidebar and navigate from the header alone.
|
|
253
257
|
|
|
258
|
+
## `stickyHeader`
|
|
259
|
+
|
|
260
|
+
```js
|
|
261
|
+
stickyHeader: false,
|
|
262
|
+
```
|
|
263
|
+
|
|
264
|
+
The header holds to the top of the screen by default: the search field, the
|
|
265
|
+
version switcher and the menu stay in reach wherever the reader is in the page.
|
|
266
|
+
|
|
267
|
+
`false` lets it scroll away with the page, which gives its height back to the
|
|
268
|
+
text — on a phone held in one hand, that height is a third of what is visible.
|
|
269
|
+
The anchors then stop reserving room for it: a link to a heading no longer
|
|
270
|
+
leaves a blank band above it.
|
|
271
|
+
|
|
254
272
|
## `foldedSidebar`
|
|
255
273
|
|
|
256
274
|
```js
|
|
@@ -108,3 +108,6 @@ No. Without a title, the project name stands in; without a date, no date is publ
|
|
|
108
108
|
### How do I keep a page offline?
|
|
109
109
|
|
|
110
110
|
Set `draft: true` in its frontmatter. It stays in the repository, absent from the output.
|
|
111
|
+
|
|
112
|
+
What these fields do once the page is built — the order of the menu, the
|
|
113
|
+
byline, the tags under the text — is in [Writing pages](../guide/writing-pages/).
|
|
@@ -41,26 +41,34 @@ supported yet and stop the build.
|
|
|
41
41
|
|
|
42
42
|
## The tokens
|
|
43
43
|
|
|
44
|
-
|
|
45
|
-
redefined token propagates everywhere, without any component having to know
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
|
50
|
-
|
|
|
51
|
-
| `--dp-
|
|
52
|
-
| `--dp-
|
|
53
|
-
| `--dp-
|
|
54
|
-
| `--dp-
|
|
55
|
-
| `--dp-
|
|
56
|
-
| `--dp-
|
|
57
|
-
| `--dp-
|
|
58
|
-
| `--dp-
|
|
59
|
-
| `--dp-
|
|
60
|
-
| `--dp-
|
|
61
|
-
| `--dp-
|
|
62
|
-
| `--dp-
|
|
63
|
-
| `--dp-
|
|
44
|
+
Twenty-one tokens, which both providers define and the components read. A
|
|
45
|
+
redefined token propagates everywhere, without any component having to know —
|
|
46
|
+
in the **light** palette: the dark values live in the theme stylesheet, and
|
|
47
|
+
are redefined in the project's `theme/` folder.
|
|
48
|
+
|
|
49
|
+
| Token | Role |
|
|
50
|
+
| --------------------- | --------------------------------------------------- |
|
|
51
|
+
| `--dp-bg` | Page background |
|
|
52
|
+
| `--dp-bg-soft` | Background of recessed areas — gauge tracks, hovers |
|
|
53
|
+
| `--dp-text` | Body text |
|
|
54
|
+
| `--dp-text-soft` | Secondary text — captions, card footers |
|
|
55
|
+
| `--dp-border` | Visible borders |
|
|
56
|
+
| `--dp-rule` | Discreet rules — tree separators |
|
|
57
|
+
| `--dp-accent` | Accent colour — links, fills |
|
|
58
|
+
| `--dp-accent-soft` | Accent background — banners |
|
|
59
|
+
| `--dp-tip` | Tone of a block of advice — border and title |
|
|
60
|
+
| `--dp-tip-soft` | Its ground |
|
|
61
|
+
| `--dp-attention` | Tone of a block that warns |
|
|
62
|
+
| `--dp-attention-soft` | Its ground |
|
|
63
|
+
| `--dp-danger` | Tone of a block that says what a wrong move costs |
|
|
64
|
+
| `--dp-danger-soft` | Its ground |
|
|
65
|
+
| `--dp-shadow` | Colour of drop shadows |
|
|
66
|
+
| `--dp-radius` | Corner rounding |
|
|
67
|
+
| `--dp-font` | Font family of the text |
|
|
68
|
+
| `--dp-font-mono` | Monospaced family — code, trees |
|
|
69
|
+
| `--dp-content-width` | Reading width. `none` by default |
|
|
70
|
+
| `--dp-sidebar-width` | Menu column |
|
|
71
|
+
| `--dp-toc-width` | Table of contents column |
|
|
64
72
|
|
|
65
73
|
Some components add their own, documented on their page: `--dp-skill-size` for
|
|
66
74
|
a circle gauge, `--dp-skill-color` for the tint of a gauge,
|
|
@@ -72,55 +80,58 @@ The templates write no class. They ask for the class of each slot, and the
|
|
|
72
80
|
theme answers. A provider only redefines what it changes; everything else keeps
|
|
73
81
|
the `dp-*` class below.
|
|
74
82
|
|
|
75
|
-
| Slot | Default class
|
|
76
|
-
| --------------- |
|
|
77
|
-
| `skip` | `dp-skip`
|
|
78
|
-
| `header` | `dp-header`
|
|
79
|
-
| `
|
|
80
|
-
| `
|
|
81
|
-
| `
|
|
82
|
-
| `
|
|
83
|
-
| `
|
|
84
|
-
| `
|
|
85
|
-
| `
|
|
86
|
-
| `
|
|
87
|
-
| `
|
|
88
|
-
| `
|
|
89
|
-
| `
|
|
90
|
-
| `
|
|
91
|
-
| `
|
|
92
|
-
| `
|
|
93
|
-
| `
|
|
94
|
-
| `
|
|
95
|
-
| `
|
|
96
|
-
| `
|
|
97
|
-
| `
|
|
98
|
-
| `
|
|
99
|
-
| `
|
|
100
|
-
| `
|
|
101
|
-
| `
|
|
102
|
-
| `
|
|
103
|
-
| `
|
|
104
|
-
| `
|
|
105
|
-
| `
|
|
106
|
-
| `
|
|
107
|
-
| `
|
|
108
|
-
| `
|
|
109
|
-
| `
|
|
110
|
-
| `
|
|
111
|
-
| `
|
|
112
|
-
| `
|
|
113
|
-
| `
|
|
114
|
-
| `
|
|
115
|
-
| `
|
|
116
|
-
| `
|
|
117
|
-
| `
|
|
118
|
-
| `
|
|
119
|
-
| `
|
|
120
|
-
| `
|
|
121
|
-
| `
|
|
122
|
-
| `
|
|
123
|
-
| `
|
|
83
|
+
| Slot | Default class | Where |
|
|
84
|
+
| --------------- | ----------------------------- | ----------------------------------------------- |
|
|
85
|
+
| `skip` | `dp-skip` | Skip link to the content |
|
|
86
|
+
| `header` | `dp-header` | Site header |
|
|
87
|
+
| `headerStatic` | `dp-header dp-header--static` | The header when it scrolls away |
|
|
88
|
+
| `brand` | `dp-brand` | Project name, in the header |
|
|
89
|
+
| `brandLogo` | `dp-brand-logo` | Logo beside the project name |
|
|
90
|
+
| `versions` | `dp-versions` | Version switcher |
|
|
91
|
+
| `versionsList` | `dp-versions-list` | Open list of the switcher |
|
|
92
|
+
| `languages` | `dp-languages` | Language switcher, when a version is translated |
|
|
93
|
+
| `languagesList` | `dp-languages-list` | Open list of that switcher |
|
|
94
|
+
| `shell` | `dp-shell` | Menu / content / table of contents grid |
|
|
95
|
+
| `shellWide` | `dp-shell dp-shell--wide` | The same, without menu or table of contents |
|
|
96
|
+
| `sidebar` | `dp-sidebar` | Menu column |
|
|
97
|
+
| `nav` | `dp-nav` | Navigation list |
|
|
98
|
+
| `navItem` | `dp-nav-item` | Navigation entry |
|
|
99
|
+
| `navItemParent` | `dp-nav-item--parent` | Entry that holds a section |
|
|
100
|
+
| `navLink` | `dp-nav-link` | Navigation link |
|
|
101
|
+
| `navLabel` | `dp-nav-label` | Section label, not clickable |
|
|
102
|
+
| `notice` | `dp-notice` | Banner of the versions that are not the current |
|
|
103
|
+
| `skillIcon` | `dp-skill-icon` | Icon before the name of a gauge |
|
|
104
|
+
| `main` | `dp-main` | Main area |
|
|
105
|
+
| `article` | `dp-article` | Page content |
|
|
106
|
+
| `toc` | `dp-toc` | Table of contents column |
|
|
107
|
+
| `tocTitle` | `dp-toc-title` | Title of the table of contents |
|
|
108
|
+
| `tocList` | `dp-toc-list` | List of the table of contents |
|
|
109
|
+
| `tocItem` | `dp-toc-item` | Entry of the table of contents |
|
|
110
|
+
| `footer` | `dp-footer` | Page footer |
|
|
111
|
+
| `scrollTop` | `dp-scroll-top` | Back-to-top button |
|
|
112
|
+
| `scrollTopIcon` | `dp-scroll-top-icon` | Arrow of that button |
|
|
113
|
+
| `search` | `dp-search` | Search field of the header |
|
|
114
|
+
| `schemeToggle` | `dp-scheme-toggle` | Light / dark button of the header |
|
|
115
|
+
| `headerNav` | `dp-header-nav` | Versions, links and search, in a row |
|
|
116
|
+
| `headerLinks` | `dp-header-links` | Links of the header |
|
|
117
|
+
| `menu` | `dp-menu` | Menu button, on a narrow screen |
|
|
118
|
+
| `menuPanel` | `dp-menu-panel` | What that button opens |
|
|
119
|
+
| `navGroup` | `dp-nav-group` | A folded category of the menu |
|
|
120
|
+
| `navSummary` | `dp-nav-summary` | The handle of that fold |
|
|
121
|
+
| `sidebarMenu` | `dp-sidebar-menu` | The documentation menu, on a narrow screen |
|
|
122
|
+
| `mega` | `dp-mega` | A header entry that opens a panel |
|
|
123
|
+
| `megaPanel` | `dp-mega-panel` | That panel |
|
|
124
|
+
| `megaColumn` | `dp-mega-column` | A column of the panel |
|
|
125
|
+
| `megaTitle` | `dp-mega-title` | The title of a column |
|
|
126
|
+
| `byline` | `dp-byline` | Authors and dates at the head of a page |
|
|
127
|
+
| `bylineAuthors` | `dp-byline-authors` | List of the authors |
|
|
128
|
+
| `bylineAuthor` | `dp-byline-author` | One author |
|
|
129
|
+
| `bylineAvatar` | `dp-byline-avatar` | Avatar of an author |
|
|
130
|
+
| `bylineName` | `dp-byline-name` | Name of an author |
|
|
131
|
+
| `bylineBio` | `dp-byline-bio` | Biography of an author |
|
|
132
|
+
| `bylineDates` | `dp-byline-dates` | Writing and update dates |
|
|
133
|
+
| `tags` | `dp-tags` | Tags at the bottom of a page |
|
|
134
|
+
| `tag` | `dp-tag` | One tag |
|
|
124
135
|
|
|
125
136
|
A slot can carry **variants**, suffixed `--variant`: `column` gives
|
|
126
137
|
`dp-column--span-8`, `skill` gives `dp-skill--circle`.
|
|
@@ -15,6 +15,10 @@ what goes further — a script that builds a site, a theme of your own.
|
|
|
15
15
|
Each entry comes from the JSDoc of the source, which the type checker
|
|
16
16
|
verifies: it cannot drift from the code without the build noticing.
|
|
17
17
|
|
|
18
|
+
To use the tool rather than call it, start at
|
|
19
|
+
[Installation](../guide/installation/); the fields of a configuration are
|
|
20
|
+
in [Configuration](./configuration/).
|
|
21
|
+
|
|
18
22
|
## `@docpensieve/shared`
|
|
19
23
|
|
|
20
24
|
Constants, errors and slugs, shared by every package.
|
|
@@ -81,6 +85,16 @@ JSON-LD types supported by the `jsonld.type` frontmatter field.
|
|
|
81
85
|
|
|
82
86
|
CSS frameworks known to the ThemeEngine.
|
|
83
87
|
|
|
88
|
+
### `DOCUMENTATION_URL`
|
|
89
|
+
|
|
90
|
+
`DOCUMENTATION_URL`
|
|
91
|
+
|
|
92
|
+
Public address of the documentation.
|
|
93
|
+
|
|
94
|
+
Written wherever a reader could be stuck — the foot of the help, the
|
|
95
|
+
generated configuration, the end of `init` — so it lives in one place
|
|
96
|
+
rather than in each of them.
|
|
97
|
+
|
|
84
98
|
### `PAGE_LAYOUTS`
|
|
85
99
|
|
|
86
100
|
`PAGE_LAYOUTS`
|
|
@@ -91,19 +105,14 @@ Layouts accepted in a page's frontmatter.
|
|
|
91
105
|
the right, content held to reading width. `home` removes all three, which
|
|
92
106
|
is what a landing page expects.
|
|
93
107
|
|
|
94
|
-
### `
|
|
108
|
+
### `ADMONITION_TONES`
|
|
95
109
|
|
|
96
|
-
`
|
|
110
|
+
`ADMONITION_TONES`
|
|
97
111
|
|
|
98
|
-
|
|
112
|
+
Tones an admonition can take: what colours it, nothing more.
|
|
99
113
|
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
falls back to these values. That is what lets a single template render
|
|
103
|
-
either `dp-nav` or a string of Tailwind utilities.
|
|
104
|
-
|
|
105
|
-
This table is shared: `core` reads it in its templates, `theme` extends it
|
|
106
|
-
in its providers.
|
|
114
|
+
Here rather than with the component: the configuration validates the kinds a
|
|
115
|
+
project declares, and `core` never imports `components` (ADR-002).
|
|
107
116
|
|
|
108
117
|
### `DocPensieveError`
|
|
109
118
|
|
|
@@ -277,6 +286,66 @@ Reads the ordering weight of a prefixed file name.
|
|
|
277
286
|
|
|
278
287
|
**Returns** `number` — The prefix number, or `Infinity` when absent (sorted last).
|
|
279
288
|
|
|
289
|
+
### `UI_STRINGS`
|
|
290
|
+
|
|
291
|
+
`UI_STRINGS`
|
|
292
|
+
|
|
293
|
+
The shipped languages.
|
|
294
|
+
|
|
295
|
+
### `DEFAULT_LANGUAGE`
|
|
296
|
+
|
|
297
|
+
`DEFAULT_LANGUAGE`
|
|
298
|
+
|
|
299
|
+
Language used when nothing else is known.
|
|
300
|
+
|
|
301
|
+
### `uiStrings`
|
|
302
|
+
|
|
303
|
+
`uiStrings([lang], [overrides])`
|
|
304
|
+
|
|
305
|
+
The wording of a language, completed by English for anything it omits.
|
|
306
|
+
|
|
307
|
+
| Parameter | Type | |
|
|
308
|
+
| --- | --- | --- |
|
|
309
|
+
| `[lang]` | `string` | Language code, `fr` or `fr-CA`. |
|
|
310
|
+
| `[overrides]` | `Record<string, Partial<UiStrings>>` | Wording declared by the project. |
|
|
311
|
+
|
|
312
|
+
**Returns** `UiStrings`
|
|
313
|
+
|
|
314
|
+
### `pageCount`
|
|
315
|
+
|
|
316
|
+
`pageCount(count, strings, [lang])`
|
|
317
|
+
|
|
318
|
+
Counts pages in the language of the page.
|
|
319
|
+
|
|
320
|
+
The plural category comes from the language itself, through the CLDR rules
|
|
321
|
+
`Intl` carries: `count === 1` is an English rule and gets French wrong on
|
|
322
|
+
zero — "0 page", not "0 pages" — and has nothing to say about Polish or
|
|
323
|
+
Arabic, which have four and six categories.
|
|
324
|
+
|
|
325
|
+
| Parameter | Type | |
|
|
326
|
+
| --- | --- | --- |
|
|
327
|
+
| `count` | `number` | |
|
|
328
|
+
| `strings` | `UiStrings` | |
|
|
329
|
+
| `[lang]` | `string` | Language of the page. |
|
|
330
|
+
|
|
331
|
+
**Returns** `string` — For instance `12 pages` or `1 page`.
|
|
332
|
+
|
|
333
|
+
### `textDirection`
|
|
334
|
+
|
|
335
|
+
`textDirection([lang])`
|
|
336
|
+
|
|
337
|
+
Writing direction of a language, for the `dir` attribute.
|
|
338
|
+
|
|
339
|
+
Read from the language rather than from a list of our own: `Intl` carries
|
|
340
|
+
what CLDR knows, and a list would go stale the day someone translates into
|
|
341
|
+
a language nobody thought of.
|
|
342
|
+
|
|
343
|
+
| Parameter | Type | |
|
|
344
|
+
| --- | --- | --- |
|
|
345
|
+
| `[lang]` | `string` | |
|
|
346
|
+
|
|
347
|
+
**Returns** `'ltr' \| 'rtl'` — `ltr` when the language is unknown — the safe default, and what every page did before this existed.
|
|
348
|
+
|
|
280
349
|
## `@docpensieve/core`
|
|
281
350
|
|
|
282
351
|
Configuration, loading, compilation, structured data and generation.
|
|
@@ -516,7 +585,7 @@ Turns the JSON description of a version into a table of authors.
|
|
|
516
585
|
|
|
517
586
|
### `buildByline`
|
|
518
587
|
|
|
519
|
-
`buildByline(frontmatter, [table], [where])`
|
|
588
|
+
`buildByline(frontmatter, [table], [where], [locale])`
|
|
520
589
|
|
|
521
590
|
Assembles what the head of a page shows, or nothing when it has none of it.
|
|
522
591
|
|
|
@@ -525,6 +594,7 @@ Assembles what the head of a page shows, or nothing when it has none of it.
|
|
|
525
594
|
| `frontmatter` | `Record<string, any>` | |
|
|
526
595
|
| `[table]` | `Map<string, Author>` | |
|
|
527
596
|
| `[where]` | `string` | Page named in a date error. |
|
|
597
|
+
| `[locale]` | `string` | Locale the dates are written in. |
|
|
528
598
|
|
|
529
599
|
**Returns** `Byline \| null`
|
|
530
600
|
|
|
@@ -532,7 +602,7 @@ Assembles what the head of a page shows, or nothing when it has none of it.
|
|
|
532
602
|
|
|
533
603
|
### `readDate`
|
|
534
604
|
|
|
535
|
-
`readDate(value, field, where)`
|
|
605
|
+
`readDate(value, field, where, [locale])`
|
|
536
606
|
|
|
537
607
|
Reads a date of the frontmatter, and gives it in both forms: the machine one
|
|
538
608
|
for `<time datetime>`, the readable one for the reader.
|
|
@@ -546,6 +616,7 @@ than shown as `Invalid Date`.
|
|
|
546
616
|
| `value` | `unknown` | |
|
|
547
617
|
| `field` | `string` | Name of the field, for the error message. |
|
|
548
618
|
| `where` | `string` | Page the date comes from. |
|
|
619
|
+
| `[locale]` | `string` | Locale the label is written in. Default: `en-GB`. |
|
|
549
620
|
|
|
550
621
|
**Returns** `{ iso: string, label: string } \| null` — `null` when absent.
|
|
551
622
|
|
|
@@ -685,6 +756,43 @@ Declares the framework of the active theme, which `ForTheme` reads.
|
|
|
685
756
|
| --- | --- | --- |
|
|
686
757
|
| `[framework]` | `string` | |
|
|
687
758
|
|
|
759
|
+
### `ADMONITION_KINDS`
|
|
760
|
+
|
|
761
|
+
`ADMONITION_KINDS`
|
|
762
|
+
|
|
763
|
+
The kinds the tool ships with, each a label and a tone.
|
|
764
|
+
|
|
765
|
+
`alert` and `danger` share a tone and differ in their label and their icon:
|
|
766
|
+
one calls for attention now, the other warns of what a wrong move costs.
|
|
767
|
+
|
|
768
|
+
### `Admonition`
|
|
769
|
+
|
|
770
|
+
`Admonition(props)`
|
|
771
|
+
|
|
772
|
+
Block set apart from the text.
|
|
773
|
+
|
|
774
|
+
| Parameter | Type | |
|
|
775
|
+
| --- | --- | --- |
|
|
776
|
+
| `props` | `{ className?: string, style?: object, children?: any, type?: string, title?: string, }` | `type` names the kind; `title` replaces its label for this block alone. |
|
|
777
|
+
|
|
778
|
+
**Throws** `DocPensieveError` — When the kind is unknown.
|
|
779
|
+
|
|
780
|
+
### `getAdmonitionKinds`
|
|
781
|
+
|
|
782
|
+
`getAdmonitionKinds()`
|
|
783
|
+
|
|
784
|
+
@returns \{Record<string, \{ label: string, tone: string, icon?: string \}>\} Every kind available.
|
|
785
|
+
|
|
786
|
+
### `setAdmonitionKinds`
|
|
787
|
+
|
|
788
|
+
`setAdmonitionKinds([kinds])`
|
|
789
|
+
|
|
790
|
+
Declares the kinds of the project, beside the ones shipped.
|
|
791
|
+
|
|
792
|
+
| Parameter | Type | |
|
|
793
|
+
| --- | --- | --- |
|
|
794
|
+
| `[kinds]` | `Record<string, { label: string, tone: string, icon?: string }>` | |
|
|
795
|
+
|
|
688
796
|
### `Card`
|
|
689
797
|
|
|
690
798
|
`Card(props)`
|
|
@@ -759,6 +867,44 @@ the grid recomputes the widths by itself.
|
|
|
759
867
|
| --- | --- | --- |
|
|
760
868
|
| `props` | `{ className?: string, style?: object, children?: any }` | |
|
|
761
869
|
|
|
870
|
+
### `Menu`
|
|
871
|
+
|
|
872
|
+
`Menu(props)`
|
|
873
|
+
|
|
874
|
+
Menu of links.
|
|
875
|
+
|
|
876
|
+
| Parameter | Type | |
|
|
877
|
+
| --- | --- | --- |
|
|
878
|
+
| `props` | `{ className?: string, style?: object, children?: any, label?: string, }` | `label` names the menu for screen readers, and labels the button it folds into on a narrow screen. |
|
|
879
|
+
|
|
880
|
+
### `MenuGroup`
|
|
881
|
+
|
|
882
|
+
`MenuGroup(props)`
|
|
883
|
+
|
|
884
|
+
Group of entries, folded under a title.
|
|
885
|
+
|
|
886
|
+
In the row it opens as a panel below its title; folded, it unfolds in place
|
|
887
|
+
rather than over the rest — on a narrow screen a panel would open off
|
|
888
|
+
screen.
|
|
889
|
+
|
|
890
|
+
| Parameter | Type | |
|
|
891
|
+
| --- | --- | --- |
|
|
892
|
+
| `props` | `{ className?: string, style?: object, children?: any, title?: string, }` | |
|
|
893
|
+
|
|
894
|
+
**Throws** `DocPensieveError` — Outside a `Menu`, or without a title.
|
|
895
|
+
|
|
896
|
+
### `MenuLink`
|
|
897
|
+
|
|
898
|
+
`MenuLink(props)`
|
|
899
|
+
|
|
900
|
+
Entry of a menu.
|
|
901
|
+
|
|
902
|
+
| Parameter | Type | |
|
|
903
|
+
| --- | --- | --- |
|
|
904
|
+
| `props` | `{ className?: string, style?: object, children?: any, href?: string, }` | |
|
|
905
|
+
|
|
906
|
+
**Throws** `DocPensieveError` — Outside a `Menu`, or without a target.
|
|
907
|
+
|
|
762
908
|
### `FallbackAfter`
|
|
763
909
|
|
|
764
910
|
`FallbackAfter(props)`
|
|
@@ -24,3 +24,6 @@ what is wrong and what is expected instead.
|
|
|
24
24
|
Nothing fails silently. A component that cannot render what it is asked for
|
|
25
25
|
stops the build rather than produce an inert element — a tag that does nothing
|
|
26
26
|
goes unnoticed on review, an error does not.
|
|
27
|
+
|
|
28
|
+
For the failures that say nothing — the site builds and something is still
|
|
29
|
+
wrong — the guide has [When it breaks](../guide/when-it-breaks/).
|
|
@@ -106,3 +106,6 @@ parent, a file not found: each one stops the build with a message and a hint.
|
|
|
106
106
|
The alternative — rendering an empty element, ignoring a prop, falling back on
|
|
107
107
|
a default value — produces pages that look right and are not. Those faults are
|
|
108
108
|
only discovered in production, long afterwards.
|
|
109
|
+
|
|
110
|
+
Those it does produce, with the shape each one takes on your screen, are
|
|
111
|
+
gathered by symptom in [When it breaks](./guide/when-it-breaks/).
|