@inditextech/docouture-cli 0.1.0-SNAPSHOT.40.1

package/build/templates/starter/scripts/check-links.mjs

@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+'use strict'
+
+// Checks the built site (build/site) for broken links, but only ever FAILS
+// on a broken EXTERNAL (http/https) link — a raw link in content Antora
+// itself can't see, which is the whole reason this check exists (Antora's
+// own strict mode, runtime.log.failure_level: warn, already fails the build
+// on a broken xref before this script ever runs).
+//
+// A broken LOCAL link is reported as a warning, never a failure. Two
+// reasons a local link can legitimately show up BROKEN here even though
+// nothing is actually wrong:
+//
+//   1. docouture-pr-verify.yml and docouture-release.yml both build with
+//      antora-playbook.local.yml (branches: HEAD only) rather than the real,
+//      multi-source antora-playbook.yml — content generated from config
+//      rather than an xref (the module switcher, the footer, a
+//      urls.latest_version_segment alias) can point at another version or
+//      component that simply isn't part of this reduced, single-source
+//      build. Antora doesn't fail on these (they're not xrefs it resolves),
+//      but linkinator, crawling the actual rendered HTML, will.
+//   2. Any other local-link false positive linkinator produces against
+//      content Antora itself is satisfied with.
+//
+// A broken link matching an IGNORE pattern (see IGNORE_PATTERNS below) is
+// also only a warning — same reasoning, different cause: it starts with
+// http(s):// so it looks external, but it isn't a real third-party
+// dependency an author is vouching for.
+//
+// Uses linkinator's own JS API (see @inditextech/docouture-*'s own
+// devDependency on it in package.json) rather than shelling out to its CLI:
+// the CLI's own --skip flag can only exclude a link from being checked
+// altogether (see linkinator's own source, LinkChecker#crawl: a skipped URL
+// is never fetched, so it can neither be validated NOR recursed into) — it
+// cannot express "fetch and recurse through this page, just don't fail the
+// whole job over IT specifically". Classifying results after the fact, via
+// the API, is the only way to get both: a full recursive crawl of every
+// generated page (so a raw external link buried three pages deep still gets
+// found), and a pass/fail decision that only external links get to make.
+import { readFile } from 'node:fs/promises'
+import { check } from 'linkinator'
+
+const SKIP = ['^(mailto:|tel:)']
+
+// linkinator's own mapUrl() (see its src/index.ts) strips the local static
+// server's http://127.0.0.1:<port> prefix from every local result before
+// it's reported — the port is random per run, so this is the only stable
+// way to tell a local link from an external one after the fact: whatever's
+// left over either still starts with http(s):// (a real external URL) or
+// doesn't (a local one, already rewritten to a bare path).
+const isExternal = (url) => /^https?:\/\//.test(url)
+
+// A simple shell-style glob, not a regex: `*` matches any run of characters
+// (including none), `?` matches exactly one, everything else is literal —
+// most people writing "which links to ignore" think in terms of a host or a
+// path shape, not regex syntax, and a literal `.` (as in every hostname) is
+// far more likely to be meant literally than as "any character". Escapes
+// every other regex metacharacter so the rest of the string is matched
+// verbatim.
+function globToRegExp(glob) {
+  const escaped = glob.replace(/[.+^${}()|[\]\\]/g, '\\$&')
+  return new RegExp(escaped.replace(/\*/g, '.*').replace(/\?/g, '.'))
+}
+
+// `package.json`'s own "docouture" config block (see the scaffolded stub, next
+// to "docouture.publish") is this project's existing place for a local,
+// site-specific override — `docouture.checkLinks.ignore` is a list of globs
+// (see globToRegExp above), tested the same way linkinator's own
+// `--skip`/`linksToSkip` are, but warned rather than silently dropped so an
+// ignored link that starts failing for a REAL reason still shows up
+// somewhere. Scaffolded with these default entries already in it (see
+// package.json's own comment... it's JSON, so there isn't one — this is
+// that comment):
+//
+//   - `*/edit/HEAD/*` — the footer's "Propose a change" link
+//     (edit-this-page.hbs) renders `page.editUrl`, which Antora builds from
+//     whatever ref it detects checked out. docouture-pr-verify.yml and
+//     docouture-release.yml both build from a detached-HEAD checkout (a PR
+//     merge commit, or a one-off commit on top of main — see those
+//     workflows' own comments), so Antora has no real branch name to put
+//     there and falls back to the literal string `HEAD` — a path GitHub's
+//     web UI never resolves. This is deterministic, not flaky: it will be
+//     "broken" on every single PR-verify/release run of every scaffolded
+//     site, regardless of content, so it carries no signal worth failing a
+//     build over.
+//   - `https://<org>.github.io/<repo>` — getting-started.adoc's own
+//     "Publish the docs" section mentions this literal, illustrative
+//     placeholder as an example of what `site.url` should look like for a
+//     GitHub Pages project page. Asciidoctor auto-links any bare http(s)
+//     URL it finds, including inside monospace text, so this example ends
+//     up as a real (and obviously never-resolving) link in the built HTML.
+//   - this site's own repo link (repo-link.hbs renders `site.keys.repoUrl`,
+//     or absent that Antora's own `page.origin.webUrl` — same URL either
+//     way, computed by `docouture new` from `git remote get-url origin` at
+//     scaffold time; see new.ts's own repoIgnoreGlob()), shown once per page
+//     so a single broken link here would otherwise report once per page in
+//     the results. There's a real, principled reason it can 404 to an
+//     anonymous CI crawler even when nothing is actually wrong: GitHub
+//     returns 404 (not 403) for a private repo when unauthenticated,
+//     indistinguishable from one that doesn't exist, and plenty of docs
+//     sites publish before (or without ever) making their source repo
+//     public. A harmless sentinel glob that can never match a real URL
+//     fills this slot instead when there was no `origin` remote configured
+//     yet at scaffold time — never an empty string, which would silently
+//     ignore every link. Baked in once, at scaffold
+//     time, rather than recomputed here on every run: if this repo's remote
+//     is later renamed or moved, this entry goes stale along with it, the
+//     same as any other config a site owner would need to update by hand.
+async function ignorePatterns() {
+  let pkg
+  try {
+    pkg = JSON.parse(await readFile('package.json', 'utf8'))
+  } catch {
+    return []
+  }
+  const ignore = pkg?.docouture?.checkLinks?.ignore
+  return Array.isArray(ignore) ? ignore.map(globToRegExp) : []
+}
+
+const IGNORE_PATTERNS = await ignorePatterns()
+
+// An absolute link whose host is `localhost` or `127.0.0.1` — a
+// self-referential `site.url` (or similar absolute-URL config) that happens
+// to point at wherever someone's local dev server runs. That address is
+// never actually serving anything while this script runs its own,
+// unrelated throwaway static server, so the link is "broken" as a pure
+// artifact of running the check at all, not because the site's content is
+// wrong. Kept as its own structural check (not a package.json default)
+// since it applies to every site unconditionally, with nothing to
+// configure.
+const isNonRepresentative = (url) =>
+  /^https?:\/\/(localhost|127\.0\.0\.1)(:|\/|$)/.test(url) || IGNORE_PATTERNS.some((pattern) => pattern.test(url))
+
+const result = await check({
+  path: 'build/site',
+  recurse: true,
+  linksToSkip: SKIP,
+  // A plain 403/429 from a real external host (most commonly GitHub's own
+  // bot/rate-limit protection kicking in on repo links, hit repeatedly
+  // across every page of a freshly built site) can't be told apart from a
+  // genuinely dead link — linkinator's own README documents the same
+  // reasoning for its built-in 403 (Cloudflare)/999 (LinkedIn) handling.
+  // Treating these as a warning rather than a failure extends that same
+  // policy to any host, not just the two it special-cases already.
+  statusCodes: {
+    403: 'warn',
+    429: 'warn',
+  },
+})
+
+const broken = result.links.filter((link) => link.state === 'BROKEN')
+const local = broken.filter((link) => !isExternal(link.url))
+const nonRepresentative = broken.filter((link) => isExternal(link.url) && isNonRepresentative(link.url))
+const external = broken.filter((link) => isExternal(link.url) && !isNonRepresentative(link.url))
+
+for (const link of local) {
+  console.log(`::warning::local link reported broken (ignored): ${link.url} (parent: ${link.parent ?? 'unknown'})`)
+}
+
+for (const link of nonRepresentative) {
+  console.log(
+    `::warning::non-representative link reported broken (ignored — see this script's own comment): ${link.url} (parent: ${link.parent ?? 'unknown'})`
+  )
+}
+
+if (external.length > 0) {
+  for (const link of external) {
+    console.log(`::error::broken external link: ${link.url} (parent: ${link.parent ?? 'unknown'})`)
+  }
+  console.error(`\n${external.length} broken external link(s) found.`)
+  process.exit(1)
+}
+
+const ignored = local.length + nonRepresentative.length
+console.log(
+  `Checked ${result.links.length} link(s): 0 broken external link(s)` +
+    (ignored > 0 ? `, ${ignored} local/non-representative link(s) ignored (see warnings above).` : '.')
+)

