Develop Documentation Search & Discoverability Analyzer - #187
Open
jankiluitel wants to merge 2 commits into
Open
jankiluitel wants to merge 2 commits into
jankiluitel wants to merge 2 commits into
Conversation
✅ Deploy Preview for thoth-tech ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
jankiluitel
requested review from
Kachi-Okorie and
omckeon
and removed request for
omckeon
September 17, 2026 05:54
Rhinoatron
approved these changes
Sep 17, 2026
Rhinoatron
left a comment
Rhinoatron
left a comment
There was a problem hiding this comment.
Great work on this. The analyzer covers the requested checks, produces a useful report without changing the documentation, and I found no overlapping PR. One minor note: both changed files need a trailing newline to satisfy the current CI lint check. That doesn’t at all affect the analyzer itself, so I’m happy to approve this from my side.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
This PR introduces a Documentation Search & Discoverability Analyzer for the ThothTech Documentation Website.
The analyzer provides a repository-wide way to identify documentation that may be difficult to discover, distinguish, or navigate. Rather than modifying documentation automatically, it generates actionable information for contributors to review.
Features
The analyzer currently:
Scans all Markdown and MDX documentation recursively.
Detects missing and empty page descriptions.
Identifies missing and potentially weak/generic titles.
Analyses internal documentation relationships using both Markdown links and HTML/MDX href links.
Builds an internal link graph and identifies pages with no detected incoming content links as potentially orphaned.
Detects exact duplicate documentation titles.
Uses token-based Jaccard similarity analysis to identify highly similar titles.
Separates exact duplicate titles from potentially similar titles to reduce misleading results.
Produces a structured console report summarising the analysis.
Usage
The analyzer can be run locally using:
npm run docs:analyze
Current Analysis
Running the analyzer against the current documentation collection produced:
224 documents analysed
168 internal documentation links identified
184 metadata discoverability issues
158 potentially orphaned documents
19 exact duplicate-title pairs
1 potentially similar-title pair
Potentially orphaned documents are intentionally treated as an informational signal rather than confirmed inaccessible pages, as pages may still be discoverable through Starlight navigation or search.
Testing
npm run docs:analyze — completed successfully.
npm run build — completed successfully.
224 pages built successfully.
Pagefind search index generated successfully from 226 HTML files.
Existing internal-link validation passed.
Files Changed
Added scripts/documentation-search-analyzer.mjs
Added the docs:analyze npm script to package.json
Purpose
This tool is intended to help contributors maintain documentation quality as the website grows by providing visibility into metadata quality, content relationships, potential navigation gaps, and ambiguous documentation titles