Internal linking in MDX

Internal links help readers move through a site and help search engines understand how pages relate to each other.

Link when the next page is useful

A documentation page about rendering can naturally link to performance, Core Web Vitals, or JavaScript strategy. A service page can link to a relevant case study. The link should exist because the destination helps continue the topic.

Avoid manufactured linking

We do not force ten links into every page to hit an arbitrary SEO target. Excessive linking can make content harder to read and weakens the meaning of each link.

Use descriptive anchor text

The words in the link should identify the destination. That helps people scanning the page and gives search engines useful context.

Link across content types

Strong site architecture connects docs, services, portfolio work, and articles where the relationship is real. Documentation should not become an isolated library.

Keep routes stable

Internal links should point to canonical routes. If a route changes, update the source links rather than relying forever on redirect chains.

Think in topic paths

A good internal linking system lets a reader move from explanation to proof to service without being pushed through a sales funnel on every paragraph. The information architecture should do most of the work.

MDX makes contextual linking easy, which means we have to use it carefully

Because the body is ordinary Markdown, adding an internal link is simple. That is useful when a paragraph naturally introduces another service, guide, case study, or supporting explanation. It also makes overlinking easy. A content library can quickly become noisy if every related phrase is linked merely because a destination exists.

Our standard is to link when the destination advances the reader's task.

Documentation should explain its own vocabulary

The docs library is a good example. A page introducing server-first architecture can link to the JavaScript budget, static generation, and Server Components because those pages answer natural follow-up questions. A sitemap guide can link to the lastmod guide because the two systems interact directly.

That creates depth without repeating the same explanation on every page.

Commercial links need context

Articles can support service pages, but the link should make sense inside the subject. On the connectrader site, related commercial links are derived from constrained topic rules and limited in number. The system is designed to surface a small number of relevant next steps rather than attach the entire service catalog to every article.

That distinction matters. Internal linking is useful when it clarifies relationships. It becomes obvious SEO machinery when the page is covered with unrelated destinations.

We update source links when routes move

Redirects are necessary during migrations, but they should not become the permanent internal-link layer. If a canonical route changes, MDX links should eventually point to the new route directly. That reduces redirect chains, keeps analytics cleaner, and makes the source accurately describe the current site.

Anchor text should carry meaning

A link such as why our website content lives in the repository tells the reader exactly what they will get. "Click here" does not. Descriptive anchors improve scanning, accessibility, and the semantic relationship between documents at the same time. The larger internal-link strategy is covered in Internal linking architecture. MDX is simply the authoring surface where many of those relationships become explicit.