dx: fix broken PageRef

.github/scripts/broken-pageref.js

@@ -0,0 +1,64 @@
+// deno run --allow-read .github/scripts/broken-pageref.js
+
+import { resolve, dirname, fromFileUrl } from "https://deno.land/std/path/mod.ts";
+import { walk } from "https://deno.land/std/fs/mod.ts";
+
+const rootDir = resolve(Deno.cwd());
+
+async function findBrokenLinks() {
+  const brokenLinks = [];
+
+  for await (const entry of walk(rootDir, { exts: ['.md'], followSymlinks: true })) {
+    if (entry.isFile) {
+      const content = await Deno.readTextFile(entry.path);
+      const matches = [...content.matchAll(/<PageRef page="([^"]+)"/g)];
+
+      for (const match of matches) {
+        let relativePath = match[1];
+
+        if (relativePath.startsWith('http')) {
+          continue
+        }
+
+        if (relativePath.includes('#')) {
+          relativePath = relativePath.split('#')[0]
+        }
+
+        if (relativePath.endsWith('/')) {
+          relativePath = `${relativePath}/index.md`
+        }
+
+        if (relativePath.endsWith('.html')) {
+          relativePath = `${relativePath.substring(0, relativePath.length - '.html'.length)}.md`
+        } else if (!relativePath.endsWith('.md')) {
+          relativePath = `${relativePath}.md`
+        }
+
+        const resolvedPath = resolve(dirname(entry.path), relativePath);
+
+        try {
+          await Deno.stat(resolvedPath);
+        } catch {
+          brokenLinks.push({ file: entry.path, relativePath, resolvedPath });
+        }
+      }
+    }
+  }
+
+  return brokenLinks;
+}
+
+const brokenLinks = await findBrokenLinks();
+if (brokenLinks.length) {
+  console.log('Broken links found:');
+  brokenLinks.forEach(link => {
+    console.log(`File: ${link.file}`);
+    console.log(`Relative Path: ${link.relativePath}`);
+    console.log(`Resolved Path: ${link.resolvedPath}`);
+    console.log('---');
+  });
+  Deno.exit(1)
+}
+
+console.log('No broken links found.');
+Deno.exit(0)

.github/workflows/markdown-style-check.yml

@@ -13,6 +13,13 @@ jobs:
     - name: Check out code
       uses: actions/checkout@v4
 
+    - uses: denoland/setup-deno@v1
+      with:
+        deno-version: "~1.32"
+
+    - name: Check broken PageRef links
+      run: deno run --allow-read .github/scripts/broken-pageref.js
+
     - name: Lint all files
       uses: docker://avtodev/markdown-lint:v1.5
       with:

concepts/api/store-api.md

@@ -17,7 +17,7 @@
 
 Using plugins, you can add custom routes to the Store API \(as well as any other routes\) and also register custom services. We don't force developers to provide API coverage for their functionalities. However, if you want to support headless applications, ensure that your plugin provides its functionalities through dedicated routes.
 
-<PageRef page="../../guides/plugins/plugins/framework/store-api" />
+<PageRef page="../../guides/plugins/plugins/framework/store-api/" />
 
 ## What next?
 

guides/plugins/plugins/administration/advanced-configuration/add-rule-assignment-configuration.md

@@ -22,7 +22,7 @@
 This guide **does not** explain how to create a new plugin for Shopware 6.
 Head over to our Plugin base guide to learn how to create a plugin at first:
 
-<PageRef page="../plugin-base-guide" />
+<PageRef page="../../plugin-base-guide" />
 
 ## Creating the index.js file
 

guides/plugins/plugins/administration/data-handling-processing/search-custom-data.md

@@ -26,17 +26,17 @@
 
 For this guide, it's necessary to have a running Shopware 6 instance and full access to both the files and a running plugin. See our plugin page guide to learn how to create your own plugins.
 
-<PageRef page="../plugin-base-guide" />
+<PageRef page="../../plugin-base-guide" />
 
 In addition, you need a custom entity to add to the search to begin with. Head over to the following guide to learn how to achieve that:
 
-<PageRef page="../framework/data-handling/add-custom-complex-data" />
+<PageRef page="../../framework/data-handling/add-custom-complex-data" />
 
 ## Support custom entity via search API
 
 To support an entity in the untyped global search, the entity has to be defined in one of the Administration Modules.
 
