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