Refactor documentation templates for consistency and clarity

- Standardize titles and sidebar labels across templates
- Update code block formatting for better readability
- Improve example structures and explanations
- Remove unnecessary markdown syntax for cleaner output

Author: hawkeyexl

docs/contributing/templates/feature.mdx

@@ -28,7 +28,7 @@ Use feature documentation when:
 
 Copy and adapt this template for your feature documentation:
 
-```markdown
+````markdown
 ---
 title: [Feature name]
 description: [One-sentence description of what this feature does]
@@ -60,15 +60,23 @@ description: [One-sentence description of what this feature does]
 
 ### Basic example
 
-\`\`\`[language] title="[filename]" [Code showing simplest usage] \`\`\`
+```[language] title="[filename]"
+[Code showing simplest usage]
+```
 
 [Explain what this code does and what to expect.]
 
 ### Advanced example
 
+```[language] title="[filename]"
+[More complex example]
+```
+
 [Optional: Show a more complex or real-world usage.]
 
-\`\`\`[language] title="[filename]" [More complex example] \`\`\`
+```[language] title="[filename]"
+[More complex example]
+```
 
 [Explain the additional capabilities demonstrated.]
 
@@ -83,7 +91,9 @@ description: [One-sentence description of what this feature does]
 
 ### Example configuration
 
-\`\`\`json title=".doc-detective.json" { "featureName": { "option1": "value", "option2": 20 } } \`\`\`
+```json title=".doc-detective.json"
+{ "featureName": { "option1": "value", "option2": 20 } }
+```
 
 ## Migration guide
 
@@ -93,13 +103,17 @@ description: [One-sentence description of what this feature does]
 
 [Show how users currently do this.]
 
-\`\`\`[language] [Old way] \`\`\`
+```[language]
+[Old way]
+```
 
 ### To new behavior
 
 [Show how users should do this now.]
 
-\`\`\`[language] [New way] \`\`\`
+```[language]
+[New way]
+```
 
 ### Breaking changes
 
@@ -139,7 +153,7 @@ description: [One-sentence description of what this feature does]
 - [Related feature or action](link)
 - [Configuration reference](link)
 - [Tutorial using this feature](link)
-```
+````
 
 ## Writing tips
 
@@ -231,7 +245,7 @@ If behavior varies by version:
 
 Here's a complete example:
 
-```markdown
+````markdown
 ---
 title: Screenshot cropping
 description: Capture screenshots of specific elements instead of the entire page.
@@ -263,15 +277,19 @@ When documenting specific features, you often want screenshots that focus on a p
 
 Capture just a specific button:
 
-\`\`\`json title="screenshot-button.spec.json" { "tests": [ { "steps": [ { "action": "goTo", "url": "https://doc-detective.com" }, { "action": "screenshot", "path": "get-started-button.png", "cropTo": { "selector": "a[href='/docs/get-started']" } } ] } ] } \`\`\`
+```json title="screenshot-button.spec.json"
+{ "tests": [ { "steps": [ { "action": "goTo", "url": "https://doc-detective.com" }, { "action": "screenshot", "path": "get-started-button.png", "cropTo": { "selector": "a[href='/docs/get-started']" } } ] } ] }
+```
 
 This captures only the "Get Started" link, not the entire page.
 
 ### Advanced example
 
 Crop to an element with padding:
 
-\`\`\`json title="screenshot-with-padding.spec.json" { "tests": [ { "steps": [ { "action": "goTo", "url": "https://doc-detective.com" }, { "action": "screenshot", "path": "navigation-menu.png", "cropTo": { "selector": "nav.navbar", "padding": 20 } } ] } ] } \`\`\`
+```json title="screenshot-with-padding.spec.json"
+{ "tests": [ { "steps": [ { "action": "goTo", "url": "https://doc-detective.com" }, { "action": "screenshot", "path": "navigation-menu.png", "cropTo": { "selector": "nav.navbar", "padding": 20 } } ] } ] }
+```
 
 Adds 20 pixels of padding around the navigation element for context.
 
@@ -289,19 +307,25 @@ Adds 20 pixels of padding around the navigation element for context.
 
 ### Example configuration
 
-\`\`\`json title=".doc-detective.json" { "tests": [ { "steps": [ { "action": "screenshot", "path": "feature.png", "cropTo": { "selector": "#feature-section", "padding": 15 } } ] } ] } \`\`\`
+```json title=".doc-detective.json"
+{ "tests": [ { "steps": [ { "action": "screenshot", "path": "feature.png", "cropTo": { "selector": "#feature-section", "padding": 15 } } ] } ] }
+```
 
 ## Migration guide
 
 If you were using full-page screenshots and want to crop:
 
 ### From full-page screenshots
 
-\`\`\`json { "action": "screenshot", "path": "page.png", "fullPage": true } \`\`\`
+```json
+{ "action": "screenshot", "path": "page.png", "fullPage": true }
+```
 
 ### To element-based cropping
 
-\`\`\`json { "action": "screenshot", "path": "element.png", "cropTo": { "selector": "#target-element" } } \`\`\`
+```json
+{ "action": "screenshot", "path": "element.png", "cropTo": { "selector": "#target-element" } }
+```
 
 ### Breaking changes
 
@@ -345,7 +369,7 @@ None. This is a backward-compatible addition. Existing screenshots continue to w
 - [screenshot action reference](/docs/get-started/actions/screenshot)
 - [CSS selectors guide](/docs/get-started/selectors/css)
 - [Tutorial: Capture screenshots](/docs/get-started/tutorials/capture-screenshot)
-```
+````
 
 ## Checklist before submitting
 