-<PageRef page="./add-custom-module.md" />
+<PageRef page="../module-component-management/add-custom-module.md" />
 
 Add the `entity` and `defaultSearchConfiguration` values to your module to make it available to the search bar component.
 

guides/plugins/plugins/administration/data-handling-processing/using-custom-fields.md

@@ -11,15 +11,15 @@
 
 All you need for this guide is a running Shopware 6 instance, the files and preferably a registered module in your own plugin. Don't know how to create an own plugin yet? Head over to the following guide:
 
-<PageRef page="../plugin-base-guide" />
+<PageRef page="../../plugin-base-guide" />
 
 In order to craft your module, you will need to create lots on own components. If you're not sure about how to do that, take a look at the corresponding guide:
 
-<PageRef page="add-custom-component" />
+<PageRef page="../module-component-management/add-custom-component" />
 
 In addition, of course you need an entity with custom fields to be able to add those custom fields to your module to begin with. Here you can learn how to add your custom fields:
 
-<PageRef page="../framework/custom-field/add-custom-field" />
+<PageRef page="../module-component-management/add-custom-field" />
 
 ## Using custom fields in your module
 

guides/plugins/plugins/administration/module-component-management/add-custom-component.md

@@ -17,11 +17,11 @@
 
 This guide **does not** explain how to create a new plugin for Shopware 6. Head over to our Plugin base guide to learn how to create a plugin at first:
 
-<PageRef page="../plugin-base-guide" />
+<PageRef page="../../plugin-base-guide" />
 
 If you want to work with entities in your custom component or page, it might be useful to take a look at how to create a custom entity guide first:
 
-<PageRef page="../framework/data-handling/add-custom-complex-data" />
+<PageRef page="../../framework/data-handling/add-custom-complex-data" />
 
 Especially if you want to add a new page for an own module, you should consider looking at the process on how to add a custom module first.
 

guides/plugins/plugins/administration/module-component-management/add-custom-field.md

@@ -15,7 +15,7 @@
 
 This guide **does not** explain how you can create a new plugin for Shopware 6. Head over to our plugin base guide to learn how to create a plugin at first:
 
-<PageRef page="../plugin-base-guide" />
+<PageRef page="../../plugin-base-guide" />
 
 ## Injecting into the Administration
 

guides/plugins/plugins/administration/module-component-management/add-custom-module.md

@@ -15,7 +15,7 @@
 This guide **does not** explain how to create a new plugin for Shopware 6.
 Head over to our Plugin base guide to learn how to create a plugin at first:
 
-<PageRef page="../plugin-base-guide" />
+<PageRef page="../../plugin-base-guide" />
 
 ## Creating the index.js file
 
@@ -69,7 +69,7 @@
 
 ::: danger
 This is not the icon being used for a menu entry! The icon for that needs to be configured separately.
-Please refer to the [Add a menu entry](add-menu-entry) guide for more information on this topic.
+Please refer to the [Add a menu entry](../routing-navigation/add-menu-entry) guide for more information on this topic.
 :::
 
 In addition, you're able to configure a title here, which will be used for the actual browser title.
@@ -87,11 +87,11 @@
 
 The next steps are covered in their own guides. The first one would be adding a menu entry, so please take a look at the guide regarding:
 
-<PageRef page="add-menu-entry" />
+<PageRef page="../routing-navigation/add-menu-entry" />
 
 The second one refers to setting up custom routes, its guide can be found in the guide on adding custom routes:
 
-<PageRef page="add-custom-route" />
+<PageRef page="../routing-navigation/add-custom-route" />
 
 ## Set up additional meta info
 
@@ -299,8 +299,8 @@
 You may want to try the following things:
 
 * [Add custom component](add-custom-component)
-* [Add a menu entry](add-menu-entry)
-* [Add a custom route](add-custom-route)
+* [Add a menu entry](../routing-navigation/add-menu-entry)
+* [Add a custom route](../routing-navigation/add-custom-route)
 * [Add a custom service](add-custom-service)
 * [Add translations](adding-snippets)
 * [Customizing another module](customizing-modules)

guides/plugins/plugins/administration/routing-navigation/add-menu-entry.md

@@ -15,11 +15,11 @@
 
 This guide **does not** explain how to create a new plugin for Shopware 6. Head over to our Plugin base guide to learn how to create a plugin at first:
 
