Imported from ActiveInferenceInstitute/GeneralizedNotationNotation (
src/gnn/website/AGENTS.md). Install upstream withnpx skills add ActiveInferenceInstitute/GeneralizedNotationNotation --skill website. Copyright stays with the author.
Website Module - Agent Scaffolding
Module Overview
Purpose: Static HTML website generation from pipeline artifacts and results
Pipeline Step: Step 20: Website generation (src/gnn/20_website.py)
Category: Documentation / Website Generation
Status: Production Ready
Version: 3.2.0
Last Updated: 2026-09-04
Core Functionality
Primary Responsibilities
- Generate static HTML websites from pipeline results
- Create interactive documentation and reports
- Organize and present pipeline artifacts
- Generate cross-linked documentation
- Create publication-ready websites
Key Capabilities
- Static website generation from pipeline artifacts
- Interactive documentation and reports
- Cross-linked content organization
- Publication-ready HTML output
- Asset management and optimization
API Reference
Public Functions
process_website(target_dir: Path, output_dir: Path, verbose: bool = False, pipeline_output_root: Path | None = None, **kwargs) -> bool
Description: Main website generation function called by orchestrator (src/gnn/20_website.py). Generates a multi-page static HTML website from pipeline artifacts.
Parameters:
target_dir(Path): Directory containing pipeline artifactsoutput_dir(Path): Output directory for website filesverbose(bool): Enable verbose logging (default: False)pipeline_output_root(Path | None): Root of numbered pipeline output dirs; defaults tooutput_dir.parent**kwargs: Additional website generation options (e.g.website_html_filenamefrom the orchestrator, accepted and ignored)
Returns: bool - True if website generation succeeded, False otherwise
Example:
from gnn.website import process_website
from pathlib import Path
success = process_website(
target_dir=Path("output"),
output_dir=Path("output/20_website_output"),
verbose=True,
)generate_html_report(content: str, output_file: Path) -> bool
Description: Generate an HTML report from content and write it to output_file.
Returns: bool - True if writing succeeded, False otherwise
embed_image(image_path: Path, output_file: Path) -> bool
Description: Embed image in HTML output file.
Returns: bool - True if embedding succeeded, False otherwise
embed_markdown_file(md_path: Path, output_file: Path) -> bool
Description: Embed markdown file in HTML output.
Returns: bool - True if embedding succeeded, False otherwise
Additional exports (see __init__.py): WebsiteGenerator, WebsiteRenderer, generate_website, embed_text_file, embed_json_file, embed_html_file, get_module_info, get_supported_file_types, validate_website_config, render_dashboard (re-exported from dashboard.py), collect_website_data, get_pipeline_steps, PIPELINE_STEPS, StepInfo, inspect_website, list_website_pages.
collect_website_data(pipeline_output_root, input_dir, assets_dir, *, output_dir=None, user_data=None) -> dict
Description: Pure aggregation of every artifact the pages render (GNN files, step statuses, analysis JSON, visualization assets, reports, MCP page data). Step statuses come from the durable output/00_pipeline_summary/pipeline_execution_summary.json (per-step status records; a step whose output dir exists but whose recorded status is FAILED/SKIPPED is not advertised complete), falling back to the numbered-output-dir heuristic only when the summary is absent. MCP page data is sourced from the step-21 artifacts — 21_mcp_output/mcp_processing_summary.json for the summary and 21_mcp_output/registered_tools.json for the tool inventory — so the site reflects what step 21 actually recorded and degrades to a truthful empty state when step 21 did not run.
get_pipeline_steps() -> tuple[StepInfo, ...]
Description: Returns the immutable 25-step catalogue derived from gnn.pipeline.step_registry.STEPS (StepInfo(number, name, description) with a script_name display property that matches the real orchestrator scripts) used to render the dashboard and pipeline pages.
inspect_website(directory) -> dict / list_website_pages(directory) -> dict
Description: Pure filesystem queries over a generated site (page inventory, sizes, key-page completeness; per-page size/mtime listing). website.inspection.KEY_PAGES lists the seven canonical pages. These are the shared implementation behind the get_website_status and list_generated_website_pages MCP tools.
Dependencies
The website module is stdlib-only plus one first-party import (gnn.pipeline.step_registry, the canonical step catalogue); no optional pip extra is required to import or run it. The gnn.pipeline package init adds ~50 ms of import time. The Jinja2/Markdown/Bleach templating stack is not used — pages are built with inline CSS/HTML. (The orchestrator src/gnn/20_website.py pulls in gnn.utils.pipeline_orchestration.pipeline_template, a core utility.)
Usage Example
from gnn.website import embed_image
success = embed_image(
image_path="visualizations/network.png", output_file="website/index.html"
)Output Specification
Output Products
generate_website (in generator.py) writes seven pages plus a results manifest:
index.html- Pipeline dashboard with step cardspipeline.html- Full 25-step pipeline status tablegnn_files.html- GNN source file browseranalysis.html- Analysis and complexity metricsvisualization.html- Gallery of generated visualizationsreports.html- JSON/text report viewermcp.html- MCP tools registry across all moduleswebsite_results.json- generation manifest withsuccess,pages_created,pages(written filenames),errors,warnings,generated_at(written byprocess_website)
assets/ is created under the output dir; static/ is copied only if a static/ directory ships beside the module.
Output Directory Structure
output/20_website_output/
├── index.html
├── pipeline.html
├── gnn_files.html
├── analysis.html
├── visualization.html
├── reports.html
├── mcp.html
├── website_results.json
└── assets/
Performance Characteristics
Generation is fast (seconds) for typical pipeline output; no published benchmarks. Measure on demand if needed.
Error Handling
Page Resilience
Each of the seven pages is rendered and written independently (atomic temp-file + rename per page). A failure on one page records Failed to render/write <page> in errors and leaves the remaining pages intact; success in the result dict (and the process_website bool) is True only when no errors occurred. Values coming from pipeline data (GNN sources, analysis JSON, report content, MCP tool fields) are HTML-escaped on every page.
Recovery Strategies
- Template Recovery: Use default templates
- Content Simplification: Simplify content processing
- Asset Skip: Skip problematic assets
- Error Documentation: Generate error reports
Integration Points
Orchestrated By
- Script:
src/gnn/20_website.py(Step 20) - Function:
process_website()
Imports From
gnn.utils.pipeline_orchestration.pipeline_template- Pipeline utilities
Imported By
main.py- Pipeline orchestrationtests/website/test_website_overall.py,test_website_public_api.py,test_website_dashboard.py- Website tests
Data Flow
Pipeline Artifacts → Content Extraction → Template Processing → Asset Embedding → Website Generation
Testing
Test Files
tests/website/test_website_overall.py- Module-level teststests/website/test_website_public_api.py- Public API surface teststests/website/test_website_dashboard.py- Dashboard teststests/website/test_website_generator_units.py- Catalogue, data collection, escaping, page-resilience, manifest teststests/website/test_website_inspection.py-inspect_website/list_website_pagestests
Test Coverage
Measure on demand:
uv run --extra dev python -m pytest tests/website/ \
--cov=src/gnn/website --cov-report=term-missingKey Test Scenarios
- Website generation from pipeline artifacts
- HTML report creation and formatting
- Asset embedding and management
- Error handling and recovery
MCP Integration
Tools Registered
process_website- Generate a website from a target directorybuild_website_from_pipeline_output- Discover numbered pipeline artifacts and build the siteget_website_status- Inspect completeness of an existing generated sitelist_generated_website_pages- List generated HTML pages and metadataget_website_module_info- Return website features and the live MCP inventory
The module-info inventory and register_tools() use these same five names.
MCP File Location
src/gnn/website/mcp.py- MCP tool registrations
Troubleshooting
Common Issues
Issue 1: Website generation fails
Symptom: HTML files not generated or incomplete
Cause: Missing pipeline artifacts or template issues
Solution:
- Verify previous pipeline steps completed successfully
- Check that required artifacts exist in output directories
- Use
--verboseflag for detailed generation logs - Review website template structure
Issue 2: Embedded content missing
Symptom: Website generated but images or markdown not embedded
Cause: File paths incorrect or files missing
Solution:
- Verify all referenced files exist
- Check file paths are relative to website output directory
- Ensure images and markdown files are accessible
- Review embedding function logs
Version History
Module __version__ is 1.7.0 (__init__.py); the pipeline/repo release is 3.2.0. No formal changelog is maintained in this file.
References
Related Documentation
External Resources
Last Updated: 2026-09-04
Maintainer: GNN Pipeline Team
Status: Production Ready
Version: 3.2.0
Architecture Compliance: Thin Orchestrator Pattern (delegates to website.processor.process_website → renderer.process_website → generator.generate_website)