for-humanity 0.13.1 → 0.14.1

package/CHANGELOG.md

@@ -2,11 +2,36 @@
 
 ## Unreleased
 
+## 0.14.1 — 2026-10-19
+
+**Upgrade:** CLI commands, configuration, document syntax and Node.js requirements remain unchanged.
+
+**Known issue:** The intermittent Windows cursor check (`NAV-010`) fails again in CI, and its cause is being investigated. See [Maintenance](https://github.com/minu-ha/for-humanity/blob/main/content/private/maintenance.md#known-windows-check-issue).
+
+- Reorganize the documentation site into Start, Guide and Updates. Installation has its own page, Commands covers command options and troubleshooting, and the changelog is published with update instructions. The Reference and Releases pages are removed; their content is in Commands, Settings, Writing and Changelog.
+- Let the mouse wheel scroll the document over the document list and the outline when they fit on screen. Chrome previously kept the wheel inside them.
+- Restore the scroll position instantly when reloading or going back to an address with a heading, without first jumping to the heading or sliding down from the top.
+- End documents with a regular section margin instead of nearly a screen of blank space. Over the last screen, the outline steps through the remaining headings in order, and a heading opened from a link stays marked until you scroll.
+- Land anchor links with the heading at 40% of the screen height instead of near the top, and switch the outline at the same line.
+- Land anchor links in the last screen exactly where the outline switches to them, so clicking an outline entry never briefly marks another heading.
+
+## 0.14.0 — 2026-10-19
+
+**Breaking change:** Configuration now belongs in the project root. CLI paths identify a project, not a Markdown folder. Move published documents into `content/public`, local-only documents into `content/private`, and the site home into `content/README.md`; use `content.root`, `content.public` and `content.private` to customize these paths. Existing flat document folders are not automatically published. See the [migration guide](https://for-humanity.fyi/migration/). Node.js 22.12.0 or later is still required.
+
+- Focus public documentation on installation, configuration, authoring and deployment. Keep internal plans, release operations, development history and fictional project studies in local-only content.
+- Show both document collections in `dev`; build and preview only the public site in `content/dist`.
+- Preserve public document URLs and reserve `/private/` for local internal pages. Exclude internal pages, navigation data, sitemap entries and their assets from public builds.
+- Reject public references to internal Markdown, images and snippets, including raw HTML and symlink targets.
+- Move this repository's documentation to `content` and its configuration to the project root.
+- Include a reusable `template/` starter with public/private folders and document migration from flat Markdown projects.
+- Reject content-root symlinks into build output, Git metadata and installed dependencies.
+
 ## 0.13.1 — 2026-10-16
 
 **Upgrade:** CLI commands, configuration and Node.js requirements remain unchanged. Navigation scroll positions saved by older versions may reset once after upgrading.
 
-**Known issue:** The previously recorded intermittent Windows cursor check (`NAV-010`) remains deferred. See [Maintenance](https://for-humanity.fyi/maintenance/#known-windows-check-issue).
+**Known issue:** The previously recorded intermittent Windows cursor check (`NAV-010`) remains deferred. See [Maintenance](https://github.com/minu-ha/for-humanity/blob/main/content/private/maintenance.md#known-windows-check-issue).
 
 - Let Zustand persist own navigation scroll storage and hydration; remove direct storage reads, legacy layout-key compatibility and duplicate restoration helpers.
 - Validate saved navigation positions once with a shared Zod schema, discard malformed snapshots, and compare navigation data without traversing DOM links on every scroll event.
@@ -16,7 +41,7 @@
 
 **Upgrade:** Node.js 22.12.0 or later is now required; upgrade Node before installing. Existing `dev`, `build`, `preview` commands and `.mjs` configurations remain supported. To use typed configuration, replace the `.mjs` file with `for-humanity.config.ts`; keep only one configuration file per document folder. Development and preview servers bind to localhost.
 
-**Known issue:** The Windows browser check for cursor visibility after a reload (`NAV-010`) intermittently fails. The other browser checks and installed-package dev/preview checks pass; further cursor lifecycle investigation is deferred. See [Maintenance](https://for-humanity.fyi/maintenance/#known-windows-check-issue).
+**Known issue:** The Windows browser check for cursor visibility after a reload (`NAV-010`) intermittently fails. The other browser checks and installed-package dev/preview checks pass; further cursor lifecycle investigation is deferred. See [Maintenance](https://github.com/minu-ha/for-humanity/blob/main/content/private/maintenance.md#known-windows-check-issue).
 
 - Render page titles, metadata and resource tags with a request-local Unhead server instance; deduplicate links, preserve literal metadata text, and keep CSS and font loading in the initial HTML.
 - Use Citty for CLI commands and help/version output, reject unsupported options and extra paths before running, and format build results and document warnings with Consola.

package/README.md

@@ -13,122 +13,97 @@ Write Markdown. Keep the context. Share a static site.
 [![MIT](https://img.shields.io/badge/license-MIT-1111aa?style=flat-square)](https://github.com/minu-ha/for-humanity/blob/main/LICENSE)
 [![npm](https://img.shields.io/npm/v/for-humanity?style=flat-square)](https://www.npmjs.com/package/for-humanity)
 ![Node 22.12.0+](https://img.shields.io/badge/node-22.12.0%2B-444444?style=flat-square)
-![Hono JSX](https://img.shields.io/badge/Hono-JSX-444444?style=flat-square)
 ![Prototype](https://img.shields.io/badge/status-prototype-9a6400?style=flat-square)
 
-[Quick start](#quick-start) · [Guide](https://github.com/minu-ha/for-humanity/blob/main/templates/document/writing.md) · [API](https://github.com/minu-ha/for-humanity/blob/main/templates/document/api.md) · [Deployment](https://github.com/minu-ha/for-humanity/blob/main/templates/document/deployment.md) · [Korean](https://github.com/minu-ha/for-humanity/blob/main/language/README.ko.md)
+[Quick start](#quick-start) · [Guide](https://github.com/minu-ha/for-humanity/blob/main/content/public/writing.md) · [Commands](https://github.com/minu-ha/for-humanity/blob/main/content/public/commands.md) · [Deployment](https://github.com/minu-ha/for-humanity/blob/main/content/public/deployment.md) · [Korean](https://github.com/minu-ha/for-humanity/blob/main/language/README.ko.md)
 
 </div>
 
-## A little structure. Room to read.
+## Write, organize, publish
 
-- **Find your place.** Pages grouped by purpose, a reading order, a tree of contents and the current reading position.
-- **Keep the detail.** Notes for context, native disclosures for implementation details, and links that open folded sections.
-- **Show the connections.** Tables, highlighted code, official Mermaid diagrams including flowcharts, sequences and directory trees, status badges and color swatches.
-- **Share the result.** Static HTML, self-hosted fonts and a small browser script. Browser interactions stay separate from Markdown rendering.
-- **Read your way.** System-matched light and dark themes, keyboard navigation and a layout for narrow screens.
+Write Markdown with code examples, tables, images and Mermaid diagrams. Organize pages into groups and nested navigation. Use notes for context and collapsible details for longer explanations.
+
+The result is a static site with bundled fonts, light and dark themes, keyboard navigation and a layout that adapts to narrow screens.
 
 ## Quick start
 
-Node.js 22.12.0 or later and pnpm. Install the CLI in your document project:
+You need Node.js 22.12.0 or later and pnpm. In a project with a `package.json`, install the package:
 
 ```sh
-pnpm add -D --save-exact for-humanity@0.13.1
-mkdir docs
+pnpm add -D --save-exact for-humanity@0.14.1
 ```
 
-Create `docs/README.md` for the home page, then start the development server:
+Copy `for-humanity.config.ts` and the `content` folder from `node_modules/for-humanity/template` into your project. If you already have documentation, follow [Migration](https://github.com/minu-ha/for-humanity/blob/main/content/public/migration.md) before moving files.
 
-```sh
-pnpm exec for-humanity dev docs
-```
+Edit `content/README.md` for your home page:
 
-Open [localhost:4321](http://localhost:4321). Build and preview your static site:
+```markdown
+# Project notes
 
-```sh
-pnpm exec for-humanity build docs    # Generate docs/dist
-pnpm exec for-humanity preview docs
+Welcome to the project documentation.
 ```
 
-If your Markdown files are in the project root, use `.` instead of `docs`. The root `README.md` becomes the home page; root `AGENTS.md` and `CLAUDE.md` stay out of the site.
-
-Version `0.13.1` supports `dev`, `build` and `preview`. `init` is planned; see the [Roadmap](https://github.com/minu-ha/for-humanity/blob/main/templates/document/roadmap.md) and [Changelog](https://github.com/minu-ha/for-humanity/blob/main/CHANGELOG.md).
-Cloudflare Pages can host the generated site. See [Deployment](https://github.com/minu-ha/for-humanity/blob/main/templates/document/deployment.md) for the build settings.
-Set an optional public root `url` in the site configuration to generate `robots.txt` and `sitemap.xml`; projects without a URL emit neither file. See [Crawling](https://github.com/minu-ha/for-humanity/blob/main/templates/document/crawling.md).
-
-### Develop the kit
-
-Version 0.13.0 requires Node.js 22.12.0 or later. Repository development uses one Vite server with Hono, source TSX reloads and CSS HMR.
-
-To work on the CLI or read this library's guides and examples locally, run the project from source:
+Start the local server:
 
 ```sh
-git clone https://github.com/minu-ha/for-humanity.git
-cd for-humanity
-pnpm install
-pnpm dev
+pnpm exec for-humanity dev
 ```
 
-Open [localhost:4321](http://localhost:4321) to read this library's usage guides, API reference and fictional examples.
+Open [localhost:4321](http://localhost:4321). Edit the Markdown file and save to update the page. Follow [Installation](https://github.com/minu-ha/for-humanity/blob/main/content/public/installation.md) to add your first document.
+
+Build and inspect the site before deployment:
 
 ```sh
-pnpm build      # Generate templates/document/dist
-pnpm preview    # Preview the static site
-pnpm build:pages # Add Cloudflare Pages headers and a 404 page
+pnpm exec for-humanity build
+pnpm exec for-humanity preview
 ```
 
-Changes pushed to `main` update the documentation site. A stable version tag such as `v0.13.1` runs checks, publishes the package to npm, then creates a GitHub Release with the same package file.
-The npm README updates with each package release. See [Maintenance](https://github.com/minu-ha/for-humanity/blob/main/templates/document/maintenance.md#packaging-and-release) for the release steps.
+Deploy the generated `content/dist` directory and add it to `.gitignore`. See [Deployment](https://github.com/minu-ha/for-humanity/blob/main/content/public/deployment.md) for hosting settings.
+
+Keep published documents in `content/public` and local notes in `content/private`. The local server shows both; builds include only public documents and the home page. Folder names are configurable.
 
 ## Make it yours
 
-A document folder is enough to get started. Without a site configuration, the sidebar shows **for humanity**. The pixel face appears in the browser tab, and follows the mouse on desktop when the site sets `cursorFace: true`.
-The folder's `README.md` becomes the home page at `/`, with no frontmatter required. Click the site name to return home.
-This repository generates [the documentation home](https://github.com/minu-ha/for-humanity/blob/main/templates/document/README.md) from its root README.md and [the site changelog](https://github.com/minu-ha/for-humanity/blob/main/templates/document/changelog.md) from CHANGELOG.md. Edit those source files, then run `pnpm sync:docs`; `pnpm dev` and `pnpm build` also sync them on startup.
-Set your own name in `for-humanity.config.ts`, using the exported `SiteConfig` type for editor completion and static checking:
+Set the site name and the order of navigation groups:
 
 ```ts
 import type {SiteConfig} from "for-humanity";
 
 export default {
     title: "Project notes",
-    description: "Decisions, working notes and the details behind them.",
-    navigation: ["Getting started", "Guide", "Reference", "Examples"],
+    description: "A guide to using the project.",
+    navigation: ["Start", "Guide", "Updates"],
 } satisfies SiteConfig;
 ```
 
-Existing `for-humanity.config.mjs` files remain supported. When migrating to TypeScript, replace the old file with the `.ts` file.
-Use one configuration file per document folder. The CLI validates values at startup; run `tsc --noEmit` in your project for static type checking.
+Save this as `for-humanity.config.ts` in the project root, alongside `package.json`. Existing `.mjs` configuration is also supported; keep only one configuration file.
 
-See [Commands](https://github.com/minu-ha/for-humanity/blob/main/templates/document/commands.md) for using another document folder, and [Settings](https://github.com/minu-ha/for-humanity/blob/main/templates/document/settings.md) for configuration.
-Each document other than the root README chooses a `group` and optional `order`. Pages stay independent; groups do not need parent documents or nested folders. Document names may share the same first letter.
-Use `group: Guide` for one group or `group: [Projects, Example project, Research]` for nested navigation. Group paths do not change document URLs.
-Use `parent: writing` to place a document below another document in the same group. File-relative references such as `parent: ./readme` also work. Parent pages remain clickable and each page keeps its own URL; see [Navigation](https://github.com/minu-ha/for-humanity/blob/main/templates/document/navigation.md).
+Each document declares a title, description and navigation group in frontmatter. See [Writing](https://github.com/minu-ha/for-humanity/blob/main/content/public/writing.md) for a complete example and [Settings](https://github.com/minu-ha/for-humanity/blob/main/content/public/settings.md) for available options.
 
-## Write with context
+## Keep useful detail
 
 ```markdown
-:::note[Scope]
-What this document covers and what still needs a decision.
+:::note[Before you start]
+Check the requirements before following the steps.
 :::
 
-:::details[Implementation]
-The contract, code or reasoning behind the visible result.
+:::details[More information]
+Add examples or explanations readers can open when needed.
 :::
 ```
 
-[Parts](https://github.com/minu-ha/for-humanity/blob/main/templates/document/parts.md) pairs source examples with their rendered results. The [Design example](https://github.com/minu-ha/for-humanity/blob/main/templates/document/blueprint.md) uses a fictional reading-list app to show a screen flow, decisions, open questions and illustrative API contracts.
+[Parts](https://github.com/minu-ha/for-humanity/blob/main/content/public/parts.md) shows the syntax alongside its rendered output.
 
 ## Documentation
 
-| Group | Read |
-| ----- | ---- |
-| Getting started | [Commands](https://github.com/minu-ha/for-humanity/blob/main/templates/document/commands.md) · [Deployment](https://github.com/minu-ha/for-humanity/blob/main/templates/document/deployment.md) |
-| Guide | [Writing](https://github.com/minu-ha/for-humanity/blob/main/templates/document/writing.md) · [Parts](https://github.com/minu-ha/for-humanity/blob/main/templates/document/parts.md) · [Settings](https://github.com/minu-ha/for-humanity/blob/main/templates/document/settings.md) |
-| Reference | [API](https://github.com/minu-ha/for-humanity/blob/main/templates/document/api.md) |
-| Releases | [Official releases](https://github.com/minu-ha/for-humanity/blob/main/templates/document/releases.md) · [Changelog](https://github.com/minu-ha/for-humanity/blob/main/templates/document/changelog.md) |
-| Examples | [Fictional design example](https://github.com/minu-ha/for-humanity/blob/main/templates/document/blueprint.md) |
-| Development | [Architecture](https://github.com/minu-ha/for-humanity/blob/main/templates/document/architecture.md) · [Design](https://github.com/minu-ha/for-humanity/blob/main/templates/document/design.md) · [Maintenance](https://github.com/minu-ha/for-humanity/blob/main/templates/document/maintenance.md) · [Roadmap](https://github.com/minu-ha/for-humanity/blob/main/templates/document/roadmap.md) |
+| Task | Guide |
+| --- | --- |
+| Install and run | [Installation](https://github.com/minu-ha/for-humanity/blob/main/content/public/installation.md) · [Commands](https://github.com/minu-ha/for-humanity/blob/main/content/public/commands.md) |
+| Write and organize pages | [Writing](https://github.com/minu-ha/for-humanity/blob/main/content/public/writing.md) · [Navigation](https://github.com/minu-ha/for-humanity/blob/main/content/public/navigation.md) |
+| Add rich content | [Parts](https://github.com/minu-ha/for-humanity/blob/main/content/public/parts.md) · [Diagrams](https://github.com/minu-ha/for-humanity/blob/main/content/public/diagrams.md) · [Images](https://github.com/minu-ha/for-humanity/blob/main/content/public/images.md) |
+| Configure the site | [Settings](https://github.com/minu-ha/for-humanity/blob/main/content/public/settings.md) |
+| Publish | [Deployment](https://github.com/minu-ha/for-humanity/blob/main/content/public/deployment.md) · [Crawling](https://github.com/minu-ha/for-humanity/blob/main/content/public/crawling.md) |
+| Update | [Changelog](https://github.com/minu-ha/for-humanity/blob/main/content/public/changelog.md) · [Migration](https://github.com/minu-ha/for-humanity/blob/main/content/public/migration.md) |
 
 ## License