admin/webstudio
1
0 Fork 0
mirror of https://github.com/webstudio-is/webstudio.git synced 2026-10-23 03:27:27 +09:00
Code Issues Packages Projects Releases Wiki Activity
Files
main
webstudio/docs/university/how-tos/how-to-crop-an-image-with-out-cropping-the-original-image.md
T
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

2.8 KiB
Raw Permalink Blame History

description
description
Crop images visually in Webstudio without modifying the original file.

▶ How to crop an image with out cropping the original image

{% embed url="https://www.tella.tv/video/clq6kyooj00580fl80ju020i9/view" %}

Learn how to visually crop images in Webstudio without modifying the original image file.

Overview

Sometimes you need an image to fit a specific shape or aspect ratio without altering the source file. Webstudio allows you to "crop" images visually using CSS properties, keeping your original image intact.

Method 1: Using Object-Fit

The most common approach uses the object-fit CSS property.

Steps

  1. Add an Image component to your page
  2. Select your image from Assets
  3. Set a specific width and height on the image (e.g., 400px × 300px)
  4. In the Styles panel, set object-fit to cover
  5. Use object-position to control which part of the image is visible:
    • center (default) - shows the center
    • top - shows the top portion
    • bottom - shows the bottom portion
    • left / right - for horizontal positioning
    • Custom values like 50% 25% for precise control

Object-Fit Values

Value Behavior
cover Fills container, may crop edges
contain Fits entire image, may letterbox
fill Stretches to fill (distorts)
none Natural size, may overflow

Method 2: Using Overflow Hidden

This method uses a container to mask parts of the image.

Steps

  1. Add a Box component
  2. Set the Box's dimensions to your desired "crop" size
  3. Set overflow: hidden on the Box
  4. Add an Image inside the Box
  5. Make the image larger than the container
  6. Position the image using transform: translate() or negative margins

Method 3: Using Aspect Ratio

For responsive cropping that maintains proportions:

  1. Add an Image component
  2. Set width to 100% (or desired width)
  3. Set a specific aspect-ratio (e.g., 16/9, 1/1, 4/3)
  4. Set object-fit: cover

Common Use Cases

  • Profile pictures: Square crop with aspect-ratio: 1/1
  • Hero banners: Wide crop with aspect-ratio: 21/9
  • Thumbnails: Consistent card images with aspect-ratio: 16/9
  • Circular crops: Add border-radius: 50% to any square aspect ratio

Tips

  • Always use object-fit: cover when setting fixed dimensions on images
  • Use the Design tab to preview how your "crop" looks at different viewport sizes
  • Consider creating multiple crops in your image editor only if you need significantly different compositions for mobile vs desktop

Related

  • Image – Learn about the Image component and its properties
  • Design tokens – Create reusable styles for consistent image sizing
  • Collection – Display cropped images in dynamic lists
Reference in new issue View Git Blame Copy Permalink