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 npm run dspublisher:clean to wipe out the internal caches and restart to see if it fixes the issue.
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-devThe 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 182E98556-B62A-467D-947F-94C586E8A463