Internal Linking

Automatic cross-linking between related pages for link equity distribution and discoverability.

Why Internal Linking Matters

Internal links serve two critical SEO functions:

1. Crawl discovery — Search engine bots follow internal links to find and index new pages. Without links, pages are "orphaned" and may never be crawled.
2. Link equity distribution — Pages that receive external backlinks pass "authority" to the pages they link to. A well-linked site distributes this equity across all pages, improving rankings site-wide.

With thousands of programmatic pages, manual linking is impossible. Contento automates the entire process.

How It Works

The internal linking engine runs automatically during every publish operation. It follows a three-step process:

1. Related Page Discovery

The linker identifies related pages using these signals:

• Same niche — Pages in the same niche are always related (e.g., two Developer Tools pages)
• Subtopic similarity — Pages covering related subtopics within the same niche (e.g., "CI/CD pipelines" and "container orchestration")
• Same schema type — Pages using the same content type are weighted slightly lower to encourage cross-type linking

The algorithm produces a ranked list of related pages for each newly published page.

2. Link Selection

From the ranked list, the linker selects 2–4 links per page. The selection prioritizes:

• Pages in the same niche (strongest signal)
• Pages with different content types (for content diversity)
• Pages that currently have the fewest inbound internal links (equity balancing)

3. Link Injection

Links are injected into the page content in two locations:

• Contextual links — Anchor text links placed naturally within the content body where subtopics are mentioned
• Related pages section — A "Related Articles" block appended after the main content and before the CTA

<!-- Contextual link (injected into content) -->
<p>When setting up your CI/CD pipeline, you should also consider
<a href="/container-orchestration-checklist">container orchestration</a>
as part of your deployment strategy.</p>

<!-- Related pages section (appended after content) -->
<aside class="related-pages">
  <h3>Related Articles</h3>
  <ul>
    <li><a href="/100-devops-ideas-2026">100 DevOps Ideas for 2026</a></li>
    <li><a href="/infrastructure-as-code-checklist">The Ultimate Infrastructure as Code Checklist</a></li>
    <li><a href="/container-orchestration-faq">Container Orchestration FAQ</a></li>
  </ul>
</aside>

Bidirectional Updates

When new pages are published, the linker does not just add links from the new pages. It also updates existing pages to link to the new content. This means:

• A page published last week can receive new internal links when related pages are published today
• The link graph evolves over time as more content is added
• Orphaned pages are automatically connected as related content appears

Link Configuration

Setting	Default	Description
Contextual links per page	1–2	Anchor text links placed within the content body
Related pages per page	3	Links shown in the "Related Articles" section
Link scope	Same niche	Links are only created between pages in the same niche
Cross-type linking	Enabled	Link between different content types (e.g., idea list to checklist)

Monitoring Internal Links

Internal link statistics are generated automatically during contento build. When you build your project, the build output includes a summary of internal links created:

$ contento build --output ./dist/articles

  Building 248 pages...
  ✓ Internal linking pass: 892 cross-links across 248 pages
  ✓ Avg links per page: 3.6
  ✓ Orphaned pages: 0
  ✓ Sitemap rebuilt: 248 URLs
  Built to: ./dist/articles/

Orphaned pages (zero inbound links) should always be zero in a healthy Contento installation. If the count is non-zero, it usually means pages were manually unpublished, leaving dangling references. Re-running the build fixes this.