Report Bug · Request Feature diff --git a/RULES.md b/RULES.md index f08a39c..da305dd 100644 --- a/RULES.md +++ b/RULES.md @@ -35,14 +35,14 @@ ## Creator (owned orgs) - Transfers: `gh api`. - Config: SDL (`.sdl`) for DevCentr-owned / `sdlang-d` surfaces; **KDL** (`.kdl`) for greenfield outside that stack; JSON5 when stuck in the JSON family. Do **not** adopt Extended SDL/XDL. -- Changelog: every project; README links to it; timeline + `changelog-details/date - title`. +- Changelog: every project; functional changes; README links to it; index + `changelog-details/date - title`; backfill from git if missing; wire into docs; alert user if cross-org secrets are required. ## Docs - Structure: Diátaxis (tutorials, how-to, explanation, reference). -- Format: AsciiDoc unless host requires Markdown (e.g. npm). -- Antora: follow `dev-centr` publishing guidance. +- Format: AsciiDoc by default; retain Markdown on upstream forks; keep/add Markdown when a package registry only parses Markdown. +- Antora: Valentus theme + org branding; Lunr + `antora-supplemental` AI search (`antora-search-chat`); follow `dev-centr` publishing guidance. If those extensions cannot be found, alert the user and wait. - **One Antora site per org** with a hub (e.g. docs.devcentr.org): wire `docs/` into the hub playbook; never publish a second Antora site on project GitHub Pages. Deduplicate errant sites. See `general/antora-docs-sites.md`. (Does not apply to mixing Antora with other docs systems.) -- **Public README layout:** when creating/revising GitHub-facing READMEs, follow `general/readme-layout.md` (Best-README adapted: linked badges, centered header, role-grouped Built With, back-to-top). Hand-edit per repo; blanks in `dev-centr/readme-template`. +- **Public README layout:** when creating/revising GitHub-facing READMEs, follow `general/readme-layout.md` (Best-README adapted: centered for-the-badge chrome, **Explore the docs »** → org hub, TOC if >3 sections, role-grouped Built With, back-to-top). Do not add Docs/CI shields that break the established look. Hand-edit per repo; blanks in `dev-centr/readme-template`. - Titles: follow site `STYLE.adoc` / `AGENTS.md` (not MEMORIES). Short defaults — first-party news omits org; action essays pass implied [On] and drop surplus *the*; prefer `X as Y` / *when* / disproof / questions over rigid `X is Y`; attach floating modifiers to an object; docs topics = concept names. Philosophy: `Titles as orientation`. Cursor rules = `.cursor/rules/*.mdc` dir; this file stays the paste preamble. - Project facts: `AGENTS.md` + README/docs. Do not commit per-repo `MEMORIES.md`. - **App shipping architecture:** when scaffolding/building/shipping apps, read `general/app-architecture.md` and adhere to Software Product Essentials under `$CODE_ROOT/github.com/dev-centr/general-knowledge/docs/modules/ROOT/pages/explanation/architecture/` (hub: `software-product-essentials.adoc`). About/build info, debug dump, Windows auto-update, installers, and CI release pipelines are core—not polish. diff --git a/general/antora-docs-sites.md b/general/antora-docs-sites.md index 76ae515..831cfbf 100644 --- a/general/antora-docs-sites.md +++ b/general/antora-docs-sites.md @@ -36,3 +36,8 @@ When you find a secondary Antora site in an Antora org: - Repo-local `antora-playbook.yml` for **developer preview** of one component is fine if it does **not** get published as an org-facing site. - Production publish path for Dev-Centr Antora components is always the `dev-centr/docs` aggregator. + +## Default UI and search + +- Prefer **Valentus** (`antora-supplemental/valentus-theme`) with org brand colors/logo from the org’s central assets. +- Every published site: `@antora/lunr-extension` plus the AI search/help extension from `antora-supplemental` (`antora-search-chat`; see also `antora-ai-help-extension`). Details in `general/documentation.md`. diff --git a/general/creator.md b/general/creator.md index 7edbb1a..2591d6e 100644 --- a/general/creator.md +++ b/general/creator.md @@ -16,7 +16,9 @@ Do not apply these rules to third-party open-source contributions unless explici ## Changelogs -- When you create a project, integrate a changelog into its docs. If it lacks docs, put the changelog in the repo base. +- All **functional** changes should appear in the changelog. Prefer the project’s existing changelog style when one exists (`general/global.md`). +- When you create a project, integrate a changelog into its docs (or docs substructure for an existing documentation system). If it lacks docs, put the changelog in the repo base. - Put a link to the changelog in the README in a Changelog section. -- The changelog should contain a timeline with quick summaries and links to very detailed changelogs for each date in a `changelog-details` subfolder that names files by `date - title`. -- If you add docs afterward, update its changelog structure. +- Structure: an index page named **changelog** (timeline of dates + short summaries + links) and detail pages under `changelog-details/` named `date - title`. Wire the changelog into the active docs system (Antora nav, etc.) when docs exist. +- If no changelog exists, **create it** and **backfill** from observed functional changes in git history. Unpack commits when the subject line is too thin. +- Wiring may require commits in **related** repositories (e.g. org docs hub playbook). If any of those repos cross **org** boundaries and CI/docs fetch needs auth, **alert the user** that a cross-repo deploy key or org/repo secret must be added (say which secret and which org/repo). diff --git a/general/documentation.md b/general/documentation.md index 66b9e23..ecc749e 100644 --- a/general/documentation.md +++ b/general/documentation.md @@ -9,8 +9,11 @@ Read this file when you **author, structure, or publish** project documentation ## Antora (when used) +- **Default stack:** Antora + **Valentus** UI (`antora-supplemental/valentus-theme`). Customize colors and logo from the org’s existing brand assets (org `.github` profile, eponymous site repo, or other central branding repo)—do not invent a one-off palette per component. - If the project uses **Antora**, follow the publishing and layout guidance in the Dev-Centr documentation repository: `dev-centr/devcentr` — see `docs/modules/publishing/pages/antora-deployment.adoc` for deployment-oriented details. -- **One Antora site per org** that already has a hub (e.g. https://docs.devcentr.org). Do not publish secondary per-repo Antora sites on GitHub Pages. Keep `docs/` in the product repo; **wire** into the hub playbook. See `general/antora-docs-sites.md`. Actively deduplicate when you find errant sites. Does **not** apply to mixtures of different docs systems (Antora + Fumadocs is fine). +- **One Antora site per org** that already has a hub (e.g. https://docs.devcentr.org). Do not publish secondary per-repo Antora sites on GitHub Pages. Keep `docs/` in the product repo; **wire** into the hub playbook. See `general/antora-docs-sites.md`. Actively deduplicate when you find errant sites. Does **not** apply to mixtures of different docs systems (Antora + Fumadocs is fine). Repo-local `antora-playbook.yml` for **preview/validation CI** is fine if it does **not** publish a second public site. +- **Search:** Enable `@antora/lunr-extension` on every published Antora site. Add the AI-assisted search/help layer from **`antora-supplemental`** — prefer [`@antora-supplemental/antora-search-chat`](https://github.com/antora-supplemental/antora-search-chat) (Lunr-first Search/Ask omnibox). Related: [`antora-ai-help-extension`](https://github.com/antora-supplemental/antora-ai-help-extension). Register Lunr before wrappers that depend on it. +- If `antora-supplemental` (or those extensions) cannot be found after a reasonable search (rename/move), **stop and alert the user** (email, Slack, or whatever channel is available) so they can notify whoever owns this automation rule — then wait for a reply before inventing a substitute. ## Relationship to creator rules diff --git a/general/global.md b/general/global.md index e3dac59..fba6e71 100644 --- a/general/global.md +++ b/general/global.md @@ -35,6 +35,8 @@ These apply universally unless a profile says otherwise. - If `ENVIRONMENT` is missing, ask the user which file applies before assuming an OS. - You **must** read `general/creator.md` before acting. - Read `general/documentation.md` when you are authoring, structuring, or publishing project documentation (optional layer for doc-heavy work). +- Read `general/antora-docs-sites.md` when the task involves Antora sites, playbooks, GitHub Pages for docs, or wiring components into an org docs hub. +- Read `general/readme-layout.md` when creating or revising a GitHub-facing README. - Read `general/app-architecture.md` when you are scaffolding, building, shipping, packaging, or maintaining an application, CLI, TUI, publishable library, game client, or service (optional layer; points at local Software Product Essentials docs). ## Memory management diff --git a/general/readme-layout.md b/general/readme-layout.md index c0f716e..e389a3b 100644 --- a/general/readme-layout.md +++ b/general/readme-layout.md @@ -2,11 +2,28 @@ Read this when creating or revising a **GitHub-facing** `README.md` / `README.adoc` for owned or org repos. Structure inspiration: [othneildrew/Best-README-Template](https://github.com/othneildrew/Best-README-Template). Canonical blanks: [dev-centr/readme-template](https://github.com/dev-centr/readme-template) (fork to other orgs / personal profile as needed). -Do **not** batch-script README rewrites across repos. Hand-edit each file so stack grouping, contact, and omitted sections stay accurate. +Do **not** batch-script README rewrites across repos. Hand-edit each file so stack grouping, contact, and omitted sections stay accurate. Not every repo needs the full template — omit fields that will never apply (e.g. no logo). That template assumes the repo is a project hub; lighter repos stay simpler. + +## Format choice + +| Situation | README format | +|-----------|----------------| +| **Default (owned / first-party)** | Prefer **AsciiDoc** (`README.adoc`). On GitHub, use embedded HTML for the centered title/header; use `[.text-center]` (or HTML) for other centered blocks. | +| **Fork of an upstream project** | **Retain Markdown** if upstream is Markdown. Do not convert away from the fork’s face format. | +| **Package registry that only parses Markdown** (npm, crates.io listing copy, etc.) | Keep or add a **Markdown** README (or registry-facing copy) for the registry. Do **not** delete a Markdown copy that exists for that reason. Deep docs may still be AsciiDoc/Antora. | +| **Major user-facing + Best-README HTML centering** | GitHub’s AsciiDoc subset centers poorly; **`README.md`** as the repo face is fine (deep docs under `docs/`). | + +## Docs link (org repos) + +For **organization** repositories with a README: include an **Explore the docs »** text link in the centered header (same pattern as `dev-centr/readme-template` / `switchyard`), pointing at the **org docs hub** component URL (e.g. `https://docs.devcentr.org/
`** — GitHub often does **not** resolve `[![x][shield]][url]` inside HTML blocks, so badges appear to link only to the image (or nowhere useful). **In the centered header, use HTML:** `
`.
3. **AsciiDoc `env-github` trap** — Do **not** strip `link=` under `ifdef::env-github[]`. Prefer HTML `![]()
` on GitHub, or always keep `link=` on `image:` macros.
4. **Centering** — One centered block for **badges + title + one-liner + quick links**. Title-only centering with badges left above is incomplete.
@@ -17,11 +34,13 @@ Do **not** batch-script README rewrites across repos. Hand-edit each file so sta
| Audience | Layout |
|----------|--------|
-| **User-facing / downstream** (apps, installable CLIs, public libs, product sites) | Full: centered header, linked shields, structured Built With, TOC, section back-to-top, Contact, optional contrib.rocks |
+| **User-facing / downstream** (apps, installable CLIs, public libs, product sites) | Full: centered header (contributors/forks/stars/issues/license as applicable), **Explore the docs »** → hub when docs exist, structured Built With, TOC when >3 sections, section back-to-top, Contact, optional contrib.rocks |
| **Internal / non-downstream** | Simplified: linked shields + short About + install/usage if needed + License/Contact. Skip LinkedIn, empty Roadmap/Acknowledgments, contrib.rocks, demo marketing links |
| **Skip** | School repos, org `.github` profiles, archived, package-tap / registry-instruction-only, empty repos |
-Prefer keeping `README.adoc` when the repo is AsciiDoc-native **except** major user-facing repos that need Best-README HTML centering: GitHub’s AsciiDoc subset does not center like Markdown. For those, use **`README.md`** as the repo face (deep docs stay under `docs/`).
+## Table of contents
+
+Include a TOC when the README has **more than three** sections (collapsible `
```
-Omit license badge / demo / docs links when absent. Collapsible TOC via ``.
3. **AsciiDoc `env-github` trap** — Do **not** strip `link=` under `ifdef::env-github[]`. Prefer HTML `` is fine on Markdown).
## Markdown header (required shape)
@@ -39,7 +58,7 @@ Prefer keeping `README.adoc` when the repo is AsciiDoc-native **except** major u
project_description
- Explore the docs »
+ Explore the docs »
View Demo
@@ -51,7 +70,7 @@ Prefer keeping `README.adoc` when the repo is AsciiDoc-native **except** major u
` is fine.
+Omit license / demo / docs links when absent. Point **Explore the docs** at the org hub component URL when the org has a docs site. Collapsible TOC via `
` is fine when the README has more than three sections.
### Built With (outside the HTML header)