FAQ docs quality pass: fix broken links, mismatched H1s, orphaned phrasing

AGENTS.md

@@ -0,0 +1,56 @@
+# Agent guide: writing and wiring FAQ articles
+
+This file is for AI agents (and anyone else) authoring or editing FAQ content in this repo. See `README.md` for what this repo is and how it's built.
+
+## Adding a new article
+
+Create a Markdown file in the right product/topic directory (see "Directory map" below) with this frontmatter and structure:
+
+```markdown
+---
+layout: default-layout
+title: <SEO-facing page title>
+keywords: <comma-separated keywords>
+description: <SEO-facing description, often the question itself>
+needAutoGenerateSidebar: false
+---
+
+# <The actual question, phrased as a question>
+
+Answer content...
+```
+
+Rules:
+
+- **Always include the H1.** It must be the real question the article answers — not a changelog-style heading, not omitted. If you're not sure how to phrase it, check the link text used for this article in its directory's `index.md`; that's the canonical phrasing.
+- **Link it from `index.md`.** Every subdirectory (`barcode-reader/general/`, `barcode-reader/web/configuration/`, `mrz-scanner/general/`, etc.) has an `index.md` that lists every article in that section. A new article with no entry there is orphaned — it exists but no one can navigate to it. Add a bullet there when you add the file, and remove the bullet if you remove the file.
+- **Internal links use `.html`, not `.md`.** Link to sibling/other articles as `some-page.html` (Jekyll serves the built output), and to a parent-directory archive as `../archive/some-page.html`, etc. A link ending in `.md` will not resolve on the live site.
+- **Don't add "back to index" links inside articles.** They were deliberately removed repo-wide; the sidebar/index already provides navigation.
+- **Images** go through a site variable per product/edition — `{{site.dbr_web_assets}}`, `{{site.dbr_mobile_assets}}`, `{{site.dbr_server_assets}}` (defined in `_config.yml`), pointing at that edition's `assets/` directory. Before referencing an image, confirm the file actually exists at that path — a stale or placeholder filename (e.g. a literal `undefined.png`) will silently 404.
+- **Write the answer as a direct statement, not a raw Q&A fragment.** Don't leave phrasing like "Yes — ..." or "This can be expanded ..." floating with no visible question or antecedent above it — the H1 is the question; the body should read as its answer, not as a leftover snippet.
+- **Don't duplicate a section under a second heading.** If a "what's new"/changelog-style heading and a "how to" heading right below it cover the same ground, merge them.
+
+## Directory map
+
+- `barcode-reader/general/` — cross-edition Barcode Reader FAQs
+- `barcode-reader/mobile/`, `barcode-reader/server/`, `barcode-reader/web/` — edition-specific Barcode Reader FAQs, each split into topic subdirectories (`configuration/`, `capabilities/`, `debug/`, `scan-setting/`, etc.)
+- `mrz-scanner/general/` — MRZ Scanner FAQs
+- `license/` — licensing FAQs shared across products
+
+## Archived content (`*/archive/*`)
+
+Directories named `archive` under `barcode-reader/{mobile,server,web}/` hold historical, version-pinned content (e.g. `-v9.6.40`, `-v10.4.2000` snapshots). They are:
+
+- Excluded from the Jekyll build via `_config.yml`'s `exclude:` list — not hosted, not in `sitemap.xml`.
+- Not linked from any live index or sidebar, and shouldn't be. Don't add new links into an `archive/` directory from a live page.
+- Not to be "modernized" — if you're editing a file in `archive/`, fix only structural issues (a truly broken build, a factual error introduced by your own change), not stale APIs or old terminology; that staleness is the point.
+
+If you find yourself wanting to *add* content to an archive directory, it almost certainly belongs in the live directory instead.
+
+## Before finishing
+
+Run the link checker from the repo root and fix anything it flags in files you touched:
+
+```bash
+python check_links.py
+```

README.md

@@ -1,84 +1,19 @@
----
-layout: default-layout
-title: Dynamsoft Capture Vision FAQ
-keywords: faq, capture vision, dcv, dynamsoft, barcode reader, mrz scanner
-description: Dynamsoft Capture Vision FAQ Documentation
-needAutoGenerateSidebar: false
-noTitleIndex: true
----
+# Dynamsoft FAQ
 