-<PageRef page="../plugin-base-guide" />
+<PageRef page="../../plugin-base-guide" />
 
 Especially if you want to add a new page for an own module, you should consider to look at the process on how to add a custom module first.
 
-<PageRef page="add-custom-module" />
+<PageRef page="../module-component-management/add-custom-module" />
 
 ## Creating a simple menu entry
 

guides/plugins/plugins/administration/routing-navigation/add-new-tab.md

@@ -15,15 +15,15 @@
 
 This guide requires you to already have a basic plugin running. If you don't know how to do this in the first place, have a look at our plugin base guide:
 
-<PageRef page="../plugin-base-guide" />
+<PageRef page="../../plugin-base-guide" />
 
 In the course of this guide, you need to create a custom route. If you want to learn on how to create a custom component, please refer to the guide on it:
 
 <PageRef page="add-custom-route" />
 
 Also, we will use a small, custom component to fill our custom tab. In order to get used to that, it might come in handy to read the corresponding guide first:
 
-<PageRef page="add-custom-component" />
+<PageRef page="../module-component-management/add-custom-component" />
 
 ::: info
 

guides/plugins/plugins/administration/templates-styling/add-custom-styles.md

@@ -15,13 +15,13 @@
 
 However, this guide does not explain how to create a custom component, so head over to the official guide about creating a custom component to learn this first.
 
-<PageRef page="add-custom-component" />
+<PageRef page="../module-component-management/add-custom-component" />
 
 In addition, you need to have a basic knowledge of CSS and SCSS in order to use custom styles. This is though considered a basic requirement and won't be taught in this guide.
 
 ### Example: Custom cms block
 
-We will base our guide on an example: Let's use a custom component printing out "Hello world!". So first of all, create a new directory for your`sw-hello-world`. As said before, more information about that topic, such as where to create this directory, can be found in [Add a custom component](add-custom-component).
+We will base our guide on an example: Let's use a custom component printing out "Hello world!". So first of all, create a new directory for your`sw-hello-world`. As said before, more information about that topic, such as where to create this directory, can be found in [Add a custom component](../module-component-management/add-custom-component).
 
 In your component's directory, create a new `index.js` file and register your custom component `sw-hello-world`:
 

guides/plugins/plugins/administration/templates-styling/using-assets.md

@@ -15,7 +15,7 @@
 
 In order to be able to start with this guide, you need to have an own plugin running. As to most guides, this guide is also built upon the Plugin base guide:
 
-<PageRef page="../plugin-base-guide" />
+<PageRef page="../../plugin-base-guide" />
 
 Needless to say, you should have your image or another asset at hand to work with.
 

guides/plugins/plugins/administration/ui-ux/adding-responsive-behavior.md

@@ -11,7 +11,7 @@
 
 The Shopware 6 Administration provides two ways of adding classes to elements based on their size, the device helper and the `v-responsive` directive. Alternatively you can use `css` media queries to make your plugin responsive. Learn how to use `css` here:
 
-<PageRef page="add-custom-styles" />
+<PageRef page="../templates-styling/add-custom-styles" />
 
 ## DeviceHelper
 

guides/plugins/plugins/content/cms/add-cms-element.md

@@ -18,7 +18,7 @@
 
 This guide will also not explain how a custom component can be created in general, so head over to the official guide about creating a custom component to learn this first.
 
-<PageRef page="../../administration/add-custom-component" />
+<PageRef page="../../administration/module-component-management/add-custom-component" />
 
 ## Creating your custom element
 

guides/plugins/plugins/framework/custom-field/add-custom-field.md

@@ -283,7 +283,7 @@
 
 While theoretically your custom field is now properly defined for the Administration, you'll still have to do some work in your custom entities' Administration module. Head over to this guide to learn how to add your field to the Administration:
 
-<PageRef page="../../administration/using-custom-fields" />
+<PageRef page="../../administration/data-handling-processing/using-custom-fields" />
 
 ## Next steps
 

guides/plugins/plugins/storefront/use-media-thumbnails.md

@@ -19,7 +19,7 @@
 
 Displaying custom images is often done by using custom fields. To take full advantage of this guide, you might want to read the corresponding guide on using custom fields:
 
-<PageRef page="../administration/add-custom-field" />
+<PageRef page="../administration/module-component-management/add-custom-field" />
 
 ## Using searchMedia function