Tweaks

Author: hawkeyexl

docs/get-started/inputs/dita.mdx

@@ -112,6 +112,15 @@ Doc Detective recognizes specific action verbs in `<cmd>` elements to determine
 
 When these verbs appear with DITA semantic elements, Doc Detective automatically extracts the complete action. For example, `<cmd>Click the <uicontrol>Save</uicontrol> button</cmd>` generates `{ "click": "Save" }`.
 
+## Best practices
+
+- Use semantic DITA elements (`<uicontrol>`, `<userinput>`, etc.) for accurate test detection
+- Structure procedures as DITA task topics with `<steps>` and `<cmd>` elements
+- Use `scope="external"` on `<xref>` elements for external links
+- Add `outputclass` attributes to `<codeblock>` elements to specify language
+- Combine inline processing instructions with detected tests for comprehensive coverage
+- Use action verbs consistently (click, type, navigate, verify, etc.)
+
 ## Default DITA patterns
 
 ### Key patterns
@@ -256,15 +265,6 @@ For a complete list of patterns, see the [configuration reference](/docs/referen
 }
 ```
 
-## Best practices
-
-- Use semantic DITA elements (`<uicontrol>`, `<userinput>`, etc.) for accurate test detection
-- Structure procedures as DITA task topics with `<steps>` and `<cmd>` elements
-- Use `scope="external"` on `<xref>` elements for external links
-- Add `outputclass` attributes to `<codeblock>` elements to specify language
-- Combine inline processing instructions with detected tests for comprehensive coverage
-- Use action verbs consistently (click, type, navigate, verify, etc.)
-
 ## Next steps
 
 - Learn about [inline tests](/docs/get-started/tests/inline) for manual test definition

docs/get-started/inputs/markdown.mdx

@@ -43,6 +43,14 @@ Markdown files support multiple comment styles for inline tests:
 
 All three styles work identically. Choose the style that fits your documentation workflow.
 
+## Best practices
+
+- Use **bold text** for UI elements you want to interact with (buttons, menu items, etc.)
+- Use explicit navigation verbs (go to, navigate to, etc.) before links you want to open
+- Add the `.screenshot` class to images you want to capture as screenshots
+- Combine inline and detected tests for comprehensive coverage
+- Use `testIgnore` in code blocks that should not be executed as tests
+
 ## Detected test patterns
 
 Doc Detective includes default markup patterns for Markdown files that automatically detect tests from your documentation content.
@@ -280,14 +288,6 @@ In this example:
 - Specific form field typing is defined inline for precise control
 - `detectSteps: true` enables detection within the test block
 
-## Best practices
-
-- Use **bold text** for UI elements you want to interact with (buttons, menu items, etc.)
-- Use explicit navigation verbs (go to, navigate to, etc.) before links you want to open
-- Add the `.screenshot` class to images you want to capture as screenshots
-- Combine inline and detected tests for comprehensive coverage
-- Use `testIgnore` in code blocks that should not be executed as tests
-
 ## Next steps
 
 - Learn about [inline tests](/docs/get-started/tests/inline) for manual test definition

docs/get-started/tests/detected.mdx

@@ -12,6 +12,17 @@ Detected tests are useful for keeping your tests in sync with your documentation
 
 > You can mix detected tests with [inline tests](inline) to declare steps that might not be covered in your content, such starting or stopping a recording.
 
+## Benefits of detected tests
+
+Detected tests provide several advantages:
+
+- **Automatic synchronization**: Tests update automatically when documentation changes
+- **Reduced maintenance**: No need to manually update test specifications
+- **Consistent coverage**: Ensures all documented procedures are tested
+- **Time savings**: Eliminates the need to write many test specifications manually
+
+Combine detected tests with [inline tests](inline) for comprehensive test coverage with minimal manual effort.
+
 ## Default markup patterns
 
 Doc Detective includes default markup patterns for Markdown and DITA files. For comprehensive information about each input format and their patterns, see [Input formats](/docs/get-started/inputs/overview).
@@ -243,14 +254,3 @@ Load a browser cookie by name from a default location.
 ```json
 { "loadCookie": "$1" }
 ```
-
-## Benefits of detected tests
-
-Detected tests provide several advantages:
-
-- **Automatic synchronization**: Tests update automatically when documentation changes
-- **Reduced maintenance**: No need to manually update test specifications
-- **Consistent coverage**: Ensures all documented procedures are tested
-- **Time savings**: Eliminates the need to write many test specifications manually
-
-Combine detected tests with [inline tests](inline) for comprehensive test coverage with minimal manual effort.

docs/get-started/tests/inline.mdx

@@ -26,6 +26,17 @@ When you declare a step, you can specify any of the properties of the action you
 
 If you declare a step without declaring a test, Doc Detective automatically creates a test to contain the step.
 
+## Benefits of inline tests
+
+Inline tests offer several advantages:
+
+- **Proximity to content**: Tests are defined right next to the instructions they validate, making it easier to keep them in sync.
+- **Easy maintenance**: When you update documentation, the associated tests are immediately visible and can be updated at the same time.
+- **Documentation as code**: Tests become part of the documentation source, ensuring that documentation and testing evolve together.
+- **Quick validation**: Small, focused tests can be quickly added to validate specific instructions or procedures.
+
+Inline tests can be combined with [detected tests](detected) to create comprehensive test coverage with minimal manual test definition.
+
 ## Comment patterns by file type
 
 Doc Detective supports different comment patterns depending on your file type. For more information about input formats, see [Input formats](/docs/get-started/inputs/overview).
@@ -167,14 +178,3 @@ Click the *Start* button:
 
 // (test end)
 ```