-# Dynamsoft Capture Vision FAQ
+Source for the FAQ site covering Dynamsoft's products, published at [dynamsoft.com/faq](https://www.dynamsoft.com/faq). This repo holds the Barcode Reader, MRZ Scanner, and licensing FAQs; Dynamic Web TWAIN (a separate product line, not part of Capture Vision) has its own FAQ section linked from the homepage (`index.md`) but sourced from a different repo.
 
-Select a product below to browse its FAQs.
+## Writing or editing an article
 
-<!-- Responsive 2x2-style grid (wraps to 1xN on small screens) -->
-<style>
-  .faq-grid {
-    display: grid;
-    grid-template-columns: repeat(auto-fit, minmax(260px, 1fr));
-    gap: 20px;
-    margin: 24px 0 8px 0;
-  }
-  .faq-tile {
-    display: block;
-    text-decoration: none;
-    padding: 28px 24px;
-    border-radius: 16px;
-    border: 1px solid rgba(0,0,0,0.06);
-    box-shadow: 0 6px 16px rgba(0,0,0,0.06);
-    transition: transform 0.08s ease, box-shadow 0.12s ease, border-color 0.12s ease;
-    background: #fff;
-  }
-  .faq-tile:hover,
-  .faq-tile:focus {
-    transform: translateY(-2px);
-    box-shadow: 0 10px 22px rgba(0,0,0,0.10);
-    border-color: rgba(0,0,0,0.12);
-    outline: none;
-  }
-  .faq-tile h2 {
-    margin: 0 0 8px 0;
-    font-size: 1.25rem;
-    line-height: 1.2;
-  }
-  .faq-tile p {
-    margin: 0;
-    color: #444;
-  }
-  .faq-tile .eyebrow {
-    display: inline-block;
-    font-size: 0.8rem;
-    letter-spacing: .06em;
-    text-transform: uppercase;
-    color: #666;
-    margin-bottom: 6px;
-  }
-  .faq-tile .emoji {
-    font-size: 1.35rem;
-    margin-right: .35rem;
-  }
+See [`AGENTS.md`](AGENTS.md) for the FAQ article structure, frontmatter, linking, and archive-directory conventions.
 
-  @media (min-width: 720px) {
-    .faq-grid {
-      grid-template-columns: repeat(2, 1fr);
-    }
-  }
-</style>
+## Building and deploying
 
