Docs: Make the block docs generator usable for any blocks directory

[bor0]

What?

See #78998

Makes tools/docs/generate-block-docs.mjs work on any directory of blocks, not just packages/block-library/src. No change to the generated core docs.

Why?

#78998 asks whether the per-block reference from #77612 could be reused by block plugins. This is a first step that doesn't commit to any public API: it only removes the core assumptions from the script, so where it should live for plugins (@wordpress/scripts or elsewhere) can be decided separately.

How?

• Core paths and handbook URLs move into CORE_OPTIONS. generateBlockDocs( options ) is exported, and running the script with no arguments uses CORE_OPTIONS as before.
• Options left out are off rather than falling back to core values, so documenting another directory never writes into the core docs. Category pages, the deprecated notice, the Source section and fixtures are each optional.
• Links between blocks resolve by block name. Before, blockLink() assumed the directory equals the name minus core/.
• Fixtures are looked up as {namespace}__{name}.html, which is the existing core naming.
• Block type detection also picks up save defined in index.js (common in plugins), ignoring save: () => null. When the type is still unknown, the markup section no longer calls the block static.
• --blocks-dir and --source-url flags for trying it on a plugin. From the CLI, related blocks link to sibling READMEs.

Testing Instructions

1. npm run docs:blocks-detail. git status shows no changes outside this script.
2. Try it on a plugin, e.g. GatherPress:

   git clone --depth 1 https://github.com/GatherPress/gatherpress /tmp/gatherpress
   node tools/docs/generate-block-docs.mjs --blocks-dir=/tmp/gatherpress/src/blocks --source-url=https://github.com/GatherPress/gatherpress/tree/main/src/blocks/
   

   20 READMEs are written to /tmp/gatherpress/src/blocks/*/README.md, and nothing in the Gutenberg checkout changes.

Sample output: gatherpress/dropdown-item (excerpt)

A customizable item for use within the dropdown menu block.

- **Name:** `gatherpress/dropdown-item`
- **Category:** gatherpress
- **API Version:** [3](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-api-versions/)
- **Block Type:** [Static](https://developer.wordpress.org/block-editor/getting-started/fundamentals/static-dynamic-rendering/) (saved in post content)

## Block Relationships

**[Parent](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#parent) blocks (direct):**
- [`gatherpress/dropdown`](../dropdown/README.md)

Known gaps, not addressed here:

• Markup examples without a fixture list every attribute default, e.g. <!-- wp:gatherpress/venue-detail {"fieldType":"text",...} /-->. The editor omits defaults when saving, so the real markup is shorter. This already happens for core blocks without fixtures.
• The Source line mentions edit, save and index.php, which is core's file layout.
• Supports and attributes anchors are read from the Gutenberg docs, so the script still has to run from a Gutenberg checkout.

Use of AI Tools

Written with Claude Code. I reviewed the change and checked the core output is unchanged.

🤖 Generated with Claude Code

[github-actions]

🤖 PR meta 🤖

🎉 Props

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: bor0 <bor0@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

Updated as activity occurs, without notifying anyone named here. Add the props-bot label to refresh.