pterodoc 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,126 @@
+# Changelog
+
+## 0.2.0
+
+### Changed
+
+- Split into an npm workspace of four packages: `@pterodoc/core` (rendering, the site
+  model, the target contract, configuration and the reconciler), `@pterodoc/docusaurus`
+  (the site loader and its readers), `@pterodoc/wordpress` (the REST target) and
+  `pterodoc` (the command line, the Docusaurus build plugin and the public barrel).
+  The dependency graph points inwards and npm enforces it. The public surface of
+  `pterodoc` is unchanged, `pterodoc/plugin` still resolves, and the goldens still match
+  byte for byte.
+- The site model, the page tree, the `SourceReader` contract and model capture moved out
+  of the Docusaurus layer: they describe what a source produces, not how Docusaurus
+  produces it. `pterodoc --model` and every fixture-driven test now resolve without
+  Docusaurus in the graph at all.
+- The command line and the Docusaurus plugin build the target through one
+  `resolveTarget`, rather than each spelling out the same options. The plugin also
+  accepts a `target` of its own.
+- The version is stamped into the build instead of found by walking up the tree looking
+  for a manifest, which under a workspace would have found the wrong one and silently
+  reported `0.0.0`.
+- Installing from a git URL is no longer supported; install `pterodoc` from npm.
+
+### Added
+
+- A WordPress plugin, in `packages/wordpress/plugin`, that turns the pages
+  pterodoc publishes into a documentation experience: a full-width layout with
+  prose kept to a comfortable measure while code and tables run to the column
+  edge, syntax highlighting and a copy button, a sidebar that collapses to the
+  section being read and scrolls on its own, a bottom sheet or drawer on small
+  screens, and tables that scroll inside their own keyboard-reachable region.
+
+  It registers no block types. Everything is layered over the core blocks
+  pterodoc already writes, through `render_block` filters, one stylesheet and one
+  script — so deactivating it leaves documentation that is still readable and
+  still navigable. Site-wide defaults live on a settings page; any single block
+  can override them from the block inspector.
+
+  Its design is built on the block supports rather than around them. Every token
+  resolves through a theme's own global-styles variables first, syntax colours
+  are derived with `color-mix` from the code block's resolved colours so a
+  palette choice repaints them to match, the gutter is padding on the column
+  rather than on any block so `spacing` composes, and every default sits inside
+  `:where()` so anything set in the inspector wins. There is no `!important` in
+  the stylesheet.
+
+- `render.blocks`, either `'core'` (the default, and byte-for-byte what pterodoc
+  emitted before) or `'plugin'`. The second carries instructions the plugin can
+  act on in block-comment attributes only, never in markup, so WordPress stores
+  the same content either way and the editor has nothing to object to.
+
+- Highlighted line ranges survive when `render.blocks` is `'plugin'`. A
+  `{1,3-5}` on a fence had no core equivalent and was reported as dropped; it is
+  now carried and rendered.
+
+- `pterodoc doctor` reports whether the plugin is installed, and warns when its
+  class prefix disagrees with `render.classPrefix` — a mismatch that otherwise
+  publishes cleanly, loads cleanly and silently styles nothing.
+
+### Fixed
+
+- `pterodoc/plugin` shipped an `exports` entry pointing at a declaration file that is not
+  where tsc emits one, so the subpath resolved to `any` for every consumer.
+- `@types/mdast`, `@types/hast` and `@types/github-slugger` were development
+  dependencies, but the emitted declarations refer to those types; they are now real
+  dependencies of `@pterodoc/core`.
+- The fake WordPress used by the tests set `title` twice in one object literal, so the
+  first was always dead. Typechecking the test suites, which nothing did before, found
+  it.
+- Six tests asserted POSIX absolute paths and could not pass on Windows, where
+  `path.resolve` prepends the drive letter. They now build their fixtures with `path`.
+
+### Removed
+
+- `remark-emoji`, which was declared as a dependency and never imported.
+
+## 0.1.0
+
+### Added
+- Project skeleton: TypeScript sources, a Rollup build emitting `lib/`, declarations from
+  `tsc`, and a `prepare` script so the package can be consumed straight from git.
+- Errors and exit codes, structured issues, path, hash and media-type helpers.
+- The renderer: markdown to Gutenberg blocks, with a configurable class prefix and string
+  table so the output is not tied to one site's theme. Verified byte-identical to the
+  DocStack script it was extracted from on a shared fixture.
+
+- The site model, read from Docusaurus itself through its own site loader: resolved
+  sidebars with autogenerated entries already expanded, versions, locales, permalinks,
+  draft and unlisted flags, and previous/next links. pterodoc never walks a docs
+  directory or parses a sidebar file.
+- The page tree, ordered by the sidebar, with directory pages named by their category.
+- Model capture, so a site can be rendered without Docusaurus and a bug can be reported
+  reproducibly.
+
+- The WordPress target: page creation and updates identified by parent and slug, so a
+  re-run rewrites only what differs; media upload keyed by content hash; pruning that
+  trashes rather than deletes.
+- The reconciler, the configuration file and the command line (`sync`, `render`,
+  `doctor`, `capture`, `init`), with rendered pages, a manifest and a plan written for
+  every run.
+
+- MDX: imports and comments are removed, `Tabs` and `TabItem` become collapsible
+  sections that need no script, `Details`, `CodeBlock` and `Admonition` become their
+  block equivalents, and plain HTML is carried through. A component or an expression
+  with no equivalent is reported with its file, line and column rather than dropped.
+
+- Images: references are found wherever they sit, resolved against the document, the
+  localised copy, the static directories or `@site/`, uploaded to the media library and
+  rewritten. A file is identified by the hash of its contents, carried in its media slug,
+  so a fresh checkout never uploads anything twice.
+- Versions and locales, each published into its own subtree with its own navigation.
+- A Docusaurus plugin, for a site that would rather publish from `postBuild`.
+
+### Fixed
+Carried over from the original script, each with a test:
+- Reference-style links (`[text][ref]`) resolve instead of printing as literal text, and
+  the definitions no longer appear on the page.
+- Images are found wherever they sit, so a standalone image becomes an image block and an
+  inline one stays inline. Their URLs and alt text are escaped.
+- Shortcode brackets are escaped on the tree rather than by pattern-matching the HTML, so
+  a `>` inside an attribute no longer confuses the escaper.
+- A leading H1 is recognised as the title even when a comment precedes it.
+- Code fences keep their `title` and `showLineNumbers`; a dropped highlight range is
+  reported rather than lost in silence.

