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.
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.
The CLI tool uses Git to clone an initial copy of the documentation project, so make sure to have Git installed.
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 @firstname.lastname@example.org 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/components/ │ ├──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 Project Object Model (POM) for theme and component dependencies
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.