-
-## Benefits of inline tests
-
-Inline tests offer several advantages:
-
-- **Proximity to content**: Tests are defined right next to the instructions they validate, making it easier to keep them in sync.
-- **Easy maintenance**: When you update documentation, the associated tests are immediately visible and can be updated at the same time.
-- **Documentation as code**: Tests become part of the documentation source, ensuring that documentation and testing evolve together.
-- **Quick validation**: Small, focused tests can be quickly added to validate specific instructions or procedures.
-
-Inline tests can be combined with [detected tests](detected) to create comprehensive test coverage with minimal manual test definition.

docs/get-started/tests/standalone.mdx

@@ -8,6 +8,15 @@ import JsonYamlTabs from "@site/src/components/JsonYamlTabs";
 
 # Standalone tests
 
+Standalone JSON or YAML files help you see the entirety of the spec and keep it in a separate, machine-readable format. They're useful for:
+
+- Complex test suites that need version control
+- Automated test generation and processing
+- Integration with CI/CD pipelines
+- Sharing tests across projects
+
+However, they make it harder to maintain strict parallelism with documentation, so consider your use case carefully.
+
 Test specs in standalone JSON or YAML files use the following basic structure:
 
 <JsonYamlTabs object={{
@@ -59,10 +68,3 @@ Here's an example test for performing a Google search and saving a screenshot of
     }
   ]
 }}></JsonYamlTabs>
-
-Standalone JSON or YAML files help you see the entirety of the spec and keep it in a separate, machine-readable format. They're useful for:
-
-- Complex test suites that need version control
-- Automated test generation and processing
-- Integration with CI/CD pipelines
-- Sharing tests across projects

docusaurus.config.ts

@@ -23,8 +23,11 @@ const config: Config = {
   deploymentBranch: "gh-pages",
 
   onBrokenLinks: "throw",
-  onBrokenMarkdownLinks: "warn",
-
+  markdown: {
+    hooks: {
+      onBrokenMarkdownLinks: "warn",
+    },
+  },
   // Even if you don't use internationalization, you can use this field to set
   // useful metadata like html lang. For example, if your site is Chinese, you
   // may want to replace "en" with "zh-Hans".