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 automatically generating redirects. All operations can be previewed before execution.

Key Features:

  • MoveOperation: Planned content move
  • MovePreview: Preview showing affected links and redirects
  • LinkUpdate: Link that needs updating after a move
  • Redirect: Redirect rule in multiple formats
  • PageDraft: Draft for split/merge operations
  • ContentMigrator: Debug tool combining all capabilities

Operations:

  • preview_move(): Preview what a move would do
  • execute_move(): Execute with link updates and redirects
  • split_page(): Split large page into sections
  • merge_pages(): Merge multiple pages into one
  • generate_redirects(): Create redirect rules

Example:

>>> from bengal.debug import ContentMigrator
>>> migrator = ContentMigrator(site=site)
>>> preview = migrator.preview_move("docs/old.md", "guides/new.md")
>>> print(preview.format_summary())

📦 Move Preview: docs/old.md → guides/new.md

🔗 3 links would be updated: • content/index.md:15 • content/about.md:42

↪️ 1 redirect(s) would be created: • /docs/old → /guides/new

✅ Safe to proceed

>>> if preview.can_proceed:
...     actions = migrator.execute_move(preview)

Related Modules:

  • bengal.health.validators.links: Link validation
  • bengal.postprocess.redirects: Redirect handling
  • bengal.debug.base: Debug tool infrastructure

See Also:

  • bengal/cli/commands/debug.py: CLI integration
6Classes

Classes

MoveOperation 4 ▼
A planned content move operation. Describes the source and destination of a content file move. Use…

A planned content move operation.

Describes the source and destination of a content file move. Used as input to preview_move() and stored in MovePreview.

Attributes

Name Type Description
source str

Source path (relative to content directory).
destination str

Destination path (relative to content directory).
reason str

Optional explanation of why this move is needed.

Methods

Internal Methods 1 ▼
__str__ 0 str ▼
Format as source → destination.
def __str__(self) -> str
Returns
str
LinkUpdate 5 ▼
A link that needs to be updated after a content move. Identifies where a link exists and what it s…

A link that needs to be updated after a content move.

Identifies where a link exists and what it should change to. Includes context for review before making changes.

Attributes

Name Type Description
file_path str

Path to the file containing the link.
old_link str

Current link target (to be replaced).
new_link str

New link target (replacement).
line int

Line number where the link appears.
context str

Surrounding text (markdown link syntax).
Redirect 6 ▼
A redirect rule for moved content. Supports generating redirect rules in multiple formats for diff…

A redirect rule for moved content.

Supports generating redirect rules in multiple formats for different hosting platforms.

Attributes

Name Type Description
from_path str

Old URL path (source of redirect).
to_path str

New URL path (destination of redirect).
status_code int

HTTP status code (301 permanent, 302 temporary).

Methods

to_nginx 0 str ▼
Generate nginx redirect rule for server config.
def to_nginx(self) -> str
Returns
str
to_netlify 0 str ▼
Generate Netlify _redirects file format.
def to_netlify(self) -> str
Returns
str
to_apache 0 str ▼
Generate Apache .htaccess redirect directive.
def to_apache(self) -> str
Returns
str
MovePreview 6 ▼
Preview of what a move operation would do. Generated by preview_move() to show all effects before …

Preview of what a move operation would do.

Generated by preview_move() to show all effects before execution. Allows review of link updates, redirects, and any warnings before committing to the move.

Attributes

Name Type Description
operation MoveOperation

The move operation being previewed.
affected_links list[LinkUpdate]

Links that would need updating across the site.
redirects_needed list[Redirect]

Redirect rules that would be generated.
warnings list[str]

Any warnings about potential issues.
can_proceed bool

Whether the move can safely proceed.

Methods

format_summary 0 str ▼
Format preview as human-readable summary.
def format_summary(self) -> str
Returns
str Multi-line summary with affected links, redirects, and status.
PageDraft 6 ▼
A draft of a new or modified page. Used by split_page() and merge_pages() to represent the output …

A draft of a new or modified page.

Used by split_page() and merge_pages() to represent the output pages before they're written to disk, allowing for preview and modification before committing changes.

Attributes

Name Type Description
path str

Target path for the new page (relative to content dir).
title str

Page title extracted from heading or frontmatter.
content str

Full Markdown content body.
frontmatter dict[str, Any]

Merged/generated frontmatter dictionary.
source_pages list[str]

Original pages this draft was derived from.

Methods

