Troubleshooting

This page describes issues you might encounter while using Design System Publisher.

The browser doesn’t match the content in the filesystem

To speed up the start process, the Design System Publisher caches some resources internally. Sometimes, caches tend to get out of sync, and need cleaning up. Run the following command to wipe out the internal caches and restart to see if it fixes the issue:

npm run dspublisher:clean

The issue may also concern the browser’s cache. In case the above doesn’t help, try cleaning the browser’s cache as well.

Updating the page heading in AsciiDoc doesn’t affect the rendered page heading

There’s one caveat about the page headings. On a regular page, if you change the main heading in the AsciiDoc (= Page Heading), you see the heading update as expected. But if you use layout: tabbed-page in the page front matter, the tabbed page heading is actually retrieved from the front matter’s title field so you need to update that instead.

On Linux, the application refuses to start up

Make sure that the necessary dependencies are installed by running the following command:

sudo apt install build-essential autoconf automake libtool pkg-config libpng-dev nasm zlib1g-dev

The development server fails to start up

The npm run dspublisher:start script, which starts up the development server, has certain expectations about your development environment. The development server may fail to start up for one of the following reasons.

npm ignore-scripts=true

If you configure npm with ignore-scripts=true, the startup will fail. An example error message for this case is the following:

Error in "/Users/[username]/.npm/_npx/c089b35bd0e8ac07/node_modules/@vaadin/dspublish
er/node_modules/gatsby-transformer-sharp/gatsby-node.js":
Something went wrong installing the "sharp" module

Cannot find module '../build/Release/sharp-darwin-arm64v8.node'

Remove the ignore-scripts=true configuration and delete the /.npm/_npx from the home directory to fix the issue.

Missing Xcode Command Line Tools (macOS only)

On macOS, you need install the Xcode Command Line Tools. Otherwise you might receive the following type of error during start up:

dsp@[version]:start ████████████████████ Initializing
npx,concurrently,--kill-others,--raw,"npx @vaadin/dspublisher@[version] --develop","mvn -C" failed with code 1

Gatsby on Windows

Design System Publisher is based on Gatsby, which has known issues on Windows. If you’re using Windows, see Gatsby on Windows for more information.

It’s recommended to use Linux or macOS as your development platform. On Windows, you can use Windows Subsystem for Linux (WSL) to run Design System Publisher.

Bug Reports and Feature Requests

Bug reports and feature requests can be submitted in the Design System Publisher GitHub repository.

82E98556-B62A-467D-947F-94C586E8A463

Documentation