docs: consumer README for every block and sub-block#1484
Open
dgaponov wants to merge 4 commits into
Open
Conversation
Add a consistent, consumer-facing README.md to each page block (23) and sub-block (12), describing what it renders, its `type` string, when to use it, a copy-pasteable JSON example, and a full properties table (type / default / description) sourced from each block's schema.ts and TS models. Each example is verified by a new harness (test-utils/readme-examples.test.tsx) that, for every README, (1) validates the JSON example against the library's own generateDefaultSchema() via ajv, and (2) renders it through <PageConstructor> in jsdom to assert it does not throw. All 35 examples render without errors; non-gap examples pass schema validation. The harness also documents pre-existing gaps in the schema bundle that reject otherwise-valid configs (hero-block/foldable-list-block not registered; form-block/tabs-block ambiguous oneOf; info-block over-strict required; basic-card/image-card themed values; content/hubspot-form are nested, not standalone children) so they are skipped explicitly rather than silently. Co-Authored-By: Claude <noreply@anthropic.com>
Contributor
|
Preview is ready. |
Contributor
|
Playwright Test Component is ready. |
Make the per-block README.md the single source of truth and stop duplicating its content in the Storybook .mdx docs pages. - Each block/sub-block .mdx now imports its README.md and renders it via <Markdown> from @storybook/blocks (GFM tables included), keeping the <Meta> + <StoryTemplate> wrapper so live stories still render below. - Add a webpack `asset/source` rule for .md in .storybook/main.ts so README.md can be imported as a raw string (.mdx files are unaffected). - Add docs .mdx for Icons and PromoFeaturesBlock (they had stories but no docs page), so every block's storybook docs come from its README. - Drop ~1.4k lines of hand-maintained parameter prose from the .mdx files. Verified with `npm run storybook:build` (clean build). Co-Authored-By: Claude <noreply@anthropic.com>
…d README The README.md is now rendered verbatim in each docs page, which duplicated the page title and added a self-referential Storybook link. - Add a small <Readme> wrapper (.storybook/readme.tsx) that removes the leading `# Title` H1 (Storybook already renders its own <Title/>) and the trailing `## Storybook` section before passing the markdown to <Markdown>. - Point every block/sub-block .mdx at <Readme> instead of <Markdown>. The README files themselves are unchanged — GitHub still shows the full document; only the Storybook render is trimmed. Verified with `npm run storybook:build` and `npm run lint:js`. Co-Authored-By: Claude <noreply@anthropic.com>
- Storybook links were generated from the block `type` string (e.g. `blocks-banner-block--docs`), but Storybook URLs are derived from the story `title` in each stories.tsx (`Blocks/Banner` → `blocks-banner--docs`). Recompute every link from the actual title, including the `Components/...` sub-block titles, and add a `## Storybook` section to the sub-block READMEs that lacked one. - `\|` inside inline code in prose rendered as a literal backslash-pipe on GitHub; keep the escape only where it is required (inside table cells) and use a plain `|` everywhere else. Co-Authored-By: Claude <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a consistent, consumer-facing
README.mdto every page block (23) and sub-block (12) — back-filling the per-block README that the root README's "How to add a new block" step mandates but was never applied to existing blocks.Each README follows the same template:
type:stringProperty | Type | Default | Description) sourced from each block'sschema.ts+ TS modelsVerification
New harness
test-utils/readme-examples.test.tsxchecks every README's example:generateDefaultSchema()(ajv).<PageConstructor>in jsdom and asserts it doesn't throw.Result: all 35 examples render without errors; every non-gap example passes schema validation (
61 passed, 9 skipped, 0 failed).typecheck,eslint, andprettierare clean.The 9 skipped cases are pre-existing gaps in the library's schema bundle (not doc bugs) — each documented in the harness:
hero-block,foldable-list-block— not registered in the schema bundle at allform-block(formData),tabs-block(media) — ambiguousoneOfinfo-block— over-strictrequiredbasic-card(icon),image-card(image) — accept themed values at runtime but schema declares plainImagePropscontent,hubspot-form— nested structures, not standalone children🤖 Generated with Claude Code