package/build/templates/starter/src/antora.yml

@@ -0,0 +1,85 @@
+# Component descriptor. Every directory Antora treats as documentation needs
+# one of these. See https://docs.antora.org/antora/latest/component-version/
+#
+# `name` is either this site's own name (a real URL path segment on
+# publish) or Antora's reserved `ROOT` (contributes no segment at all) —
+# decided by the `docouture new` wizard's "extra URL path segment" question (or
+# `--url-segment`), default off/ROOT. See antora-playbook.yml's own
+# site.url comment for the full GitHub Pages URL shape either way.
+name: __DOCOUTURE_COMPONENT_NAME__
+title: __DOCOUTURE_TITLE__
+# This descriptor is identical for BOTH versioning modes — see the docouture
+# docs-site-package skill's reference/versioning-modes.md. `main` permanently
+# says `version: prerelease`, `prerelease: true`, regardless of whether this
+# site was scaffolded standalone or versioned (`docouture new --mode versioned`).
+# What differs between the two modes is only antora-playbook.yml's
+# content.sources[] tags (`stable` vs `v*`) and what a release tag's own copy
+# of this file ends up saying: standalone's `stable` tag says
+# `version: stable`, `prerelease: false`; a versioned release tag (v1.2.0,
+# ...) says `version: '1.2.0'`, `prerelease: false`. Until the first release
+# this site has just the one (prerelease) version — that is expected.
+version: prerelease
+prerelease: true
+# The site's landing page: modules/ROOT/pages/index.adoc, rendered through
+# the UI bundle's `home` layout. Naming it here (rather than relying on
+# Antora's own default) is what stops it fabricating a synthetic
+# component-root "previous" URL for the first nav entry — a page that
+# doesn't exist — which would otherwise break the pagination footer's
+# "previous" link on the very first page of the site.
+#
+# ROOT is deliberately absent from the `nav` list below: the landing is
+# reached from the header's product name and the side menu's brand block,
+# not as a row in the navigation tree, and it borrows `main`'s navigation
+# for its own side menu (`:page-nav-module: main` in that page's own header).
+start_page: ROOT:index.adoc
+nav:
+  - modules/main/nav.adoc
+
+# Per-module navigation metadata, read by @inditextech/docouture-antora-extensions
+# (registered under `antora.extensions` in the playbook) and attached to the
+# navigation trees Antora builds from the `nav` list above. It is what lets
+# the UI show one module's navigation at a time, with a switcher between
+# modules once there is more than one — this scaffold starts with a single
+# placeholder module (`main`); add another entry here, alongside a second
+# `modules/<name>/nav.adoc` in the `nav` list above, to see the switcher
+# itself appear.
+#
+# A LIST, not a map keyed by module — deliberately, and it must stay one. See
+# @inditextech/docouture-antora-extensions's own docs for why: a map's keys get
+# silently camelCased by Antora's content aggregator, which breaks any module
+# slug containing a hyphen.
+#
+# `icon` is `<group>/<name>` from the UI bundle's own vendored sprite
+# (packages/ui-bundle/src/img/icons.yml) — an icon name is not free-form.
+nav_modules:
+  - module: main
+    title: Documentation
+    description: Placeholder documentation module — replace with your own content.
+    icon: design/grid-outlined
+
+# Which module's navigation the generated 404 page's side menu shows, read
+# by @inditextech/docouture-antora-extensions. With a single module there is
+# only one sensible value; update this alongside nav_modules above if a
+# second module is added and the 404 page should point somewhere else.
+not_found_module: main
+
+# Site footer link groups (read by @inditextech/docouture-antora-extensions and
+# attached to this component version as `footer`). Authored here rather than
+# in the playbook because `site.keys` is a flat primitive map and cannot
+# carry a list.
+#
+# A footer.groups list is positional (index 0 → column 2, 1 → column 3's
+# fallback — used only when this component has fewer than two switchable
+# modules, which is the case here with just `main` above — 2 → column 4), not
+# keyed. `url` is either a page ID — the same string xref:...[] accepts — or
+# a literal URL; one that resolves to no page is dropped with a warning
+# rather than rendered dead. `title` is optional per group; omit it for a
+# column with no heading.
+footer:
+  groups:
+    - title: Resources
+      links:
+        - text: Home
+          url: ROOT:index.adoc
+        - text: Getting started
+          url: main:getting-started.adoc

