Overview
When I first started this site, it was meant to be a simple project portfolio I could refer back to. Eventually it reached a point where the website itself became a project, and a place I could turn into a living resume. Now, nearly everything I do professionally outside of work is documented here, and I wanted to make it easy for visitors (and myself) to find related content when viewing articles.
I briefly talked about this problem at work and a coworker suggested I try k-means clustering (that's all she said). Following a brief research period, I implemented a TF-IDF + k-means + cosine similarity approach. A single script handles scoring and storing relationships: TF-IDF scores how important each word is to an article relative to the rest, k-means groups articles into topical clusters, and cosine similarity ranks how closely related articles are to each other. The output is a small JSON file that maps and ranks each article and its related articles.
The result was discoverability without the need for search, and without adding a backend service (that is super important, trying to do as much as I can without a server). There are no external dependencies, no additional libraries, and recommendations are consistent and relevant. All recommendation processing is performed at build time. Every time an article is added, updated, or removed and the website is rebuilt, recommendations are automatically updated.
Generating Related Articles Process
The article generation process runs in five major phases.
Phase 1: Parse, Normalize, and Tokenize Article Content
The script that generates the recommendations scans every article, loads each HTML file, and extracts three elements: Title, tags, and article body text. It strips HTML, normalizes text, removes stopwords, and tokenizes the remaining content.
Those tokens are converted into weighted term frequencies so curated metadata matters more than raw body text.
// Weighted frequencies used in the script:
// - title: 1.5x (strong intent signal)
// - tags: 2x (curated metadata)
// - body: 1x (broad context)
mergeWeightedFrequency(weightedFreq, titleFreq, 1.5)
mergeWeightedFrequency(weightedFreq, tagFreq, 2)
mergeWeightedFrequency(weightedFreq, bodyFreq, 1)
Phase 2: Build Weighted TF-IDF Vectors
After weighted term frequencies are built, the script calculates smoothed IDF and creates a TF-IDF vector for each article. Vectors are L2-normalized (scaled to length 1), so cosine similarity is just a dot product, which means multiplying matching values in both vectors and summing them into one similarity score.
Example: If two articles both use words like "tensorflow", "model", and "inference", their normalized vectors line up and produce a higher dot product. If they use different terms, the dot product is lower, so they are less likely to be recommended together.
const idf = Math.log((1 + totalDocs) / (1 + df)) + 1
vec.set(token, tf * idf)
doc.vector = l2Normalize(vec)
Phase 3: Cluster by Topic with K-Means
The script also runs cosine-based k-means clustering. Cluster count is determined with a simple calculation based on the number of articles. The result is a cluster ID for each article, and then recommendations prioritize/default same-cluster candidates before using cross-cluster fallback.
function pickK(count) {
if (count <= 3) return Math.max(1, count)
const k = Math.round(Math.sqrt(count / 2))
return Math.max(2, Math.min(8, k))
}
Phase 4: Score, Rank, and Filter Recommendations
Candidate ranking uses a combined score: semantic cosine overlap plus a small tag-overlap boost. This gives semantic matching first, while still rewarding explicit shared tags. As the content is already divided into distinct 'types', I wanted a way to give a small boost to articles that share tags, and are naturally similar. So, I added a 0.2 * Jaccard similarity term to the score.
score = cosine(vectorA, vectorB) + 0.2 * jaccard(tagsA, tagsB)
Candidates from the same cluster are considered first, then cross-cluster candidates are used as fallback. Everything is ranked by score descending so the best overall matches surface first.
In the current implementation, only results with score >= 0.11 are kept (which will be increased as we add more articles and there are more naturally occurring matches), and each article is capped to 8 related entries.
Phase 5: Output to JSON
The generator outputs to a JSON file. Each article slug maps to a cluster ID and a ranked related list with scores. The JSON file includes metadata and associated information for internal purposes; build time, methods, scores, clusters, and tags found in each cluster for easy identification of trends and where articles fall.
{
"version": 2,
"method": "tfidf+kmeans+cosine",
"minRelatedScore": 0.11,
"maxObservedScore": 0.428571,
"items": {
"some-article-slug": {
"cluster": 1,
"related": [
{ "slug": "another-article", "score": 0.251337 }
]
}
}
}
Tunable Parameters
There are several parameters I can adjust to fine-tune article recommendations:
- Minimum related score to tighten or loosen match quality.
- Title/tag/body weights to control influences.
- Number of clusters k-means should use.
- Max related articles per article (currently 8), to keep the UI clean.
Saturation Curved Match Percentage
Raw similarity scores are useful for ranking and internal metrics/debugging, but when attempting to convey relevance to a user, they aren't very helpful. A linear percentile conversion like this can cause dissimilar articles to appear similar and keep scores too close together. To make the scores more distinct while keeping them believable, I created an exponential saturation curved approach so lower and mid-range scores spread out naturally while high scores will have diminishing returns as they approach (but do not hit) 100%.
function scoreToMatchPercent(score) {
// Saturating transform: approaches 100 without actually reaching it.
const tau = 0.35
const scaled = 100 * (1 - Math.exp(-score / tau))
return Math.min(99, Math.max(0, Math.round(scaled)))
}
I cap at 99% on purpose so no recommendation looks absolutely certain (nor will it ever hit 99%, the articles would have to be identical). This keeps the UI believable, avoids overconfident and misleading labels, and gives better visual separation in the related articles carousel.