Troubleshooting
- The process keeps restarting with an error message saying "Killed"
This usually means that the Docker container runs out of memory and then tries to restart. It’s recommended to increase the memory limit in the Docker preferences (up to 8 GB) to make sure the container doesn’t run out of memory.
- 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:cleanto wipe out the internal caches and restart to see if it fixes the issue.Note that the issue may also concern the browser’s cache. In case the above doesn’t help, try cleaning the browser’s cache as well.
- The browser doesn’t update live when content is updated in the filesystem
When running on Windows, make sure the Design System Publisher project folder is stored in the Windows Subsystem for Linux (WSL2) filesystem. Check the official WSL2 documentation for detailed installation instructions.
Design System Publisher relies on the filesystem watchers to detect changes to the source files and refresh the content served to the browser. When running on Windows, the Publisher Docker container only receives file change events when the source files are stored on the Linux filesystem (see the Docker for Windows best practices).
- 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 uselayout: tabbed-pagein the page front matter, the tabbed page heading is actually obtained from the front matter’s title field so you need to update that instead.- File permission issues on Linux, some files are owned by root user
The Design System Publisher tool runs inside a Docker container and creates files on volumes mounted from the host environment. There’s a known issue affecting Linux hosts that the files created on the mounted volumes are by default owned by the "root" user. If necessary, you can manually change the ownership of the files inside the documentation project directory and the local Maven repository back to the current user, for example:
sudo chown -R $(whoami) path-to-the-projectand
sudo chown -R $(whoami) ~/.m2