package/build/templates/starter/src/modules/ROOT/pages/index.adoc

@@ -0,0 +1,124 @@
+= __DOCOUTURE_TITLE__
+:page-layout: home
+:page-nav-module: main
+:description: Replace this with a one-line description of __DOCOUTURE_TITLE__ — it feeds page metadata as well as the hero.
+:page-tags: replace, these, tags
+:page-action: Get started
+:page-action-url: main:getting-started.adoc
+:page-action-secondary: About
+:page-action-secondary-url: main:index.adoc
+:page-hero-image: hero-placeholder.png
+:page-hero-image-alt: Placeholder standing in for a product screenshot or diagram.
+
+Replace this preamble with a short lead-in for __DOCOUTURE_TITLE__ — one or two
+sentences, no heading of its own. It sits above the `Get started` row below
+and is the first thing a reader sees beside the hero.
+
+== Get started
+
+[cards,type=image-square,columns="1 s:2 m:4",width=container]
+====
+[card,subheader="Start here"]
+.xref:main:getting-started.adoc[Getting started]
+--
+image::card-placeholder.png[Placeholder card image]
+
+Add a page, build the site, publish it.
+--
+
+[card,subheader="Overview"]
+.xref:main:index.adoc[About]
+--
+image::card-placeholder.png[Placeholder card image]
+
+What this placeholder module is, and how to replace it with real content.
+--
+
+[card,subheader="Reference"]
+.xref:main:quickstart.adoc[Quickstart]
+--
+image::card-placeholder.png[Placeholder card image]
+
+The smallest path to a working result, as concrete steps.
+--
+
+[card,subheader="Design"]
+.xref:main:architecture.adoc[Architecture]
+--
+image::card-placeholder.png[Placeholder card image]
+
+Where to describe the system's major components and how they fit together.
+--
+====
+
+== Key features
+
+Replace this `[feature-tabs]` block with __DOCOUTURE_TITLE__'s own — each slide
+is a media still, a short paragraph, and an optional call to action.
+
+[feature-tabs]
+====
+[feature,label="Replace me"]
+--
+image::feature-placeholder.png[Placeholder feature image]
+image::feature-placeholder-dark.png[role=dark]
+
+Describe the first thing worth knowing about __DOCOUTURE_TITLE__ here.
+
+[.cta]
+xref:main:index.adoc[Learn more]
+--
+
+[feature,label="Replace me too"]
+--
+image::feature-placeholder.png[Placeholder feature image]
+image::feature-placeholder-dark.png[role=dark]
+
+A second slide, same shape — media, prose, an optional call to action.
+
+[.cta]
+xref:main:architecture.adoc[Learn more]
+--
+
+[feature,label="And this one"]
+--
+image::feature-placeholder.png[Placeholder feature image]
+image::feature-placeholder-dark.png[role=dark]
+
+A third slide. A slide with no call to action is fine too — it is optional.
+--
+====
+
+== Free & open source
+
+Replace or remove this `[cta]` block — a flat one-line pitch plus a single
+primary action, styled apart from the ordinary body copy above it.
+
+[cta]
+====
+Replace this with a short pitch for __DOCOUTURE_TITLE__ — why it is worth a
+reader's attention.
+
+[.primary]
+https://github.com[Replace with a real link]
+====
+
+== Frequently asked questions
+
+Replace this `[accordion]` block with __DOCOUTURE_TITLE__'s own real questions —
+this is a placeholder shape, not sample copy to keep.
+
+[accordion,aria-label="Frequently asked questions"]
+--
+.Replace this with a real question?
+[%collapsible]
+====
+Replace this with a real answer.
+====
+
+.And a second one?
+[%collapsible]
+====
+Answers can be as short or as long as the question needs.
+====
+--

