Getting Started With Design System Publisher

Setting Up Your Environment

Before using the Design System Publisher tool, you need to have the necessary environment requirements set up.

  1. 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.

  2. vaadin-cli

    The project is initialized using the vaadin-cli command line tool. Follow the installation instructions to get the CLI set up locally.

  3. Git

    The CLI tool uses Git to clone an initial copy of the documentation project, so make sure to have Git installed.

  4. Docker

    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.

Important
On Windows, the only supported environment is WSL2, due to Docker limitations on file change events for shared volumes. See Troubleshooting for details.

Create a New Project

Run the following command to create a new design system website project:

vaadin dsp-init
Tip
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)
  1. The 404 (not found) -page content

  2. The front page content

  3. The two main sections have an addition in the front matter to have them expanded by default in the side menu

  4. The custom theme for the documentation application. See Site Customization for more information

  5. A set of environment variables used by the Design System Publisher. See Settings for more information

  6. The project license file

Once you are happy with the changes, you should commit them.

Folder Structure

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)
  1. The root folder name is the short name provided to the initialization script

  2. Page content in AsciiDoc files

  3. TypeScript component examples

  4. Java component examples

  5. Website configuration

  6. Maven POM for theme and component dependencies

Next Steps

See Development Build to learn how to run Design System Publisher locally.

See Production Setup to learn how to run prepare the documentation website for production deployment/hosting.

See the other articles to learn how to customize the content and the styles of your documentation website.