Troubleshooting

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. Run the following command to flush the internal caches and restart the development server 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.

There’s one caveat about the page headings. On a regular page, if you change the main heading in the AsciiDoc (i.e., = Page Heading), you’ll 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. Therefore, you may want to change that instead.

When the application won’t start on Linux, make sure that the necessary dependencies are installed by running the following at the command-line:

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 for one of the following reasons:

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

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

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

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.