mirror of
https://github.com/webstudio-is/webstudio.git
synced 2026-11-10 06:24:35 +09:00
Oleg Isonen
99371187dc
## 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
3.6 KiB
3.6 KiB
description
| description |
|---|
| Add headings (H1-H6) to structure content in Webstudio. |
Heading
The Heading component renders HTML heading elements (h1-h6) for creating a hierarchical structure of titles and subtitles on your page.
Overview
Headings establish the document outline and help users and search engines understand your content structure. They're crucial for:
- Accessibility: Screen readers use headings for navigation
- SEO: Search engines use headings to understand page content
- Visual hierarchy: Guide users through your content
Tag Options
| Tag | Typical Use |
|---|---|
h1 |
Page title (use only once per page) |
h2 |
Major section titles |
h3 |
Subsection titles |
h4 |
Sub-subsection titles |
h5 |
Minor headings |
h6 |
Smallest headings |
Properties
| Property | Type | Description |
|---|---|---|
tag |
string | Heading level: h1, h2, h3, h4, h5, or h6 |
id |
string | Unique identifier (useful for anchor links) |
class |
string | CSS class names |
Heading Hierarchy
Always maintain proper heading hierarchy:
h1: Page Title
├── h2: Section 1
│ ├── h3: Subsection 1.1
│ └── h3: Subsection 1.2
├── h2: Section 2
│ ├── h3: Subsection 2.1
│ │ └── h4: Sub-subsection 2.1.1
│ └── h3: Subsection 2.2
└── h2: Section 3
Common Mistakes to Avoid
❌ Don't skip levels: Going from h2 directly to h4
❌ Don't choose heading level for style: Use CSS instead
❌ Don't use multiple h1 tags: One per page is the standard
Styling Headings
Default Preset Styles
Webstudio applies browser-normalized styles to headings. You can customize:
- Font Size: Each heading level typically has progressively smaller sizes
- Font Weight: Often bold (700) or semi-bold (600)
- Line Height: Tighter than body text (1.1-1.3)
- Margin: Space above and below headings
- Color: Can match or contrast with body text
Typography Scale
A common typographic scale for headings:
| Level | Size (desktop) | Size (mobile) |
|---|---|---|
| h1 | 48-64px | 32-40px |
| h2 | 36-48px | 28-32px |
| h3 | 28-32px | 24-28px |
| h4 | 24-28px | 20-24px |
| h5 | 20-24px | 18-20px |
| h6 | 16-18px | 16-18px |
Dynamic Headings
Headings can display dynamic content from:
- CMS collections
- Page variables
- URL parameters
To bind dynamic content:
- Select the Heading
- Click the binding icon in Settings
- Choose your data source
Anchor Links
Create anchor links to headings for in-page navigation:
- Set an
idon the Heading (e.g., "features") - Create a Link with href
#features - Clicking the link scrolls to that heading
SEO Best Practices
-
Include keywords: Place important keywords in headings naturally
-
Be descriptive: Headings should clearly describe the content that follows
-
Keep h1 unique: Each page should have exactly one h1 that describes the page's main topic
-
Front-load important words: Put key terms at the beginning of headings