Skip to content

Latest commit

 

History

History
140 lines (106 loc) · 7.99 KB

FAQ.md

File metadata and controls

140 lines (106 loc) · 7.99 KB
Raw

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.

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