Module

analysis.link_types

Semantic Link Types and Connectivity Scoring for Bengal SSG.

This module defines the semantic relationships between pages and provides weighted connectivity scoring to replace binary orphan detection.

Link Types:

  • EXPLICIT: Human-authored markdown links text
  • MENU: Navigation menu items (highest editorial intent)
  • TAXONOMY: Shared tags/categories
  • RELATED: Algorithm-computed related posts
  • TOPICAL: Section hierarchy (parent _index.md → children)
  • SEQUENTIAL: Next/prev navigation within sections

Connectivity Levels:

  • WELL_CONNECTED: Score >= 2.0 (no action needed)
  • ADEQUATELY_LINKED: Score 1.0-2.0 (could improve)
  • LIGHTLY_LINKED: Score 0.25-1.0 (should improve)
  • ISOLATED: Score < 0.25 (needs attention)

Example:

>>> metrics = LinkMetrics(explicit=2, taxonomy=1, topical=1)
>>> score = metrics.connectivity_score()
>>> level = ConnectivityLevel.from_score(score)
>>> print(f"Score: {score}, Level: {level.value}")
Score: 3.5, Level: well_connected
View source
4 Classes

Classes

LinkType
Semantic relationship types between pages. Links carry meaning beyond simple connectivity. The typ…
0

Semantic relationship types between pages.

Links carry meaning beyond simple connectivity. The type indicates the editorial intent and discoverability value of the relationship.

Inherits from Enum

Attributes

Name Type Description
EXPLICIT —

Human-authored markdown links text in content
MENU —

Navigation menu item (deliberate prominence)
TAXONOMY —

Shared tags/categories (topic clustering)
RELATED —

Algorithm-computed related posts (automated)
TOPICAL —

Section hierarchy parent → child (topical context)
SEQUENTIAL —

Next/prev navigation within section (reading order)
LinkMetrics dataclass
Detailed link breakdown for a page. Tracks the count of each link type pointing to a page, enablin…
6

Detailed link breakdown for a page.

Tracks the count of each link type pointing to a page, enabling weighted connectivity scoring.

Attributes

Name Type Description
explicit int

Count of explicit markdown links
menu int

Count of menu item references
taxonomy int

Count of shared taxonomy links
related int

Count of related post links
topical int

Count of section hierarchy links (parent → child)
sequential int

Count of next/prev navigation links

Methods 6

connectivity_score
Calculate weighted connectivity score.
1 float 
def connectivity_score(self, weights: dict[LinkType, float] | None = None) -> float

Calculate weighted connectivity score.

Parameters 1
weights dict[LinkType, float] | None

Optional custom weights. Defaults to DEFAULT_WEIGHTS.
Returns

float —

Weighted sum of all link counts. Higher = better connected.

total_links
Total number of incoming links (unweighted).
0 int 
def total_links(self) -> int

Total number of incoming links (unweighted).

Returns

int

has_human_links
True if page has any human-authored links (explicit or menu).
0 bool 
def has_human_links(self) -> bool

True if page has any human-authored links (explicit or menu).

Returns

bool

has_structural_links
True if page has structural links (section/nav).
0 bool 
def has_structural_links(self) -> bool

True if page has structural links (section/nav).

Returns

bool

has_any_links
True if page has any incoming links.
0 bool 
def has_any_links(self) -> bool

True if page has any incoming links.

Returns

bool

to_dict
Convert to dictionary for serialization.
0 dict[str, int] 
def to_dict(self) -> dict[str, int]

Convert to dictionary for serialization.

Returns

dict[str, int]

ConnectivityLevel
Connectivity classification based on weighted score thresholds. Replaces binary orphan/not-orphan …
4

Connectivity classification based on weighted score thresholds.

Replaces binary orphan/not-orphan with nuanced levels that reveal opportunities for improvement.

Levels (from best to worst):

  • WELL_CONNECTED: Score >= 2.0 (no action needed)
  • ADEQUATELY_LINKED: Score 1.0-2.0 (could improve)
  • LIGHTLY_LINKED: Score 0.25-1.0 (should improve)
  • ISOLATED: Score < 0.25 (needs attention)
Inherits from Enum

Methods 4

emoji property
Get emoji indicator for this level.
str 
def emoji(self) -> str

Get emoji indicator for this level.

Returns

str

label property
Get human-readable label for this level.
str 
def label(self) -> str

Get human-readable label for this level.

Returns

str

description property
Get description of what action is needed for this level.
str 
def description(self) -> str

Get description of what action is needed for this level.

Returns

str

from_score classmethod
Classify a page based on its connectivity score.
2 ConnectivityLevel 
def from_score(cls, score: float, thresholds: dict[str, float] | None = None) -> ConnectivityLevel

Classify a page based on its connectivity score.

Parameters 2
score float

Weighted connectivity score from LinkMetrics
thresholds dict[str, float] | None

Optional custom thresholds. Defaults to DEFAULT_THRESHOLDS.
Returns

ConnectivityLevel —

ConnectivityLevel classification

ConnectivityReport dataclass
Complete connectivity report for a site. Groups pages by connectivity level and provides distribut…
3

Complete connectivity report for a site.

Groups pages by connectivity level and provides distribution statistics.

Attributes

Name Type Description
isolated list

Pages with score < 0.25
lightly_linked list

Pages with score 0.25-1.0
adequately_linked list

Pages with score 1.0-2.0
well_connected list

Pages with score >= 2.0
total_pages int

Total number of pages analyzed
avg_score float

Average connectivity score across all pages

Methods 3

get_distribution
Get count distribution by level.
0 dict[str, int] 
def get_distribution(self) -> dict[str, int]

Get count distribution by level.

Returns

dict[str, int]

get_percentages
Get percentage distribution by level.
0 dict[str, float] 
def get_percentages(self) -> dict[str, float]

Get percentage distribution by level.

Returns

dict[str, float]

to_dict
Convert to dictionary for serialization.
0 dict 
def to_dict(self) -> dict

Convert to dictionary for serialization.

Returns

dict