Output¶

outputs ¶

Output path mapping and link rewriting.

Transforms web URLs to local file paths and rewrites absolute links to relative paths for offline browsing. Provides OutputManager for all path operations and markdown link rewriting.

Classes¶

OutputManager ¶

OutputManager(config: SusConfig, dry_run: bool = False)

Manages output paths and link rewriting.

Handles: - URL to file path mapping - Directory structure creation - Relative link calculation - Link rewriting in markdown

Examples:

>>> config = SusConfig(...)
>>> manager = OutputManager(config)
>>> doc_path = manager.get_doc_path("https://example.com/doc/guide/")
>>> asset_path = manager.get_asset_path("https://example.com/img/logo.png")
>>> markdown = manager.rewrite_links(markdown, source_url)

Initialize output manager.

Parameters:

Name	Type	Description	Default
`config`	`SusConfig`	Validated SusConfig instance	required
`dry_run`	`bool`	If True, don't create directories or write files	`False`

Raises:

Type	Description
`ValueError`	If config is invalid or paths are malformed

Functions¶

get_doc_path ¶

get_doc_path(url: str) -> Path

Convert URL to markdown file path.

Parameters:

Name	Type	Description	Default
`url`	`str`	Source URL to convert	required

Returns:

Type	Description
`Path`	Absolute path to markdown file

Logic: 1. Parse URL and extract path component 2. Strip configured prefix (config.output.path_mapping.strip_prefix) 3. Handle directory URLs (ending in /) → use index_file 4. Convert path segments to file path 5. Ensure .md extension 6. Create parent directories (unless dry run)

Examples:

URL: https://example.com/doc/guide/install/ strip_prefix: /doc → docs/guide/install/index.md

URL: https://example.com/doc/overview strip_prefix: /doc → docs/overview.md

Raises:

Type	Description
`ValueError`	If URL cannot be parsed or path is invalid

get_asset_path ¶

get_asset_path(asset_url: str) -> Path

Convert asset URL to file path.

Parameters:

Name	Type	Description	Default
`asset_url`	`str`	Asset URL (image, CSS, JS, etc.)	required

Returns:

Type	Description
`Path`	Absolute path to asset file

Logic: 1. Parse URL and extract path 2. Preserve original directory structure under assets_dir 3. Example: https://example.com/img/logo.png → assets/img/logo.png

Examples:

>>> manager.get_asset_path("https://example.com/img/logo.png")
Path("/path/to/output/site/assets/img/logo.png")

>>> manager.get_asset_path("https://example.com/css/style.css")
Path("/path/to/output/site/assets/css/style.css")

Raises:

Type	Description
`ValueError`	If URL cannot be parsed or path is invalid

rewrite_links ¶

rewrite_links(markdown: str, source_url: str) -> str

Rewrite links in markdown to relative paths.

Parameters:

Name	Type	Description	Default
`markdown`	`str`	Markdown content with absolute URLs	required
`source_url`	`str`	URL of the source page (for calculating relative paths)	required

Returns:

Type	Description
`str`	Markdown with rewritten links

Rewrites two types of links: 1. Internal doc links: text → text 2. Asset links: alt → alt

Logic: 1. Calculate source file path from URL 2. Find all markdown links: text and alt 3. For each link: - If internal doc link (same domain, under allowed paths): * Calculate target doc path * Calculate relative path from source to target - If asset link (image, css, js): * Calculate asset path * Calculate relative path from source to asset

Examples:

>>> markdown = "[Guide](https://example.com/doc/guide/)"
>>> result = manager.rewrite_links(markdown, "https://example.com/doc/")
>>> print(result)
"[Guide](guide/index.md)"

Raises:

Type	Description
`ValueError`	If source_url is invalid