Module

debug.content_migrator

Content migration assistant for safe content restructuring.

Provides tools to safely move, split, merge, and reorganize content files while maintaining link integrity and generating necessary redirects.

Key Features:

  • Preview moves before executing
  • Automatic redirect generation
  • Link update across the site
  • Split large pages into smaller ones
  • Merge related pages

Related Modules:

  • bengal.health.validators.links: Link validation
  • bengal.analysis.knowledge_graph: Content relationships
  • bengal.debug.base: Debug tool infrastructure

See Also:

  • bengal/postprocess/redirects.py: Redirect handling
View source
6 Classes

Classes

MoveOperation dataclass
A planned content move operation.
1

A planned content move operation.

Attributes

Name Type Description
source str

Source path (relative to content dir)
destination str

Destination path (relative to content dir)
reason str

Why this move is happening
Internal Methods 1
__str__
0 str 
def __str__(self) -> str
Returns

str

LinkUpdate dataclass
A link that needs to be updated.
0

A link that needs to be updated.

Attributes

Name Type Description
file_path str

File containing the link
old_link str

Current link target
new_link str

New link target
line int

Line number in file
context str

Surrounding text context
Redirect dataclass
A redirect rule for moved content.
3

A redirect rule for moved content.

Attributes

Name Type Description
from_path str

Old URL path
to_path str

New URL path
status_code int

HTTP status code (301 permanent, 302 temporary)

Methods 3

to_nginx
Generate nginx redirect rule.
0 str 
def to_nginx(self) -> str

Generate nginx redirect rule.

Returns

str

to_netlify
Generate Netlify _redirects format.
0 str 
def to_netlify(self) -> str

Generate Netlify _redirects format.

Returns

str

to_apache
Generate Apache .htaccess rule.
0 str 
def to_apache(self) -> str

Generate Apache .htaccess rule.

Returns

str

MovePreview dataclass
Preview of what a move operation would do.
1

Preview of what a move operation would do.

Attributes

Name Type Description
operation MoveOperation

The move operation being previewed
affected_links list[LinkUpdate]

Links that would need updating
redirects_needed list[Redirect]

Redirects that would be generated
warnings list[str]

Any warnings about the move
can_proceed bool

Whether the move can safely proceed

Methods 1

format_summary
Format preview as summary.
0 str 
def format_summary(self) -> str

Format preview as summary.

Returns

str

PageDraft dataclass
A draft of a new or modified page. Used for split/merge operations to preview changes before applying.
1

A draft of a new or modified page.

Used for split/merge operations to preview changes before applying.

Attributes

Name Type Description
path str

Target path for the page
title str

Page title
content str

Page content (markdown)
frontmatter dict[str, Any]

Page frontmatter
source_pages list[str]

Original pages this was derived from

Methods 1

format_preview
Format as preview.
1 str 
def format_preview(self, max_lines: int = 20) -> str

Format as preview.

Parameters 1
max_lines int
Returns

str

ContentMigrator
Tool for safely restructuring content. Helps move, split, merge, and reorganize content while main…
14

Tool for safely restructuring content.

Helps move, split, merge, and reorganize content while maintaining link integrity and generating necessary redirects.

Creation:

migrator = ContentMigrator(site=site)
Inherits from DebugTool

Methods 6

analyze
Analyze content structure for migration opportunities.
0 DebugReport 
def analyze(self) -> DebugReport

Analyze content structure for migration opportunities.

Returns

DebugReport —

DebugReport with structure analysis

preview_move
Preview what would happen if a file is moved.
2 MovePreview 
def preview_move(self, source: str, destination: str) -> MovePreview

Preview what would happen if a file is moved.

Parameters 2
source str

Source path (relative to content dir)
destination str

Destination path
Returns

MovePreview —

MovePreview with affected links and redirects

execute_move
Execute a previewed move operation.
4 list[str] 
def execute_move(self, preview: MovePreview, update_links: bool = True, create_redirects: bool = True, dry_run: bool = False) -> list[str]

Execute a previewed move operation.

Parameters 4
preview MovePreview

Move preview from preview_move()
update_links bool

Whether to update links in other files
create_redirects bool

Whether to generate redirect rules
dry_run bool

If True, only report what would be done
Returns

list[str] —

List of actions taken (or that would be taken)

split_page
Split a large page into multiple smaller pages.
3 list[PageDraft] 
def split_page(self, page_path: str, sections: list[str], output_dir: str | None = None) -> list[PageDraft]

Split a large page into multiple smaller pages.

Parameters 3
page_path str

Path to the page to split
sections list[str]

List of heading names to split at
output_dir str | None

Optional output directory for new pages
Returns

list[PageDraft] —

List of PageDraft objects for the new pages

merge_pages
Merge multiple pages into one.
3 PageDraft 
def merge_pages(self, page_paths: list[str], output_path: str, title: str | None = None) -> PageDraft

Merge multiple pages into one.

Parameters 3
page_paths list[str]

Paths to pages to merge
output_path str

Output path for merged page
title str | None

Optional title for merged page
Returns

PageDraft —

PageDraft for the merged page

generate_redirects
Generate redirect rules for moved content.
2 str 
def generate_redirects(self, moves: list[MoveOperation], output_format: str = 'netlify') -> str

Generate redirect rules for moved content.

Parameters 2
moves list[MoveOperation]

List of move operations
output_format str

Output format (netlify, nginx, apache)
Returns

str —

Redirect rules in requested format

Internal Methods 8
_find_structure_issues
Find potential structure issues in content.
0 list[DebugFinding] 
def _find_structure_issues(self) -> list[DebugFinding]

Find potential structure issues in content.

Returns

list[DebugFinding]

_is_in_navigation
Check if page is in site navigation.
1 bool 
def _is_in_navigation(self, page: Any) -> bool

Check if page is in site navigation.

Parameters 1
page Any
Returns

bool

_path_to_url
Convert file path to URL.
1 str 
def _path_to_url(self, path: str) -> str

Convert file path to URL.

Parameters 1
path str
Returns

str

_links_match
Check if a link matches a target URL.
2 bool 
def _links_match(self, link: str, target_url: str) -> bool

Check if a link matches a target URL.

Parameters 2
link str
target_url str
Returns

bool

_update_link
Update a link to point to new location.
3 str 
def _update_link(self, old_link: str, old_url: str, new_url: str) -> str

Update a link to point to new location.

Parameters 3
old_link str
old_url str
new_url str
Returns

str

_update_file_link
Update a link in a file.
1 None 
def _update_file_link(self, link_update: LinkUpdate) -> None

Update a link in a file.

Parameters 1
link_update LinkUpdate
_slugify
Convert text to URL slug.
1 str 
def _slugify(self, text: str) -> str

Convert text to URL slug.

Parameters 1
text str
Returns

str

_generate_recommendations
Generate recommendations based on analysis.
1 list[str] 
def _generate_recommendations(self, report: DebugReport) -> list[str]

Generate recommendations based on analysis.

Parameters 1
report DebugReport
Returns

list[str]