blog
Automatic internal links and TF-IDF focus keywords for a bilingual Markdown blog
TF-IDF suggests the focus keyword, a Node script writes internal links straight into the .md files of each language, and I review every anchor with git diff instead of letting the build insert them.
- Published
Every blog post on this site has a focusKeyword, and the posts link to each other with automatic internal links. Both come from Node scripts that read the content/ folder directly: TF-IDF suggests the keyword, I review it, then link:internal writes the links into the .md files themselves. The blog has 2 languages, so every step runs separately for content/blog/ and content/en/blog/.
TF-IDF suggests focus keywords, I pick the final phrase
npm run seo:keywords prints 5 candidates per post. The script takes every n-gram of 1 to 3 tokens, drops phrases that start or end with a stopword, then scores them. Each position has its own weight: title 5, tag 4, heading 3, description 2, body 1. N is the number of posts in the language being scored.
const idf = Math.log((N + 1) / (d + 1)) + 1
let score = t.tf * idf * (1 + 0.3 * (n - 1))
if (t.exactTag || containsPhrase(titleTokens, phrase)) score *= 1.5
Each extra token in a phrase adds 30% to the score, and a phrase that matches a tag exactly or sits inside the title is multiplied by 1.5. 3 filters run before the formula: a phrase that appears in more than 3 posts (df > 3) is dropped because it cannot tell posts apart; the phrase must be in the post's own title, heading or tag and repeat at least 2 times in the body; a 1-token phrase passes only if it is an exact tag or a capitalized proper name in the title.
The result is still only about half usable. One run on 4 Vietnamese posts, scores will change as the blog grows:
| Post | TF-IDF top 1 | Focus keyword I chose |
|---|---|---|
| Claude Code subagent cost | final review (135.8) | subagent Claude Code |
| Gemini 3.6 Flash on Antigravity | Flash (144.6) | Antigravity CLI |
| Fable 5.2 and prompts | bảng giá ("price table", 31.3) | Fable 5.2 |
| Loop engineering | no candidates | loop engineering |
final review really appears in the subagent post, but nobody types it into Google to find a post about subagent cost. TF-IDF measures which phrase is distinctive for a post, not what a reader types. Vietnamese has no word segmentation step, so truncated phrases slip through: the subagent post produced phí mỗi lượt (51.0) instead of "chi phí mỗi lượt" (cost per call), and the skills post produced UI UX Pro and UX Pro Max (both 55.1) for one name, UI UX Pro Max.
That is why the script never writes the top 1 directly. It exports a proposal file, I edit it by hand, and --write reads only the reviewed file:
node scripts/seo-keywords.js --out $TMPDIR/kw.txt # one line each: vi/<slug> = <top 1>
node scripts/seo-keywords.js --write $TMPDIR/kw.txt
--write inserts exactly 1 focusKeyword: '...' line right before the first date: line, and it avoids matter.stringify because that function reformats the whole YAML. The file is parsed again and compared with the phrase just written, and a mismatch restores the old file. A post that already has a focusKeyword is skipped, so a second run adds nothing. The first write, on 3 Nov 2026, touched 38 files with exactly 1 line each.
The 2 languages do not translate each other's keywords: subagent Claude Code and Claude Code subagent, trang nén and compressed pages, dịch ngược phần mềm and reverse engineering. Each language picks the phrase its own readers type.
check:keywords: 7 places the focus keyword should appear
npm run check:keywords checks that focusKeyword appears in the title, seo.title, description, the first 100 words of the body, the slug, one H2 and the alt of an image. Comparison is lowercase with diacritics stripped. The gate is soft and always exits 0. Output of one run (the script prints its messages in Vietnamese: thiếu ở means "missing in"):
[vi] nang-cap-website-nextjs-16 (Next.js 16): thiếu ở slug
[en] ai-engineer-roadmap-2026 (AI Engineer roadmap): thiếu ở 100 từ đầu
30/44 bài đạt đủ
A missing slug I leave alone: changing a slug changes the URL and needs a redirect. A missing title, description or opening paragraph gets a natural rewrite. The alt still has to describe the picture, and it carries the keyword only when the description stays accurate.
link:internal writes automatic internal links: dry-run, --write, git diff
npm run link:internal # dry-run, prints: slug: "anchor" -> /url
node scripts/link-internal.js --write # write into the .md files
git diff content/ # review every anchor
Targets are posts with a focusKeyword; the matching text is focusKeyword plus aliases, longest phrase first. The script matches only in prose and skips code, headings, existing links, <Callout> and <Checklist>. It takes the first match at character 200 of the body or later, keeps the original text as the anchor ([original text](url)), and uses Unicode word boundaries, so claude does not match inside claude-code or CLAUDE.md. Each source post gets at most 3 new links per run (--max n changes that), and no more than 8 internal links in total. The target with the fewest inbound links goes first, and the counter updates inside the loop so links spread out.
When writing, the script builds all the new content in memory first, so an error leaves every file untouched. Files with CRLF or a BOM are refused. It does not bump updated, because wrapping an anchor changes no fact.
The first --write on 38 posts inserted exactly 2 links, 1 per language. The English one:
-... compressed pages at 0%. The measuring loop, every 30 seconds ...
+... [compressed pages](/en/macos-compressed-pages-spike-agent-wait-loop) at 0%. The measuring loop, every 30 seconds ...
It is a small number because a focusKeyword rarely repeats verbatim in other posts. To get more matches, add aliases: ['other phrase'] to the target post. noLink: ['phrase'] works the other way, but it blocks by text, not by position: every match of that text is skipped, including the good ones. For a bad anchor it is usually simpler to edit the anchor text in the file by hand: the source already links to the target, so the next run skips that pair. No post declares aliases or noLink yet, and the npm run link:internal dry-run currently prints 0 link.
Why internal links live in the .md file, not in the build
An anchor is part of the post's text. If the build inserted it, the published post would differ from the one I read in the editor, and changing the focusKeyword of one target would change links in other posts with no diff to look at. With links in the .md, every anchor is one changed line, git diff is the review step, and git revert is the way back. There is no automatic write mode in CI.
The cost is real. A new post gets no inbound links until I run the script. Inserting a link does not bump updated, so the sitemap lastmod does not reflect it. The masking still misses rare cases, such as a blockquote nested in JSX or inline HTML in the middle of a line, so reading the diff is the last safety net.
After the build, check:links (inside postbuild) scans out/: a dead internal link or a cross-language link in a post body fails the build. Orphan posts only warn, and they are counted from the .md body, not from the HTML, because the "Related posts" block is ordered by tag and gives every post an inbound link in the HTML. My next step is to add aliases to the target posts that deserve the most links, then review the dry-run in small batches.
Related posts
all posts →- SEO and link gates on the Next.js build output: check the built HTML, not the source2 postbuild gates read out/**/*.html: canonical, og:image, two-way hreflang, duplicate titles, sitemap xhtml:link and dead internal links. A failure stops the build before deploy.read more →
- Deferred GA4 and AdSense in a static Next.js site: 1.3 MB of JS out of the headgtag.js and adsbygoogle.js add up to about 1.3 MB of uncompressed JS. One component loads them after the first interaction or when the browser is idle, only on the real domain, so they stay off the main thread during page load.read more →
- Removing @tailwindcss/aspect-ratio: a silent failure that made every cover 0px tallThe aspect-ratio plugin replaces theme.aspectRatio, so Tailwind core stops emitting aspect-video. Image boxes collapse to 0px, every cover vanishes, and the build stays green.read more →
- Critical CSS for static Next.js: critters, fonts and the first screen on PSI mobileMy static Next.js site hit 3 PSI mobile traps: render-blocking CSS, inlined fonts loading too early, and JS gating the first screen. Here is how I fixed each, starting with critical CSS from critters at postbuild.read more →