package/build/templates/starter/src/modules/main/nav.adoc

@@ -0,0 +1,19 @@
+* Welcome to docouture
+* xref:main:prerequisites.adoc[Prerequisites]
+* xref:main:getting-started.adoc[Getting started]
+* xref:main:components.adoc[AsciiDoc components]
+* Overview
+* xref:main:index.adoc[About]
+* xref:main:architecture.adoc[Architecture]
+* xref:main:structure.adoc[Structure]
+* xref:main:glossary.adoc[Glossary]
+* Getting started
+* xref:main:requirements.adoc[Requirements]
+* xref:main:quickstart.adoc[Quickstart]
+* App
+* xref:main:app.adoc[Overview]
+* Additional information
+* xref:main:release-notes/index.adoc[Release notes]
+* xref:main:changelog/index.adoc[Changelog]
+* xref:main:roadmap.adoc[Roadmap]
+* xref:main:contributing.adoc[Contributing]

package/build/templates/starter/src/modules/main/pages/app.adoc

@@ -0,0 +1,5 @@
+= Overview
+
+Describe the application (or product, or API) this module documents — what
+it does, and the shape of the reference material a reader will find under
+this section as it grows.

package/build/templates/starter/src/modules/main/pages/architecture.adoc

@@ -0,0 +1,6 @@
+= Architecture
+
+Describe the system's architecture here — its major components, how they
+fit together, and the boundaries between them. A diagram is often the most
+useful thing on this page; AsciiDoc's `image::` macro embeds one from
+`modules/main/images/`.

package/build/templates/starter/src/modules/main/pages/changelog/index.adoc

@@ -0,0 +1,9 @@
+= Changelog
+
+The unabridged, commit-level record of changes — in contrast to
+xref:main:release-notes/index.adoc[Release notes], which summarizes what
+matters to users.
+
+== v0.1.0
+
+* Placeholder entry. Replace with the real changelog.