Documentation

You are viewing documentation for Vaadin 23. View latest documentation

Documentation

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.

  2. Git

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

  3. Node.js

    Design System Publisher uses Node.js, so make sure to have it installed. Version 16 is recommended.

Create a New Project

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

npx @vaadin/cli@2.7.0 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/components/
│   ├──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 Project Object Model (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.

A77F9CDF-C06C-4498-8E57-A3C80F9554FD