package/LICENCE.md

@@ -0,0 +1,10 @@
+Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0)
+
+Copyright (c) Onyx <hello@onyx.ac> (https://onyx.ac)
+
+This work is licensed under the Creative Commons Attribution-ShareAlike 4.0
+International License. You are free to share and adapt this work, including
+commercially, provided you give appropriate attribution and distribute any
+derivative works under the same license.
+
+Full legal text: https://creativecommons.org/licenses/by-sa/4.0/legalcode

package/README.md

@@ -0,0 +1,128 @@
+<div align="center">
+
+# pterodoc
+
+**Your documentation, where people actually find it.**
+
+Publishes a Docusaurus site to WordPress as a tree of native Gutenberg pages, so the
+docs you write once are indexed under your own domain without being rewritten by hand.
+
+[Install](#install) · [Usage](#usage) · [Configuration](#configuration) · [How it works](#how-it-works) · [Plugin](#the-wordpress-plugin) · [Status](#status)
+
+</div>
+
+---
+
+## What is it?
+
+A one-way publisher. Docusaurus stays the source of truth; WordPress becomes a mirror.
+Every page it writes is real Gutenberg block markup — headings, lists, tables, code,
+admonitions, images — so the result is editable in WordPress rather than a wall of
+embedded HTML.
+
+It does not invent its own idea of your site. It asks Docusaurus, using Docusaurus's own
+loader, which means resolved sidebars (autogenerated ones included), versions, locales,
+draft and unlisted flags, permalinks and previous/next links all come from the same code
+that builds your site.
+
+## Install
+
+```console
+npm install --save-dev pterodoc
+```
+
+pterodoc runs inside a Docusaurus project and expects `@docusaurus/core` to be present.
+It pulls in `@pterodoc/core`, `@pterodoc/docusaurus` and `@pterodoc/wordpress`, which are
+published in lockstep with it.
+
+Installing from a git URL is not supported: the repository is an npm workspace, and a git
+install would pack only its private root.
+
+## Usage
+
+```console
+npx pterodoc render                 # render every page locally; contacts nothing
+npx pterodoc sync --dry-run         # say what would change on the site
+npx pterodoc sync                   # create and update
+npx pterodoc sync --prune           # also trash pages whose document is gone
+npx pterodoc doctor                 # check config, credentials and permissions
+```
+
+Credentials come from the environment, never from the config file:
+
+```console
+export WP_URL=https://example.com
+export WP_USER=someone
+export WP_APP_PASSWORD='xxxx xxxx xxxx xxxx'   # Users → Profile → Application Passwords
+```
+
+Without them every command still renders, and reports what it would have done.
+
+## Configuration
+
+`pterodoc.config.mjs` beside your Docusaurus config:
+
+```js
+import { defineConfig } from 'pterodoc';
+
+export default defineConfig({
+  site: { sidebars: ['docs'], versions: 'last', locales: 'default' },
+  target: { type: 'wordpress', root: '/docs' },
+});
+```
+
+Anything Docusaurus already knows — the site URL, base URL, route base path, locales,
+markdown format, admonition keywords — is read from your Docusaurus config and is not
+repeated here.
+
+## How it works
+
+Pages mirror your documentation URLs, so `/docs/guides/sync` on Docusaurus becomes
+`/<root>/guides/sync/` on WordPress. A directory becomes a page of its own, titled by its
+sidebar category. A page is identified by its parent and its slug, so re-running only
+rewrites what actually differs, and a second run reports everything as unchanged.
+
+## The WordPress plugin
+
+Optional, and worth installing. pterodoc writes ordinary core blocks, which are
+correct but plain: no syntax highlighting, tables that overflow, a sidebar that
+is a bare expanded list. The plugin in `packages/wordpress/plugin` styles them.
+
+It registers no block types, so nothing about your content becomes dependent on
+it. Deactivate it and the documentation is still there, still readable, still
+navigable.
+
+```console
+npm run --workspace @pterodoc/wp-plugin build   # writes pterodoc.zip
+```
+
+Upload that under Plugins, Add New, Upload Plugin. Defaults live at Settings,
+pterodoc; any single block can override them from the block inspector.
+
+Two things to know. Its class prefix must match `render.classPrefix` — set it on
+the settings page, which needs no re-publishing; `pterodoc doctor` says whether
+the two agree. And because a sync rewrites a page's content, an override set on a
+block in the WordPress editor is replaced the next time that page is published:
+the settings page is the durable place for a preference.
+
+Once it is installed, `render.blocks: 'plugin'` lets pterodoc carry instructions
+core blocks cannot express — chiefly a fence's highlighted line range, which is
+otherwise reported as dropped. It travels in the block comment rather than in
+markup, so WordPress stores the same content either way.
+
+## Status
+
+Working, and published.
+
+The publisher has been verified against a real 47-page documentation set: rendering
+matches the script it was extracted from on 42 of those pages, and every one of the
+remaining five differs only where pterodoc is now correct.
+
+Not yet exercised against a site that uses them: versions, locales, and the Docusaurus
+build plugin. The WordPress plugin is newer still — its PHP and JavaScript are checked in
+CI and its markup decisions are covered by tests on the publisher's side, but its
+behaviour in a browser has not been through a release on a live site.
+
+## Licence
+
+CC-BY-SA-4.0. See LICENCE.md.

package/bin/pterodoc.mjs

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+// Shipped unbuilt so the entry point stays readable and stable.
+import { main } from '../lib/cli/run.js';
+
+process.exitCode = await main(process.argv.slice(2));

package/lib/chunks/target-BC_VOAlJ.js

@@ -0,0 +1,38 @@
+import { createWordpressTarget } from '@pterodoc/wordpress';
+
+/**
+ * Build the target a run publishes to.
+ *
+ * Both entry points — the command line and the Docusaurus plugin — need the
+ * same object built the same way, and having built it in two places once
+ * already, the copies drifted apart in how they spelled the URL policy.
+ */
+/**
+ * Build the configured target.
+ *
+ * Always built, even offline: the target decides what a page's URL is, and a
+ * render with the wrong URLs is worse than no render at all. Only opening a
+ * session needs credentials.
+ *
+ * @param config The resolved configuration.
+ */
+function resolveTarget(config) {
+    return createWordpressTarget({
+        url: config.targetUrl,
+        user: config.user,
+        appPassword: config.appPassword,
+        policy: {
+            rootSegments: config.rootSegments,
+            baseSegments: config.baseSegments,
+        },
+        status: config.status,
+        template: config.template,
+        lang: config.lang,
+        mediaSlugPrefix: config.mediaSlugPrefix,
+        methodOverride: config.methodOverride,
+        retry: config.retry,
+    });
+}
+
+export { resolveTarget as r };
+//# sourceMappingURL=target-BC_VOAlJ.js.map

package/lib/chunks/target-BC_VOAlJ.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"target-BC_VOAlJ.js","sources":["../../src/target.ts"],"sourcesContent":[null],"names":[],"mappings":";;AAAA;;;;;;AAMG;AAKH;;;;;;;;AAQG;AACG,SAAU,aAAa,CAAC,MAAsB,EAAA;AAClD,IAAA,OAAO,qBAAqB,CAAC;QAC3B,GAAG,EAAE,MAAM,CAAC,SAAS;QACrB,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,WAAW,EAAE,MAAM,CAAC,WAAW;AAC/B,QAAA,MAAM,EAAE;YACN,YAAY,EAAE,MAAM,CAAC,YAAY;YACjC,YAAY,EAAE,MAAM,CAAC,YAAY;AAClC,SAAA;QACD,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,eAAe,EAAE,MAAM,CAAC,eAAe;QACvC,cAAc,EAAE,MAAM,CAAC,cAAc;QACrC,KAAK,EAAE,MAAM,CAAC,KAAK;AACpB,KAAA,CAAC;AACJ;;"}

package/lib/cli/args.d.ts

@@ -0,0 +1,26 @@
+/** Command line parsing and the usage text. */
+import type { ConfigFlags } from '@pterodoc/core';
+/** Commands the CLI accepts. */
+export declare const COMMANDS: readonly ["sync", "render", "doctor", "capture", "init"];
+/** One of the commands. */
+export type Command = (typeof COMMANDS)[number];
+/** The help text. */
+export declare const USAGE = "Publish a Docusaurus site to WordPress as a tree of pages.\n\nUsage: pterodoc <command> [options]\n\nCommands\n  sync        Reconcile the target with the site. The default.\n  render      Render every page to the output directory; contacts nothing.\n  doctor      Check the configuration, the credentials and the target.\n  capture     Write the loaded site model to a JSON file.\n  init        Write a starter pterodoc.config.mjs.\n\nSource\n  --site-dir <dir>            Docusaurus site directory (default: the working directory).\n  --config <file>             pterodoc config file.\n  --docusaurus-config <file>  Explicit docusaurus.config.* path.\n  --model <file>              Use a captured model; Docusaurus is never loaded.\n  --instance <id>             Docs plugin instance. Repeatable.\n  --locale <code>             Locale to publish. Repeatable.\n  --all-locales               Publish every locale the site declares.\n  --docs-version <name>       Version to publish. Repeatable.\n  --all-versions              Publish every version.\n\nTarget\n  --root <path>               Path the documentation hangs from.\n  --base <segment>            Segment below the root (\"\" publishes under the root).\n  --status <status>           publish, draft or private.\n  --only <prefix>             Restrict writes to pages under <prefix>.\n  --dry-run                   Plan and render, change nothing.\n  --prune                     Trash pages with no source document.\n  --offline                   Render only; never open a session.\n  --no-media                  Skip uploads; leave image URLs as written.\n\nOutput\n  --out <dir>                 Output directory (default <site-dir>/.pterodoc).\n  --capture <file>            Also write the site model to <file>.\n  --env-file <file>           Read this .env file. None is read otherwise.\n  --strict                    Fail when an issue reaches the configured severity.\n  --json                      Print a machine-readable summary.\n  --verbose                   Log every page as it is processed.\n  --quiet                     Only print errors.\n  --help, --version\n\nCredentials come from the environment: WP_URL, WP_USER, WP_APP_PASSWORD.\nWithout them every command still renders and reports what it would have done.";
+/** Flags after parsing. */
+export interface ParsedArgs {
+    command: Command;
+    flags: ConfigFlags;
+    capture: string | undefined;
+    json: boolean;
+    verbose: boolean;
+    quiet: boolean;
+    help: boolean;
+    version: boolean;
+}
+/**
+ * Parse the command line.
+ *
+ * @param argv Arguments after the executable and script name.
+ */
+export declare function parseCliArgs(argv: string[]): ParsedArgs;
+//# sourceMappingURL=args.d.ts.map

package/lib/cli/args.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../../src/cli/args.ts"],"names":[],"mappings":"AAAA,+CAA+C;AAI/C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAElD,gCAAgC;AAChC,eAAO,MAAM,QAAQ,0DAA2D,CAAC;AAEjF,2BAA2B;AAC3B,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC;AAEhD,qBAAqB;AACrB,eAAO,MAAM,KAAK,ovEA2C4D,CAAC;AAE/E,2BAA2B;AAC3B,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,WAAW,CAAC;IACnB,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CAmFvD"}

package/lib/cli/reporter.d.ts

@@ -0,0 +1,23 @@
+/**
+ * What the user sees.
+ *
+ * GitHub Actions gets annotations it can surface on the run; a terminal gets
+ * something readable.
+ */
+import { type Issue } from '@pterodoc/core/util';
+import type { Plan } from '@pterodoc/core';
+/** How output is presented. */
+export interface Reporter {
+    info(message: string): void;
+    detail(message: string): void;
+    issue(issue: Issue): void;
+    summary(plan: Plan): void;
+}
+/** Build a reporter. */
+export declare function createReporter(options: {
+    verbose?: boolean;
+    quiet?: boolean;
+    json?: boolean;
+    env?: NodeJS.ProcessEnv;
+}): Reporter;
+//# sourceMappingURL=reporter.d.ts.map

package/lib/cli/reporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reporter.d.ts","sourceRoot":"","sources":["../../src/cli/reporter.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAe,KAAK,KAAK,EAAiB,MAAM,qBAAqB,CAAC;AAC7E,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAE3C,+BAA+B;AAC/B,MAAM,WAAW,QAAQ;IACvB,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IAC1B,OAAO,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAAC;CAC3B;AAED,wBAAwB;AACxB,wBAAgB,cAAc,CAAC,OAAO,EAAE;IACtC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACzB,GAAG,QAAQ,CAuCX"}

package/lib/cli/run.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Command line entry point.
+ *
+ * The only place that catches: every other module raises, and this decides how
+ * it is shown and which exit code it becomes.
+ */
+/** Run the CLI. */
+export declare function main(argv: string[]): Promise<number>;
+//# sourceMappingURL=run.d.ts.map

package/lib/cli/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/cli/run.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAiBH,mBAAmB;AACnB,wBAAsB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA2C1D"}