improve documentation based on feedback

Author: bmuenzenmeyer

www/pages/getting-started.md

@@ -4,6 +4,8 @@ This page takes you from an empty directory to a rendered documentation page.
 
 ## Install
 
+From an initialized npm project, run this in your terminal.
+
 ```bash
 npm install --save-dev @node-core/doc-kit
 ```
@@ -41,12 +43,12 @@ npx doc-kit generate \
   -o out
 ```
 
-Open `out/all.html`.
+Open `out/all.html` in a browser. You'll notice the Node.js branding.
 
 ## Render the modern site
 
 The `web` target produces the server-rendered, client-hydrated site that
-nodejs.org uses — and that this site is built with:
+[nodejs.org](https://nodejs.org) uses — and that this site is built with:
 
 ```bash
 npx doc-kit generate \
@@ -65,21 +67,67 @@ npx doc-kit generate -t web -t orama-db -i "docs/*.md" -o out
 
 The `web` output uses import maps and client-side hydration, so it must be
 served over HTTP — opening the files directly with `file://` will not work. Any
-static server does; for example:
+static server will do the trick; for example:
 
 ```bash
-npx serve out
+npx serve out -p 3000
 ```
 
 Then open the printed URL (usually <http://localhost:3000>). The
 `legacy-html-all` output from earlier has no such requirement — `out/all.html`
 opens straight from disk.
 
+## Customize the `web` generator output
+
+The power of the `web` generator comes from its customization hooks. Let's walk
+through a couple quick changes.
+
+Create a `doc-kit.config.mjs` file at the root of the project.
+
+```json
+import { join } from 'node:path';
+
+/** @type {import('@node-core/doc-kit/src/utils/configuration/types').Configuration} */
+export default {
+  web: {
+    project: "My Project", // Project name used in page titles and the version selector
+    remoteConfigUrl: "", // Suppress the Node.js default that sets the top banner based on Node.js news.
+    head: {
+      html: [
+        // re-write the brand color for effect
+        `<style>
+          :root {
+            --color-brand-100: #f7f1fb;
+            --color-brand-200: #ead9fb;
+            --color-brand-300: #dbbdf9;
+            --color-brand-400: #c79bf2;
+            --color-brand-600: #9756d6;
+            --color-brand-700: #7d3cbe;
+            --color-brand-800: #642b9e;
+            --color-brand-900: #361b52;
+          }
+        </style>`,
+      ],
+    },
+    // use a custom logo instead of the Node.js logo
+    // our logo.jsx file like this, just for the demo
+    // export default Logo = () =>
+    //   <svg height="30" width="30" viewBox="0 0 10 10"><circle cx="5" cy="5" r="5" fill="var(--color-brand-400)"/></svg>;
+    imports: {
+      "#theme/Logo": join(import.meta.dirname, './logo.jsx'),
+    },
+  },
+};
+```
+
+Re-build the project, serve, and you'll see how quickly you can change the
+experience, preserving core functionality.
+
 ## Next steps
 
-- [Configuration](./configuration.html) — move these flags into
-  `doc-kit.config.mjs`.
-- [Customize the `web` generator](./generator-web.html) — theming, `head`, and
-  custom templating
-- [Read the full input specification](./specification.html) — the full Markdown
+- Explore [Configuration](./configuration) — consider moving your `-t` target
+  flags into a `doc-kit.config.mjs` file.
+- [Further customize the `web` generator](./generator-web) — check out more
+  customization options
+- [Read the full input specification](./specification) — the full Markdown
   contract. components.

www/pages/index.md

@@ -1,16 +1,18 @@
-# doc-kit
+# `doc-kit`
 
-doc-kit is not a general-purpose Markdown-to-output tool to structurally
-transform API documentation.
-
-`@node-core/doc-kit` is the documentation toolchain behind the Node.js API
+`doc-kit` is an opinionated Markdown parsing tool to structurally transform API
+documentation. It;s the documentation toolchain behind the Node.js API
 reference, found at https://nodejs.org/docs/latest/api/. This site is built by
-doc-kit, from its own repository. The pages you are reading were produced by the
-`web` generator.
+`doc-kit`, from its own repository. The pages you are reading were produced by
+the `web` generator.
+
+> 📣 `doc-kit` is in beta. We'd like feedback within the
+> [issue log](https://github.com/nodejs/doc-kit/issues) or by visiting the
+> [#nodejs-website Slack Channel](https://openjs-foundation.slack.com/archives/CVAMEJ4UV).
 
 ## `doc-kit` is a pipeline, not a Markdown converter
 
-doc-kit parses Markdown source files once, emitting output according to
+`doc-kit` parses Markdown source files once, emitting output according to
 configured generators. You run any subset of them in one command, customize
 their logic, or even build your own generator.
 
@@ -36,7 +38,7 @@ Only some of these are things you ask for by name. `ast`, `metadata`, and
 them, and they are not valid `-t` targets. Everything in the fan-out below
 `metadata` is a target you can pass to `-t`, and passing several at once reuses
 the one shared parse rather than repeating it. The full list is in the
-[generators reference](./generator-web.html).
+[generators reference](./generator-web).
 
 ## The input contract
 
@@ -48,11 +50,11 @@ important rule:
 > page's identity — its sidebar label and its output filename. A file without
 > one produces no page at all, and the build still exits `0`.
 
-See [the specification](./specification.html) for the full input format.
+See [the specification](./specification) for the full input format.
 
-## Start here
+## What's next
 
-- [Getting started](./getting-started.html) — render your first document.
-- [Commands](./commands.html) — the `doc-kit` CLI surface.
-- [Configuration](./configuration.html) — `doc-kit.config.mjs` reference.
-- [Creating generators](./generators.html) — extend the pipeline.
+- [Getting started](./getting-started) — render your first document.
+- [Commands](./commands) — the `doc-kit` CLI surface.
+- [Configuration](./configuration) — `doc-kit.config.mjs` reference.
+- [Creating generators](./generators) — extend the pipeline.