docpensieve 0.5.0-beta.2 → 0.5.0-beta.3

package/bin/docpensieve.js

@@ -63,6 +63,7 @@ program
   .command('dev')
   .description('Development server with reload')
   .option('-p, --port <number>', 'listening port', Number, 3000)
+  .option('--host <address>', 'address to listen on; 0.0.0.0 opens it to the network', '127.0.0.1')
   .action(async (options) => {
     await dev(options);
   });
@@ -71,6 +72,7 @@ program
   .command('serve')
   .description('Serves the output folder statically')
   .option('-p, --port <number>', 'listening port', Number, 4000)
+  .option('--host <address>', 'address to listen on; 0.0.0.0 opens it to the network', '127.0.0.1')
   .option('-d, --dir <dir>', 'folder to serve')
   .action(async (options) => {
     await serve(options);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docpensieve",
-  "version": "0.5.0-beta.2",
+  "version": "0.5.0-beta.3",
   "description": "DocPensieve command-line interface (init, build, check, dev, serve)",
   "type": "module",
   "license": "MIT",
@@ -24,10 +24,10 @@
     "types"
   ],
   "dependencies": {
-    "@docpensieve/components": "0.5.0-beta.2",
-    "@docpensieve/core": "0.5.0-beta.2",
-    "@docpensieve/shared": "0.5.0-beta.2",
-    "@docpensieve/theme": "0.5.0-beta.2",
+    "@docpensieve/components": "0.5.0-beta.3",
+    "@docpensieve/core": "0.5.0-beta.3",
+    "@docpensieve/shared": "0.5.0-beta.3",
+    "@docpensieve/theme": "0.5.0-beta.3",
     "chalk": "^6.0.0",
     "chokidar": "^5.0.0",
     "commander": "^15.0.0"

package/src/commands/build.js

@@ -11,6 +11,7 @@ import {
   createRegistry,
   setSiteContext,
   setAdmonitionKinds,
+  setSnippetIcons,
 } from '@docpensieve/components';
 import { SiteGenerator, loadConfig, resolveVersion } from '@docpensieve/core';
 
@@ -28,6 +29,7 @@ export async function build(versionSlug, options = {}) {
 
   // The kinds a project declares, beside the ones shipped.
   setAdmonitionKinds(config.admonitions);
+  setSnippetIcons(config.snippetIcons);
 
   const generator = new SiteGenerator(config, {
     // `globalComponents: false` removes the shipped components: a project that

package/src/commands/dev.js

@@ -12,12 +12,20 @@ import {
   createRegistry,
   setSiteContext,
   setAdmonitionKinds,
+  setSnippetIcons,
 } from '@docpensieve/components';
 import { SiteGenerator, loadConfig } from '@docpensieve/core';
 import { CONFIG_FILENAME, DocPensieveError, THEME_FOLDER } from '@docpensieve/shared';
 import chokidar from 'chokidar';
 
-import { RELOAD_PATH, createStaticServer, listen } from '../server.js';
+import {
+  DEFAULT_HOST,
+  RELOAD_PATH,
+  createStaticServer,
+  exposedNotice,
+  isExposed,
+  listen,
+} from '../server.js';
 import { createTheme } from '../theme.js';
 
 /** Default port of `dev`, distinct from that of `serve`. */
@@ -40,7 +48,7 @@ const RELOAD_SCRIPT =
   `.addEventListener("message",()=>location.reload())</script>`;
 
 /**
- * @param {{ port?: number, cwd?: string }} [options]
+ * @param {{ port?: number, host?: string, cwd?: string }} [options]
  * @returns {Promise<{
  *   server: import('node:http').Server,
  *   watcher: import('chokidar').FSWatcher,
@@ -62,6 +70,7 @@ export async function dev(options = {}) {
     // Read again with the rest: a kind added to the configuration must show
     // without restarting the command.
     setAdmonitionKinds(current.admonitions);
+    setSnippetIcons(current.snippetIcons);
     const generator = new SiteGenerator(current, {
       // `globalComponents: false` removes the shipped components: a project
       // that defines its own thus avoids a name collision. The option was
@@ -87,8 +96,10 @@ export async function dev(options = {}) {
     },
   });
 
-  const port = await listen(server, options.port ?? DEFAULT_PORT);
+  const host = options.host ?? DEFAULT_HOST;
+  const port = await listen(server, options.port ?? DEFAULT_PORT, 10, host);
   const url = `http://localhost:${port}${config.baseUrl}`;
+  if (isExposed(host)) console.log(exposedNotice(host));
   console.log(`served at ${url}`);
 
   // The project's own stylesheets, re-read by every rebuild.

package/src/commands/init.js

@@ -368,6 +368,16 @@ function renderConfig({ name, theme, siteUrl, version, translation = '' }) {
     '  // Back-to-top button on every page.',
     '  scrollToTop: true,',
     '',
+    '  // A button copying each block of code. It is the one thing that makes a',
+    '  // content page load a script — a small file, shared by every page of the',
+    '  // version — so it stays off until you ask for it.',
+    '  copyCode: false,',
+    '',
+    '  // Icon collection a code block takes the mark of its language from, for',
+    "  // instance 'simple-icons' once @iconify-json/simple-icons is installed.",
+    '  // Left empty, the short name of the language is shown instead.',
+    "  snippetIcons: '',",
+    '',
     '  // The header stays at the top of the screen. false lets it scroll away',
     '  // with the page, and gives its height back to the text.',
     '  stickyHeader: true,',

package/src/commands/serve.js

@@ -10,13 +10,13 @@ import path from 'node:path';
 import { loadConfig } from '@docpensieve/core';
 import { DocPensieveError } from '@docpensieve/shared';
 
-import { createStaticServer, listen } from '../server.js';
+import { DEFAULT_HOST, createStaticServer, exposedNotice, isExposed, listen } from '../server.js';
 
 /** Default port of `serve`, distinct from that of `dev`. */
 const DEFAULT_PORT = 4000;
 
 /**
- * @param {{ port?: number, dir?: string, cwd?: string }} [options]
+ * @param {{ port?: number, host?: string, dir?: string, cwd?: string }} [options]
  * @returns {Promise<{ server: import('node:http').Server, port: number, url: string }>}
  * @throws {DocPensieveError} When the folder to serve does not exist.
  */
@@ -34,11 +34,13 @@ export async function serve(options = {}) {
   // The site is mounted under the configuration's baseUrl: otherwise the links
   // of the generated pages would not resolve locally.
   const server = createStaticServer({ root, basePath: config.baseUrl });
-  const port = await listen(server, options.port ?? DEFAULT_PORT);
+  const host = options.host ?? DEFAULT_HOST;
+  const port = await listen(server, options.port ?? DEFAULT_PORT, 10, host);
   const url = `http://localhost:${port}${config.baseUrl}`;
 
   console.log(`${root}`);
   console.log(`served at ${url}`);
+  if (isExposed(host)) console.log(exposedNotice(host));
 
   return { server, port, url };
 }

package/src/server.js

@@ -162,16 +162,35 @@ export function createStaticServer({ root, basePath = '/', inject = null, onRelo
   });
 }
 
+/** The loopback address: the site is served to this machine and to no other. */
+export const DEFAULT_HOST = '127.0.0.1';
+
+/**
+ * Whether an address reaches beyond this machine.
+ *
+ * @param {string} host
+ * @returns {boolean}
+ */
+export function isExposed(host) {
+  return !['127.0.0.1', 'localhost', '::1'].includes(host);
+}
+
 /**
  * Starts listening, looking for a free port if needed.
  *
+ * On this machine only, unless asked otherwise. Called without a host, Node
+ * listens on every interface: anyone on the same network — a café, a
+ * coworking space — could read the site being written, drafts included.
+ *
  * @param {import('node:http').Server} server
  * @param {number} port Desired port.
  * @param {number} [attempts] Number of ports tried from `port` on.
+ * @param {string} [host] Address to listen on. `0.0.0.0` opens it to the
+ *   network, which a phone on the same wifi needs.
  * @returns {Promise<number>} The port actually used.
  * @throws {DocPensieveError} When no port is free in the range.
  */
-export function listen(server, port, attempts = 10) {
+export function listen(server, port, attempts = 10, host = DEFAULT_HOST) {
   return new Promise((resolve, reject) => {
     let current = port;
 
@@ -181,7 +200,7 @@ export function listen(server, port, attempts = 10) {
       // the next one beats forcing --port.
       if (error.code === 'EADDRINUSE' && current < port + attempts - 1) {
         current += 1;
-        server.listen(current);
+        server.listen(current, host);
         return;
       }
       server.off('error', onError);
@@ -202,6 +221,17 @@ export function listen(server, port, attempts = 10) {
       const address = server.address();
       resolve(typeof address === 'object' && address !== null ? address.port : current);
     });
-    server.listen(current);
+    server.listen(current, host);
   });
 }
+
+/**
+ * Said when the site is opened to the network, so that it is never done
+ * without the person knowing.
+ *
+ * @param {string} host
+ * @returns {string}
+ */
+export function exposedNotice(host) {
+  return `listening on ${host}: anyone on this network can read the site.`;
+}

package/starter/01-guide/02-first-site.md

@@ -98,6 +98,10 @@ online.
     → ignores the deployment prefix "/my-project/"
 ```
 
+Two commands, and the second reads what the first wrote — so they belong
+together. [Deployment](./deployment/) shows how to say that once, in a
+`package.json`, and have a workflow run the same thing you run.
+
 It is the check to run after any change of `baseUrl`, of folder structure or of
 URL. When something does not add up, [When it breaks](./when-it-breaks/) lists
 the failures this tool produces, by the symptom you see.

package/starter/01-guide/06-deployment.md

@@ -88,6 +88,32 @@ the tool through `npx`, which takes the latest published version. To pin it
 from one build to the next, declare `docpensieve` in a `package.json` and add
 `npm ci` before the build.
 
+## One command, for you and for the machine
+
+Two commands are one too many to remember, and a workflow should run exactly
+what you run. A `package.json` is the place to say it once:
+
+```json
+{
+  "scripts": {
+    "docs": "docpensieve dev",
+    "check": "docpensieve build && docpensieve check"
+  }
+}
+```
+
+`npm run check` then generates the site and reads it back. A dead link, a
+nesting the markup cannot carry, a page that stops the build: each one fails
+the command, on your machine and in your workflow, in the same way and with
+the same message.
+
+The `&&` is the point of it. `check` reads what `build` wrote, so a check run
+on its own tells you about the site as it was the last time it was generated —
+which, the day you forget, is the day it matters.
+
+With that in place the recipe above becomes `npm ci` and `npm run check`, and
+the version of the tool stops depending on the day the workflow ran.
+
 ## Reading back before publishing
 
 A generated site can compile without error and contain dead links.

package/starter/01-guide/07-migrate-to-beta.md

@@ -31,8 +31,23 @@ npx docpensieve check
 
 ## What changes on its own
 
-Nothing yet: the 0.5 has just opened. Each change is listed here as it lands,
-beside what it asks of a project already built on the 0.4.
+- **`dev` and `serve` listen on this machine only.** They used to listen on
+  every interface, so anyone on the same network could read the site being
+  written. To look at it from a phone on the same wifi, say so:
+  `npx docpensieve dev --host 0.0.0.0`.
+- **Code blocks carry a background of their own.** A block in a language the
+  highlighter does not know used to sit on the bare page; it now looks like
+  every other block.
+- **An error keeps its hint.** An error the tool raises while a page compiles
+  no longer comes out as a generic syntax complaint.
+
+## What is worth turning on
+
+- [Snippet](../components/snippet/), to show a real file rather than a copy.
+- [Hero](../components/hero/) and [Calendar](../components/calendar/).
+- `copyCode`, a copy button on every code block — off by default, since it is
+  what makes a page load a script. See [the reference](../reference/configuration/).
+- `snippetIcons`, if your project installs an icon collection.
 
 ## What to check afterwards
 

package/starter/02-components/01-card.mdx

@@ -341,3 +341,6 @@ in none: a class of yours always wins, even to undo the default style.
 </Card>
 
 </ForTheme>
+
+The commonest row is a row of cards; [Columns](./columns/) shows how to keep
+them the same height, which a grid alone does not.

package/starter/02-components/13-snippet.mdx

@@ -0,0 +1,230 @@
+---
+title: Snippet
+description: A code block that names a real file of your project, read when the page is generated, so that the example cannot go stale.
+---
+
+# Snippet
+
+An example written by hand is a copy. It stops being true the day the code
+changes, and nothing reports it: the page goes on showing something that
+worked once. `Snippet` names the file instead, and the file is read when the
+page is generated — there is no copy left to drift.
+
+The idea comes from **Christophe Avonture**, who built it for his own site.
+
+## Naming a file
+
+<Snippet source="./snippet-example.js" />
+
+```mdx
+<Snippet source="./snippet-example.js" />
+```
+
+The file name labels the block, and the highlighting is the one every code
+block gets. A path beginning with `./` or `../` is read **from the page**, as
+a link is; any other path is read **from the root of your project**, so that
+`src/index.js` means the same file from every page.
+
+## Part of a file
+
+Two ways, and they do not age the same.
+
+A **range of lines** is quick to write and means line 12 of the file as it is
+today:
+
+<Snippet source="./snippet-example.js" lines="9-10" title="The words it drops" />
+
+```mdx
+<Snippet source="./snippet-example.js" lines="9-10" title="The words it drops" />
+```
+
+Write `lines="9"` for one line, `"9-10"` for a range, `"9-"` from there to the
+end, `"-10"` from the start. It says what the file holds today, and only
+today.
+
+A **region** is a marker left in the source file itself, in a comment. It
+follows the code when the code moves, which is the whole point of naming a
+file rather than copying it:
+
+<Snippet source="./snippet-example.js" region="guard" title="The guard" />
+
+```mdx
+<Snippet source="./snippet-example.js" region="guard" title="The guard" />
+```
+
+In the file, the marker is an ordinary comment — the one editors already fold
+on:
+
+```js
+// #region guard
+if (!name) {
+  throw new Error('greet needs a name');
+}
+// #endregion
+```
+
+The indentation the kept lines share is removed, so a region marked inside a
+function does not come out shifted.
+
+## Folding a long file
+
+`collapsed` puts the block inside a `details`. No script: a long file can sit
+in a page without burying what follows it.
+
+<Snippet source="./snippet-example.js" collapsed title="The whole file" />
+
+```mdx
+<Snippet source="./snippet-example.js" collapsed title="The whole file" />
+```
+
+## Code you write yourself
+
+Without `source`, the component frames the code written in the page. A fenced
+block inside the tag is the dependable way to write it: it carries anything,
+braces and `<` included, and no formatter touches what is inside it.
+
+<Snippet title="greet.py">
+
+```python
+def greet(name, greetings={'en': 'Hello'}):
+    return f"{greetings['en']}, {name}!"
+```
+
+</Snippet>
+
+````mdx
+<Snippet title="greet.py">
+
+```python
+def greet(name, greetings={'en': 'Hello'}):
+    return f"{greetings['en']}, {name}!"
+```
+
+</Snippet>
+````
+
+The extension of the title names the language; `lang` says it where the title
+does not, as for a shell:
+
+<Snippet title="Build the site" lang="bash">
+
+```bash
+npm install
+npx docpensieve build
+```
+
+</Snippet>
+
+````mdx
+<Snippet title="Build the site" lang="bash">
+
+```bash
+npm install
+npx docpensieve build
+```
+
+</Snippet>
+````
+
+### Code typed straight into the tag
+
+Code written bare inside the tag is read too, from the page as you typed it —
+indentation kept, nothing taken for Markdown:
+
+```mdx
+<Snippet title="who_are_you.py">name = input("What's your name? ")</Snippet>
+```
+
+Two things it cannot carry, both of which happen before any component sees the
+code. A page is MDX, so `{`, `}` and `<` are read as MDX and stop the build on
+a syntax error. And a formatter run over your pages reflows what it takes for
+prose: two lines of shell come back as one. Where either applies — which is
+most real code — use the fenced form above.
+
+## The mark of the language
+
+A block carries the colour of its language — a rule above it, and a short mark
+beside the file name. The colour is set as a variable on the frame, so the
+theme decides what it paints and a project can set another.
+
+The same function, in the other file this page reads. Nothing was said about
+the language: the extension carried it, and with it the mark and the colour.
+
+<Snippet source="./snippet-example.py" region="guard" title="The same guard, in Python" />
+
+```mdx
+<Snippet source="./snippet-example.py" region="guard" title="The same guard, in Python" />
+```
+
+A block the page writes says its language in the fence, and is marked the same
+way:
+
+<Snippet title="deploy.yml">
+
+```yaml
+steps:
+  - run: npx docpensieve build
+  - run: npx docpensieve check
+```
+
+</Snippet>
+
+<Snippet title="A first build" lang="bash">
+
+```bash
+npx docpensieve init my-site
+npx docpensieve dev
+```
+
+</Snippet>
+
+Where a project installs an icon collection and names it, the drawing replaces
+the mark:
+
+```js
+snippetIcons: 'simple-icons',
+```
+
+It is never a reason to fail. The icon is the tool's idea, not something your
+page asked for: a collection you do not have, or a language it does not draw,
+brings back the mark. `icon="simple-icons:docker"` on a single block wins over
+both.
+
+### A language nobody marked
+
+Twenty-one languages have a mark and a colour. Any other is shown without
+one — the frame, the name, and the code.
+
+Highlighting is a separate matter, and a wider one: the highlighter knows
+several hundred languages, and a block in one it does not know comes out as
+plain text rather than stopping the build. You can write a snippet in anything
+your project is written in.
+
+## What it refuses
+
+Nothing fails quietly, because a snippet that resolved to nothing would leave
+an empty frame — and an empty frame looks deliberate.
+
+| Written                             | What happens                                                    |
+| ----------------------------------- | --------------------------------------------------------------- |
+| a file that is not there            | The build stops, saying which path was looked for.              |
+| a path leading outside the project  | Refused: a page is content, and content does not read the disk. |
+| a region no marker opens, or closes | The build stops, naming the region and the file.                |
+| a range that reads backwards        | The build stops.                                                |
+
+## Properties
+
+| Property    | Type      | Effect                                                                      |
+| ----------- | --------- | --------------------------------------------------------------------------- |
+| `source`    | `string`  | File to read. From the page with `./` or `../`, from the project otherwise. |
+| `title`     | `string`  | Label above the block. Defaults to the name of the file.                    |
+| `lines`     | `string`  | `8`, `8-14`, `8-` or `-14`.                                                 |
+| `region`    | `string`  | Name marked by `#region` and `#endregion` in the file.                      |
+| `lang`      | `string`  | Language for the highlighting, when the extension says the wrong thing.     |
+| `collapsed` | `boolean` | Folds the block into a `details`.                                           |
+| `icon`      | `string`  | An icon for this block, instead of the mark of its language.                |
+| `className` | `string`  | Classes added to the frame.                                                 |
+| `style`     | `object`  | Inline styles on the frame.                                                 |
+
+The file this page reads is installed along with it, so every example above
+works in your project exactly as it does here.