-<div class="faq-grid">
+The site is built with Jekyll using a shared theme/layout maintained in [dynamsoft-docs/Docs-Template-Repo](https://github.com/dynamsoft-docs/Docs-Template-Repo), which this repo doesn't include locally. Pushes to `main` and `preview` trigger the CI workflows in `.github/workflows/main.yml`, which build and sync to production and the preview/testing environment respectively.
 
-  <!-- Barcode Reader -->
-  <a class="faq-tile" href="/faq/barcode-reader/index.html" aria-label="Barcode Reader FAQs">
-    <div class="eyebrow"><span class="emoji">📲</span>Barcode Reader</div>
-    <h2>Barcode Reader</h2>
-    <p>General usage, requirements, configuration, and troubleshooting guides.</p>
-  </a>
+## Checking links
 
-  <!-- MRZ Scanner -->
-  <a class="faq-tile" href="/faq/mrz-scanner/index.html" aria-label="MRZ Scanner FAQs">
-    <div class="eyebrow"><span class="emoji">🛂</span>MRZ Scanner</div>
-    <h2>MRZ Scanner</h2>
-    <p>Setup, supported formats, UI customization, and integration examples.</p>
-  </a>
+`check_links.py` crawls the repo's Markdown files and reports broken links. Run it before submitting a change that touches links:
 
-</div>
+```bash
+python check_links.py
+```

_config.yml

@@ -34,6 +34,15 @@ sad_icon: /faq/assets/img-icon/icon-sad.png
 plugins:
   - jekyll-sitemap
 
+# Archived, version-pinned FAQ content. Kept in the repo for reference,
+# but not built/hosted on the live site and not listed in sitemap.xml.
+exclude:
+  - barcode-reader/mobile/archive
+  - barcode-reader/server/archive
+  - barcode-reader/web/archive
+  # Plain repo-contributor README, not a site page.
+  - README.md
+
 defaults:
   - scope:
       path: ""

barcode-reader/general/avoid-incorrect-barcode-results.md

@@ -13,21 +13,15 @@ needAutoGenerateSidebar: false
 
 ---
 
-> **Notice (Temporary Issue)**  
-> This is a known issue in versions 11.0.0 - 11.0.6000 and has been fixed in version 11.2. 
->  
-> As a temporary solution, please set `IncludeTrailingCheckDigit` to `0` in the `BarcodeFormatSpecification` for Code128.  
-> This will prevent the SDK from returning the trailing check digit.
-
 ### CODE_128 decoding returns an extra byte?
 
 When using DBR v11, you may notice that decoding a **CODE_128** barcode returns one extra byte at the end if you call `item.get_bytes()`.
 
 **Cause**  
-By default, DBR includes the trailing check digit for CODE_128 in the decoded byte results.
+By default, DBR includes the trailing check digit for CODE_128 in the decoded byte results. This is a known issue in versions 11.0.0 - 11.0.6000 and has been fixed in version 11.2.
 
 **Solution**  
-Set `IncludeTrailingCheckDigit` to `0` in the `BarcodeFormatSpecification` for Code128.
+Set `IncludeTrailingCheckDigit` to `0` in the `BarcodeFormatSpecification` for Code128. This will prevent the SDK from returning the trailing check digit.
 
 **Example JSON Configuration**
 

barcode-reader/general/avoid-incorrect-results.md

@@ -6,6 +6,6 @@ description: How to filter results with the barcode result length?
 needAutoGenerateSidebar: false
 ---
 
-# How to filter results with the barcode result length?
+# How to filter incorrect results with the barcode result length?
 
 One way to filter results is to set the [minBarcodeTextLength](https://www.dynamsoft.com/barcode-reader/docs/server/programming/cplusplus/api-reference/simplified-barcode-reader-settings.html#:~:text=int%20minResultConfidence%3B-,int%20minBarcodeTextLength%3B,-char%20barcodeTextRegExPattern%5B) in [SimplifiedBarcodeReaderSettings](https://www.dynamsoft.com/barcode-reader/docs/server/programming/cplusplus/api-reference/simplified-barcode-reader-settings.html#:~:text=SimplifiedBarcodeReaderSettings-,SimplifiedBarcodeReaderSettings,-The%20SimplifiedBarcodeReaderSettings%20struct) of [SimplifiedCaptureVisionSettings](https://www.dynamsoft.com/capture-vision/docs/server/programming/cplusplus/api-reference/capture-vision-router/structs/simplified-capture-vision-settings.html?product=dbr&repoType=server) to the correct length that the barcode results should be. Say that the barcode results should at least be 10 characters long, and the results are sometimes coming out with just 6 or 7 characters. By setting the minBarcodeTextLength to 10, the SDK will ignore results that are shorter than 10 characters.

barcode-reader/general/check-current-version.md

@@ -11,11 +11,10 @@ needAutoGenerateSidebar: false
 There are multiple ways to check the version currently being used -
 
 - The first way is to use the [version API](https://www.dynamsoft.com/barcode-reader/docs/web/programming/javascript/api-reference/barcode-reader-module-class.html#getversion). Using this API in the browser console should print out the version of the library being used by the web app.
-- If you are using the library via npm or yarn, then you can check the version of the package via
-
-    ```bash
-    npm –v dynamsoft-javascript-barcode
-    ```
+- If you are using the library via npm or yarn, then you can check the installed version of the package via `npm list`. Note that the npm package has been renamed across major versions:
+    - Version 11 and above: `npm list dynamsoft-barcode-reader-bundle`
+    - Version 10: `npm list dynamsoft-barcode-reader`
+    - Version 9: `npm list dynamsoft-javascript-barcode`
 
 - If you are including the library via the CDN link, then the version number should be mentioned in that reference link.
 
@@ -45,7 +44,7 @@ print("Dynamsoft Barcode Reader Version: \(version)")
 ```
 >
 ```java
-BarcodeReaderModule reader = BarcodeReaderModule();
+BarcodeReaderModule reader = new BarcodeReaderModule();
 String versionInfo = reader.getVersion();
 ```
 >

barcode-reader/mobile/archive/android/debug-mode.md

@@ -8,8 +8,6 @@ needAutoGenerateSidebar: true
 
 # How to use Debug Mode in Barcode Scanner X?
 
-## Debug Mode in BarcodeScannerX(Android)
-
 If you are experiencing app crashes in your own application or you’ve come across some barcode(s) that you can’t read and you have exhausted all of the other troubleshooting methods, Debug Mode of the [BarcodeScannerX](https://www.dynamsoft.com/barcode-reader/sdk-mobile/#appDemo) demo app can help offer one last effort to resolve these issues.
 
 This next section will explain how to toggle on debug mode on the demo app, and will then dive into how to collect crash logs and/or image samples.

barcode-reader/mobile/archive/android/index-v10.4.2000.md

@@ -29,7 +29,7 @@ noTitleIndex: true
 
 10. [Can I reduce the size of the final Android app?](reduce-final-size.md)
 
-11. [How to use Debug Mode in Barcode Scanner X?](debug-mode-barcodescannerx.md)
+11. [How to use Debug Mode in Barcode Scanner X?](debug-mode.md)
 
 12. [How to prevent project build failure after shrinking code?](proguard.md)
 

barcode-reader/mobile/archive/android/no-camera-enhancer-v9.6.40.md

@@ -8,6 +8,6 @@ needAutoGenerateSidebar: true
 
 # How can I use CameraX or third-party camera modules with Dynamsoft Barcode Reader?
 
-You can read this [article](../samples/no-camera-enhancer.md) on how to use the video stream via CameraX such that the output frames from `CameraX` are converted into `imageData` which can be used as input for the barcode reader. If you would like to see a quick code snippet on how to convert these frames from `CameraX` into `ImageData`, please see it <a href="https://www.dynamsoft.com/barcode-reader/docs/mobile/programming/android/api-reference/primary-decode.html?ver=latest#get-imagedata-from-android-camera2" target="_blank">here</a>. 
+You can read this [article](../../configuration/no-camera-enhancer.md) on how to use the video stream via CameraX such that the output frames from `CameraX` are converted into `imageData` which can be used as input for the barcode reader. If you would like to see a quick code snippet on how to convert these frames from `CameraX` into `ImageData`, please see it <a href="https://www.dynamsoft.com/barcode-reader/docs/mobile/programming/android/api-reference/primary-decode.html?ver=latest#get-imagedata-from-android-camera2" target="_blank">here</a>. 
 
 > **_NOTE:_** The Barcode Reader decodes barcodes from an `ImageData` object. The `ImageData` object stores the pixel buffer, width, height, stride and pixel format of the image. *However, it is always recommended to use DBR in conjunction with DCE for the best results and performance*.

barcode-reader/mobile/archive/ios/drivers-license-extraction-v9.6.40.md

@@ -8,6 +8,6 @@ needAutoGenerateSidebar: true
 
 # Can I extract the driver’s information from a PDF417 barcode?
 
-In the Barcode Scanner X(mobile app), "US Driver's License" scenario is able to parse driver's information from driver's licenses.
+In the Barcode Scanner X (mobile app), "US Driver's License" scenario is able to parse driver's information from driver's licenses.
 
 At the moment, there is no external framework that is responsible for this function in the sample. However, the team is currently developing an edition of our complimentary product, the *Dynamsoft Code Parser*, that is compatible with the mobile platform.

barcode-reader/mobile/archive/ios/index.md

@@ -86,7 +86,7 @@ func onDecodedBarcodesReceived(_ result: DecodedBarcodesResult) {
 }
 ```
 
-## How to resolve the "Building for iOS Simulator, but linking in dylib built for iOS" error when building for the iOS simulator?](arm64-simulator-error.md)
+## How to resolve the "Building for iOS Simulator, but linking in dylib built for iOS" error when building for the iOS simulator?
 
 DBR iOS can be used to build apps that belong to the arm64 architecture. If you try building an app for the arm64 simulator, and you migrated your app from an older version of Xcode to Xcode 12 or higher, then you might encounter the following error message:
 
@@ -238,7 +238,7 @@ Nowadays, most QR codes are QR code Model 2. BarcodeScannerX, by default, only s
 7. Click **Import Template** in the Advanced Scan settings of BarcodeScannerX. Then input the link.
 8. Now you can scan QR code Model 1!
 
-## How to Handle Non-printable Characters Like "\u{1D}" or "{GS}" from the Barcode Text?]({{site.faq_general}}unprintable-character.html?lang=objc,swift)
+## How to Handle Non-printable Characters Like "\u{1D}" or "{GS}" from the Barcode Text?
 
 This page helps to you modify the barcode results when non-printable characters exists in the barcode text you decoded.
 

barcode-reader/mobile/capabilities/index.md

@@ -7,5 +7,7 @@ needAutoGenerateSidebar: false
 noTitleIndex: true
 ---
 
+# Capabilities Index
+
 - [Architecture armv7 Error](armv7-architecture-error.html)
 - [Minimum System Requirements](min-system-requirements.html)

barcode-reader/mobile/configuration/no-camera-enhancer.md

@@ -6,15 +6,15 @@ description: How can I use AVCaptureSession, CameraX or third-party camera modul
 needAutoGenerateSidebar: true
 ---
 
-# How can I use AVCaptureSession, CameraX or third-party camera modules with Dynamsoft Barcode Reader - Android?
+# How can I use AVCaptureSession, CameraX or third-party camera modules with Dynamsoft Barcode Reader?
 
-# Android
+## Android
 
-## CameraX
+### CameraX
 
-If you are using the CameraX, you can view [HelloWorld/DecodeWithCamerX sample](https://github.com/Dynamsoft/barcode-reader-mobile-samples/tree/main/android/FoundationalAPISamples/DecodeWithCameraX) for a quick start.
+If you are using CameraX, you can view [HelloWorld/DecodeWithCameraX sample](https://github.com/Dynamsoft/barcode-reader-mobile-samples/tree/main/android/FoundationalAPISamples/DecodeWithCameraX) for a quick start.
 
-## Third-Party Camera Module
+### Third-Party Camera Module
 
 If you are using a third-party camera module, what you have to do is:
 
@@ -23,13 +23,13 @@ If you are using a third-party camera module, what you have to do is:
 - Create an instance of the [CaptureVisionRouter](https://www.dynamsoft.com/capture-vision/docs/mobile/programming/android/api-reference/capture-vision-router/multiple-file-processing.html?product=dbr&lang=android) class. Then trigger the [`setInput`](https://www.dynamsoft.com/capture-vision/docs/mobile/programming/android/api-reference/capture-vision-router/multiple-file-processing.html#setinput) method with the instance of your camera class as the parameter.
 - Trigger the [`startCapturing`](https://www.dynamsoft.com/capture-vision/docs/mobile/programming/android/api-reference/capture-vision-router/multiple-file-processing.html#startcapturing) method to start the barcode decoding.
 
-# iOS
+## iOS
 
-## AVCaptureSession
+### AVCaptureSession
 
-If you are using the CameraX, you can view [HelloWorld/DecodeWithAVCaptureSession sample](https://github.com/Dynamsoft/barcode-reader-mobile-samples/tree/main/ios/FoundationalAPISamples/DecodeWithAVCaptureSession) for a quick start.
+If you are using AVCaptureSession, you can view [HelloWorld/DecodeWithAVCaptureSession sample](https://github.com/Dynamsoft/barcode-reader-mobile-samples/tree/main/ios/FoundationalAPISamples/DecodeWithAVCaptureSession) for a quick start.
 
-## Third-Party Camera Module
+### Third-Party Camera Module
 
 If you are using a third-party camera module, what you have to do is:
 

barcode-reader/mobile/configuration/reduce-battery-consumption.md

@@ -20,7 +20,7 @@ If scanning is only needed occasionally, be sure to stop the camera and barcode
 Call the appropriate method to stop capturing:
 
 - **Android**: [`stopCapturing`](https://www.dynamsoft.com/capture-vision/docs/mobile/programming/android/api-reference/capture-vision-router/multiple-file-processing.html?product=dbr&lang=android#stopcapturing)  
-- **iOS**: [`stopCapturing`](http://dynamsoft.com/capture-vision/docs/mobile/programming/ios/api-reference/capture-vision-router/multiple-file-processing.html?product=dbr&lang=objectivec-swift#stopcapturing)
+- **iOS**: [`stopCapturing`](https://www.dynamsoft.com/capture-vision/docs/mobile/programming/ios/api-reference/capture-vision-router/multiple-file-processing.html?product=dbr&lang=objectivec-swift#stopcapturing)
 
 This ensures that system resources like the camera and CPU are properly released, reducing battery drain.