format_preview 1 str ▼
Format as preview.
def format_preview(self, max_lines: int = 20) -> str
Parameters
Name Type Description
max_lines — Default:20
Returns
str
ContentMigrator 18 ▼
Tool for safely restructuring content with link integrity. Provides safe content reorganization op…

Tool for safely restructuring content with link integrity.

Provides safe content reorganization operations that maintain site integrity by automatically updating internal links and generating redirect rules for external references.

Capabilities:

  • Move/Rename: Relocate content files with automatic link updates.
  • Split Pages: Break large pages into multiple smaller pages.
  • Merge Pages: Combine multiple pages into a single page.
  • Redirect Generation: Create redirect rules for various platforms.
  • Structure Analysis: Find orphan pages, large pages, and issues.

The tool operates in a preview-first mode: all operations can be previewed before execution to review the impact.

Attributes

Name Type Description
name —

Tool identifier ("migrate").
description —

Brief tool description.
site —

Site instance for content access.
cache —

Optional build cache for dependency info.
root_path —

Project root directory.

Methods

analyze 0 DebugReport ▼
Analyze content structure for migration opportunities.
def analyze(self) -> DebugReport
Returns
DebugReport DebugReport with structure analysis
preview_move 2 MovePreview ▼
Preview what would happen if a file is moved.
def preview_move(self, source: str, destination: str) -> MovePreview
Parameters
Name Type Description
source —

Source path (relative to content dir)
destination —

Destination path
Returns
MovePreview MovePreview with affected links and redirects
execute_move 4 list[str] ▼
Execute a previewed move operation.
def execute_move(self, preview: MovePreview, update_links: bool = True, create_redirects: bool = True, dry_run: bool = False) -> list[str]
Parameters
Name Type Description
preview —

Move preview from preview_move()
update_links —

Whether to update links in other files

Default:True
create_redirects —

Whether to generate redirect rules

Default:True
dry_run —

If True, only report what would be done

Default:False
Returns
list[str] List of actions taken (or that would be taken)
split_page 3 list[PageDraft] ▼
Split a large page into multiple smaller pages.
def split_page(self, page_path: str, sections: list[str], output_dir: str | None = None) -> list[PageDraft]
Parameters
Name Type Description
page_path —

Path to the page to split
sections —

List of heading names to split at
output_dir —

Optional output directory for new pages

Default:None
Returns
list[PageDraft] List of PageDraft objects for the new pages
merge_pages 3 PageDraft ▼
Merge multiple pages into one.
def merge_pages(self, page_paths: list[str], output_path: str, title: str | None = None) -> PageDraft
Parameters
Name Type Description
page_paths —

Paths to pages to merge
output_path —

Output path for merged page
title —

Optional title for merged page

Default:None
Returns
PageDraft PageDraft for the merged page
generate_redirects 2 str ▼
Generate redirect rules for moved content.
def generate_redirects(self, moves: list[MoveOperation], output_format: str = 'netlify') -> str
Parameters
Name Type Description
moves —

List of move operations
output_format —

Output format (netlify, nginx, apache)

Default:'netlify'
Returns
str Redirect rules in requested format
Internal Methods 7 ▼
_find_structure_issues 0 list[DebugFinding] ▼
Find potential structure issues in content.
def _find_structure_issues(self) -> list[DebugFinding]
Returns
list[DebugFinding]
_is_in_navigation 1 bool ▼
Check if page is in site navigation.
def _is_in_navigation(self, page: Any) -> bool
Parameters
Name Type Description
page —
Returns
bool
_path_to_url 1 str ▼
Convert file path to URL.
def _path_to_url(self, path: str) -> str
Parameters
Name Type Description
path —
Returns
str
_links_match 2 bool ▼
Check if a link matches a target URL.
def _links_match(self, link: str, target_url: str) -> bool
Parameters
Name Type Description
link —
target_url —
Returns
bool
_update_link 2 str ▼
Update a link to point to new location.
def _update_link(self, old_link: str, new_url: str) -> str
Parameters
Name Type Description
old_link —
new_url —
Returns
str
_update_file_link 1 ▼
Update a link in a file.
def _update_file_link(self, link_update: LinkUpdate) -> None
Parameters
Name Type Description
link_update —
_generate_recommendations 1 list[str] ▼
Generate recommendations based on analysis.
def _generate_recommendations(self, report: DebugReport) -> list[str]
Parameters
Name Type Description
report —
Returns
list[str]