Frequently asked questions

I am experiencing issues with building the docs.

There are a few known issues:

• you are missing some static assets - you will get an error Error resolving an import
• the docs are partially embedded - you can use ./docs-cli.cjs embed method to locally embed all repos
• Duplicate attribute
• My build breaks

If the build breaks for no reason, check out ./.github/scripts/debug.js for automatically debugging hundreds of .md files for issues.

The local docs preview does not open in Chrome.

If pnpm docs:preview starts successfully but the page does not open properly in Chrome during local development, your Linux inotify limits may be too low.

Try the following commands, in sudo mode:

sysctl fs.inotify.max_queued_events=16384
sysctl fs.inotify.max_user_instances=8192
sysctl fs.inotify.max_user_watches=524288

If this fixes the issue, you may want to persist these values in your system sysctl configuration so they survive a reboot.

PHPStorm does not reformat my frontmatter config properly.

Please, enable registry key markdown.experimental.frontmatter.support.enable=true in your PhpStorm registry settings.

Shift+Shift -> Registry -> Find and enable key

See https://youtrack.jetbrains.com/issue/IDEA-291881/Frontmatter-Support in JetBrains issue tracker for more info.

GitHub workflow is broken

Give it another try. Sometimes the process takes too long and reaches the timeout setting. You can also try running the pipeline locally using the ./.github/scripts/act.sh.

Can I run the whole workflow locally?

Yes, you can use nektos/act for that purpose. First, follow the install instructions for your OS.

Then copy ./.act.env.sample to ./.act.env and edit env vars for Figma and GitHub.

$ cp ./.act.env.sample ./.act.env
$ nano ./.act.env

To list all available jobs run the following command.

$ ./bin/act -l

For running a selected job run the command below and pass the --secret-file option.

# run embed-docs and test-cli steps
$ ./bin/act -j embed-docs --secret-file ./.act.env
$ ./bin/act -j test-cli --secret-file ./.act.env

To draw a workflow graph:

$ ./bin/act -g

What is the difference between the library and project?

Library (developer-documentation-vitepress) holds Shopware-flavoured Vitepress theme that can be reused by different projects. Our project (Developer portal) reuses the library.

What is the difference between the basic (embedded) and advanced (standalone) usages.

General overview

• Setup - only Developer portal reuses our developer-documentation-vitepress theme.
• Configuration: - configuration is kept at single place in developer-portal. Other repos can "flavour" it by using docs-after-build.sh script and docs.yml config.
• Dependencies: - dependencies are kept in developer-portal and developer-documentation-vitepress repos. Other repos only provide .md files and custom VueJS components.
• Algolia search: - index is updated whenever the main website developer.shopware.com is updated, through the algolia-crawl.yml GitHub workflow
• Sitemap: - sitemap is generated during the build process of the developer-portal.
• Updates: - Feature branch PRs are created in developer-portal using create-pr.yml, self-trigger workflows and checkout-install action.
• Navigation: - navigation is configured in global config.ts
• Deployments: - static build is deployed to Vercel, from the checkout-test-build-deploy workflow
• Content: - contents are provided by all repos and embedded/mounted to the src directory in developer-portal, as defined in data.ts.
• Custom features: - all features by provided by developer-portal or developer-documentation-vitepress
• GitHub actions: - custom checkout-install is provided and reused by other repos
• PageRef / Sidebar - sidebars are automatically generated, meta data is provided to all pages and available to components

Both approaches

• Sitemap: sitemap can be automatically generated by using the readSitemap() helper provided by developer-documentation-vitepress.

Here's a table explaining pros and cons using for both methods.

With Developer portal (embedded) - single-project, single-build, single-deployment

This is how Developer portal is intended to work.

Feature	Pros	Cons
Setup	Single setup to maintain	More complex setup
Configuration	Single config to maintain	More complex configuration
Dependencies	Single list of all dependencies	Globally available dependencies
Algolia search	Single source to maintain	Larger index
Sitemap	Single sitemap	Larger sitemap
Development	Single dev environment and workflow	More complex development
Updates	Single update method	More complex structure
Navigation	Single config	/
Deployments	Single production environment	Larger and more frequent deployments
Content	Only embed .md files with static content	Need to extend the library to provide custom features
Custom features	Available once-and-for-all	May break other docs
GitHub actions	Single GitHub workflow	Longer execution
Sidebar / PageRef	Automatic link discovery	Larger build size

With Vitepress template/library (standalone) - multiple projects, multiple builds, multiple deployments

This is how Developer portal is actually built.

Feature	Pros	Cons
Setup	Independent setup	More setups to maintain
Configuration	Independent project configuration	More configs to maintain
Dependencies	Dedicated dependencies	More projects to maintain
Algolia search	Having a separate index	Not being able to display results from other docs
Sitemap	Smaller sitemap	/
Development	Independent components	Using the same version of dependency across multiple projects
Updates	Independent updates	Outdated code and features
Navigation	Custom navigation	Keeping navigation up to date
Deployments	Independent deployments	Multiple production environments
Content	/	/
Custom features	Independent features	Sharing the same feature, making it available in all docs
GitHub actions	Faster execution	Multiple repositories
Sidebar / PageRef	Smaller build size	Managing links, titles and descriptions