admin/webstudio
1
0 Fork 0
mirror of https://github.com/webstudio-is/webstudio.git synced 2026-11-02 18:18:35 +09:00
Code Issues Packages Projects Releases Wiki Activity
6,781 Commits 124 Branches 311 Tags
main
Commit Graph
3 Commits
Author SHA1 Message Date
Oleg Isonen f1c3abf1be docs: Refresh accessible Builder screenshots at 2x (#6595) 
## Outcome

Refresh the accessible low-resolution Builder documentation screenshots
with current, native 2× light and dark captures. Images retain useful
crops, descriptive alt text, and explicit display widths.

The final audit accounts for 165 candidate files: 132 refreshed, 29
inaccessible screenshots kept with the user's approval, two existing
images made 2× by setting their display width, and two Content Engine
query screenshots held because the current Builder shows a false
draft-filter type warning. Those two originals remain in place pending a
separate Builder fix and recapture. Four animated GIFs remain outside
this still-screenshot refresh.

## Review checklist

- [x] Inventory image references, native dimensions, display widths, UI
states, and source pages; audit omitted references across all docs.
- [x] Replace the approved Form pairs and accessible Builder screenshots
with matching 2× light and dark captures.
- [x] Keep inaccessible external/account/desktop and disabled Export
images, as approved.
- [x] Review size-sufficient images and GIF/diagram exclusions.
- [x] Review crops, alt text, widths, links, and source references.
Independent screenshot review passed.
- [x] Check the full docs image inventory: 322 placements, 284 unique
assets, zero missing files. The only unaccounted sub-2× refs are four
excluded GIFs.
- [x] Run `git diff --check` and verify all 204 changed image files are
referenced; 117 changed picture placements have matching themes and at
least 2× native width.
- [x] Verify required PR checks: Lint PR, Check submodules, Visual
regression, and Main workflow all passed at 14937127db.
- [ ] Recapture the two Content Engine query images after [Builder fix
#6597](https://github.com/webstudio-is/webstudio/pull/6597) reaches the
Builder used for capture. Keep their originals until then.\n- [ ]
Confirm GitBook rendering at intended CSS widths after publication. This
repository has no PR preview.

## Held images

`content-engine-overview-query.png` and
`content-engine-article-query.png` are unchanged. The current Builder's
query form reports a false type warning for the Boolean
`properties.draft` filter. Screenshotting that state would teach a
broken workflow. The user approved a separate [Builder query type fix in
PR #6597](https://github.com/webstudio-is/webstudio/pull/6597). Once
that fix is reviewed, the two screenshots can be recaptured from the
corrected UI. This PR does not change application code.

All captures use synthetic content. No release or publication branch is
changed.
 2026-10-25 10:11:58 +01:00
Oleg Isonen 1b48716ff4 docs: Document MDX-backed Content Blocks (#6273) 
## Summary

- Document how people create, connect, edit, validate, and publish
MDX-backed Content Blocks.
- Document the complete MCP workflow, including scoped expression
sources, frontmatter updates, diagnostics, conflicts, and disconnect
behavior.
- Add two focused screenshots for the human workflow.
- Fix issues found by a low-reasoning MCP agent while executing every
documented workflow.

Ref #6182

## Implementation notes

- Connection confirmation uses the public `confirmReplacement` field
because `confirm` is reserved as a hidden transport field.
- MCP edits frontmatter with `update-content-block-frontmatter`;
materialized MDX elements are not persistent targets for generic
instance mutation tools.
- Reload now intentionally discards a conflicted local source and
accepts the Asset's latest storage revision before an edit is reapplied.
- Generated MCP documentation and runtime contracts are updated from
their source files.

## Checklist

- [x] Document the human MDX Content Block workflow.
- [x] Document MCP discovery, connection, editing, diagnostics,
frontmatter, dynamic sources, conflicts, and disconnection.
- [x] Add only screenshots that clarify otherwise hard-to-describe UI
steps.
- [x] Test every documented MDX capability through the local MCP CLI
with a low-reasoning agent.
- [x] Reproduce and fix the replacement-confirmation schema mismatch.
- [x] Reproduce and fix persistent-session conflict reload and reapply.
- [x] Add regression tests that failed before each product fix and pass
afterward.
- [x] Regenerate runtime contracts and generated MCP documentation.
- [x] Review authoritative `docs/` content and update affected pages.
- [x] Run affected tests, typechecks, formatting, and diff checks.

## Verification

- Project Build: 208 affected tests passed.
- Content Engine Asset session: 8 tests passed.
- CLI documentation tests: 14 tests passed.
- MCP docs generator: 3 tests passed.
- Content Engine, Project Build, CLI, and MCP docs typechecks passed.
- `pnpm oxfmt --check` passed.
- `git diff --check` passed.
- Low-reasoning MCP evaluation passed all documented workflows,
including a real two-client revision conflict, reload, reapply, and
final saved inspection.
 2026-08-31 18:39:05 +02:00
Oleg Isonen 99371187dc docs: Move product documentation into Builder (#5987) 
## Summary

- move the complete GitBook documentation tree and assets into Builder
under `/docs`
- generate the exhaustive MCP page from the local CLI source in the same
change
- publish GitBook from a release-gated `docs` branch containing the
exact successfully released revision
- run MCP documentation tests, typechecking, and stale-output checks
with the existing generated-docs check
- remove links to the Community Discussions repository

## Technical choices

- Import the current documentation as a linear snapshot so the branch
satisfies Builder's required-linear-history protection.
- Keep the Markdown wrapper separate from the TypeScript generator at
`scripts/docs/mcp-page.md`.
- Generate through `packages/cli/local.js` so CLI guidance and its
documentation are reviewed together.
- Let `check:generated-docs` reject CLI changes that leave the committed
MCP page stale.
- After both GitHub release creation and package publication succeed,
fast-forward the read-only `docs` branch to the immutable release tag
commit. A divergent update fails instead of publishing a different
revision.
- Configure GitBook to publish `/docs` from the `docs` branch, not
directly from `main`.
- Exclude `/docs` from the repository-wide `oxfmt` scan so imported
GitBook Markdown retains its established formatting; generator tests and
stale-output checks still validate the MCP page.
- Exclude `transcripts/` and GitHub Discussions from the migration.

## Todo

- [x] Import documentation, navigation, includes, and assets under
`/docs`.
- [x] Generate the MCP page from the local CLI source.
- [x] Move MCP generation and validation into Builder.
- [x] Require MCP documentation updates alongside CLI changes.
- [x] Publish released revisions through a read-only `docs` branch.
- [x] Remove Community repository links from Builder and the migrated
docs.
- [x] Preserve and verify a final Community Git bundle locally.
- [ ] Merge this pull request.
- [ ] Let the next successful release create or advance the `docs`
branch.
- [ ] Repoint GitBook Git Sync to `webstudio-is/webstudio`, branch
`docs`, root directory `/docs`.
- [ ] Verify `docs.webstudio.is`, navigation, assets, anchors, and the
MCP page in production.
- [ ] Delete `webstudio-is/webstudio-community`.

## Verification

- `pnpm check:generated-docs`
- `pnpm lint`
- `pnpm oxfmt --check`
- `git diff --check origin/main...HEAD`
- generator regression test demonstrated failing when the GitBook
wrapper behavior was removed, then passing after restoration
- no fixture inputs or outputs are affected

## Known limitation

All documentation merged after the previous release waits for the next
successful release before GitBook publishes it. This deliberately keeps
the public MCP reference aligned with an installable CLI revision.

Ref #5986
 2026-08-03 17:55:50 +02:00