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
5.2 KiB
🧑💻 Contributing for Developers
Process
If you want to contribute and don't know where to start, here is a step-by-step for a complete lifecycle, from idea to deployment.
-
If you have an idea that is not already in issues, open an issue or reach out on Discord.
-
If you are a DEVELOPER, and you want to contribute to the Builder UI, your first step is to become familiar with our design system in figma. Start with the first page of our Design Docs. And for our design system & components see the Webstudio Library. Please read the docs carefully and thoroughly so you can use our design system properly to create a UI that looks like it's a natural part of Webstudio. If any part of the design is confusing or intimidating you can reach out to us on Discord with questions or feedback.
-
After submitting an enhancement or a bug, we need to agree on a solution. You can jump into implementation right away, but be aware that we have to agree on the solution in the end. Communicating the problem you are solving and why you think the approach you are taking is the best is key for a quick process.
In fact, we are happy to help you communicate your ideas, so if you are not sure - talk to us on discord.
-
When the implementation is in a mergeable state, a core team member will deploy it to production.
Running the Webstudio Project Using VS Code
Prerequisites
- VS Code installed: Download VS Code
- Docker installed: Install Docker
Steps
- Install the "Dev Containers" extension in VS Code:
- Open VS Code.
- Go to the Extensions view by clicking the Extensions icon in the Activity Bar on the side of the window.
- Search for "Dev Containers" and click Install. Alternatively, you can install it from the recommended extensions listed in the Webstudio project.
- Fork and clone the Webstudio repository:
- Fork the repository on GitHub.
- Clone your forked repository to your local machine.
- Open the repository in VS Code:
- Open VS Code.
- Select "File" > "Open Folder" and choose your project folder.
- Reopen in Container:
- Once your folder is open, you might see a notification asking if you want to reopen in a container. Click "Reopen in Container".
- If you don't see a notification, press
F1, typeDev Containers: Reopen in Container, and select it.
VS Code will now build the Docker container and open the Webstudio project inside it. This process will take some time as the environment is set up and dependencies are installed.
-
Run the development server:
-
After the setup completes, open the terminal in VS Code.
-
Run the following command:
pnpm dev
-
-
Open the application in your browser:
-
After running
pnpm dev, you will see a URL in the console that looks like this:➜ Local: https://wstd.dev:5173/ -
Cmd + click on the URL in the console to open it in your browser.
-
{% hint style="danger" %}
If VS Code shows you an "Open Browser" button, it will lead you to the wrong URL as they are only watching ports. Be sure to use wstd.dev and NOT localhost. The proper URL will show in the console.
{% endhint %}
Login locally
When downloading the app you will have two options for login and they both work in different ways.
Dev login
Dev login will create you a dev account so you don't need to be online or create a github app. To enable you create a file .env.development in apps/builder and include two lines:
DEV_LOGIN=true
AUTH_SECRET=a random value
To login in the app click on the "Login with Secret" button and paste your AUTH_SECRET in the input.
To log in as another user in dev mode, use your AUTH_SECRET, followed by : and any email address. For example: `abcd:example@email.com`\
GitHub Login
To login and use GitHub login you will need to create an OAuth app with the following values:
Name: Webstudio
Homepage URL: http://localhost:3000
Authorization callback URL: http://localhost:3000/auth/github/callback
When creating the app with
http://localhost:3000you will need to always open your app athttp://localhost:3000for the GitHub login to work.
After the app is created you will need to create a client secret and then copy that value and your client id to the .env file:
GH_CLIENT_SECRET=
GH_CLIENT_ID=
You are done! 🎉
Related
- Contributing for Designers – Ways designers can contribute to Webstudio
- Contributing to the Marketplace – Submit templates and sections
- FAQs – Common questions including licensing information
- Roadmap & Links – See what the team is working on