Before using the Design System Publisher tool, you need to have the necessary environment requirements set up.
Vaadin development tools
The documentation contains a Vaadin project for rendering UI examples, and you need to have the same development tools installed when doing Vaadin application development.
See the Installing instructions for setting up the environment for Vaadin projects.
The CLI tool uses Git to clone an initial copy of the documentation project, so make sure to have Git installed.
Since the Design System Publisher tool runs within a Docker container, you need to have Docker (with
docker-compose) installed to use the tool. See the Docker installation guide for instructions for setting it up.
|On Windows, the only supported environment is WSL2, due to Docker limitations on file change events for shared volumes. See Troubleshooting for details.|
Run the following command to create a new design system website project:
npx @vaadin/cli dsp-init
New to terminal?The terminal – also referred to as the command line or shell – is a text-based interface used to run commands on your computer. If you’re new to the terminal, see instructions for Windows, macOS, and Linux.
The tool asks for a name for your design system, which is used for things like the visible page title, and a folder name for the website project.
The initialization script should take about a minute to finish. Once done, you should have the website project in your current working directory. The project uses Git for version control.
After the initialization process finishes, the repository has some file changes that you should look into and possibly edit:
my-docs ├── articles/ds/ │ ├──404.asciidoc (1) │ ├──index.asciidoc (2) │ └──components/foundation │ └──index.asciidoc (3) ├── dspublisher/ │ ├──docs-theme (4) │ └──.env (5) └── LICENSE (6)
The 404 (not found) -page content
The front page content
The two main sections have an addition in the front matter to have them expanded by default in the side menu
The custom theme for the documentation application. See Site Customization for more information
A set of environment variables used by the Design System Publisher. See Settings for more information
The project license file
Once you are happy with the changes, you should commit them.
The folder structure generated by the initialization script is as follows:
my-docs (1) ├── articles/ (2) ├── frontend/ (3) ├── src/main/java/ (4) ├── dspublisher/ (5) └── pom.xml (6)
The root folder name is the short name provided to the initialization script
Page content in AsciiDoc files
TypeScript component examples
Java component examples
Maven POM for theme and component dependencies