docs/contributing/templates/how-to.mdx

@@ -1,10 +1,10 @@
 ---
-title: How-To Guide Template
+title: How-To guide template
 description: Template for creating task-oriented documentation.
-sidebar_label: How-To Template
+sidebar_label: How-To
 ---
 
-# How-To Guide Template
+# How-To guide template
 
 Use this template for task-oriented documentation that helps users accomplish a specific goal.
 
@@ -17,7 +17,7 @@ Use a how-to guide when users:
 - Want to complete a specific task
 - Already understand basic concepts
 
-**Examples:**
+Examples:
 
 - How to configure browser settings
 - How to run tests in parallel
@@ -28,7 +28,7 @@ Use a how-to guide when users:
 
 Copy and adapt this template for your how-to guide:
 
-```markdown
+````markdown
 ---
 title: How to [accomplish task]
 description: [One-sentence description of what users will accomplish]
@@ -52,7 +52,9 @@ description: [One-sentence description of what users will accomplish]
 
 [Provide detailed instructions. Use numbered sub-steps if needed.]
 
-\`\`\`[language] title="[filename if applicable]" [Code example or command] \`\`\`
+```[language] title="[filename if applicable]"
+[Code example or command]
+```
 
 [Explain what this code does or what to expect.]
 
@@ -93,7 +95,7 @@ description: [One-sentence description of what users will accomplish]
 - [Related task 1](link)
 - [Related task 2](link)
 - [Learn more about X](link)
-```
+````
 
 ## Writing tips
 
@@ -156,91 +158,6 @@ Before submitting:
 3. ✅ Test on a clean environment if possible
 4. ✅ Note any assumptions or prerequisites
 
-## Example how-to guide
-
-Here's a complete example:
-
-```markdown
----
-title: How to run tests in parallel
-description: Speed up test execution by running multiple tests simultaneously.
----
-
-# How to run tests in parallel
-
-Run multiple Doc Detective tests at the same time to reduce total execution time. This is useful when you have many tests or tests that take a long time to complete.
-
-## Before you begin
-
-- Doc Detective installed (`npm install -g doc-detective`)
-- At least two test files to run
-- Understanding of [test configuration](/docs/references/schemas/config)
-
-## Step 1: Enable parallel execution
-
-Add the `concurrency` option to your Doc Detective configuration file:
-
-\`\`\`json title=".doc-detective.json" { "concurrency": 4 } \`\`\`
-
-This runs up to 4 tests simultaneously. Adjust based on your system resources.
-
-## Step 2: Run your tests
-
-Execute tests as usual:
-
-\`\`\`bash npx doc-detective runTests \`\`\`
-
-Doc Detective automatically distributes tests across parallel workers.
-
-## Step 3: Monitor execution
-
-Watch the output to see parallel execution:
-
-\`\`\` [INFO] Running tests with concurrency: 4 [INFO] Test 1: RUNNING [INFO] Test 2: RUNNING [INFO] Test 3: RUNNING [INFO] Test 4: RUNNING [INFO] Test 1: PASSED [INFO] Test 5: RUNNING \`\`\`
-
-## Verify it works
-
-Compare execution time with and without parallelization:
-
-\`\`\`bash
-
-# Without parallelization
-
-time npx doc-detective runTests --concurrency 1
-
-# With parallelization
-
-time npx doc-detective runTests --concurrency 4 \`\`\`
-
-You should see reduced execution time.
-
-## Troubleshooting
-
-### Tests fail in parallel but pass individually
-
-**Cause:** Tests may have dependencies or shared state
-
-**Solution:** Ensure tests are independent. Avoid:
-
-- Shared files or resources
-- Dependencies between tests
-- Hardcoded ports or URLs
-
-### System becomes unresponsive
-
-**Cause:** Too many parallel tests for available resources
-
-**Solution:** Reduce concurrency:
-
-\`\`\`json { "concurrency": 2 } \`\`\`
-
-## What's next
-
-- [Optimize test performance](/docs/tutorials/optimize-tests)
-- [Configure test contexts](/docs/get-started/config/contexts/)
-- [Run tests in CI/CD](/docs/tutorials/ci-cd)
-```
-
 ## Checklist before submitting
 
 - [ ] Title starts with "How to"