0
# Page Enhancement and Context
1

2
Functions that enhance page rendering with metadata, asset management, and template processing. These functions are connected to Sphinx events to modify page context and improve performance.
3

4
## Capabilities
5

6
### Page Metadata Addition
7

8
Adds contextual metadata to pages during rendering, including titles, descriptions, and translation support.
9

10
```python { .api }
11
def add_metadata_to_page(app, pagename, templatename, context, doctree):
12
    """
13
    Add metadata to page context for enhanced rendering.
14
    
15
    This function:
16
    - Adds root document title to navbar context
17
    - Sets page title from document structure
18
    - Generates page description from content (160 chars)
19
    - Adds author information if configured
20
    - Sets up translation context
21
    - Configures search bar text
22
    
23
    Parameters:
24
    - app: Sphinx application instance
25
    - pagename: Name of the page being processed
26
    - templatename: Template being used for rendering
27
    - context: Template context dictionary (modified in-place)
28
    - doctree: Document tree for the page
29
    """
30
```
31

32
### Asset Hash Management
33

34
Manages asset hashing for cache busting, ensuring updated assets are properly loaded.
35

36
```python { .api }
37
def hash_html_assets(app, pagename, templatename, context, doctree):
38
    """
39
    Add digest hashes to CSS and JS assets for cache busting.
40
    
41
    Processes theme-specific assets and adds hash-based query parameters
42
    to ensure browsers reload updated files.
43
    
44
    Parameters:
45
    - app: Sphinx application instance
46
    - pagename: Name of the page being processed
47
    - templatename: Template being used
48
    - context: Template context (modified to include hashed assets)
49
    - doctree: Document tree for the page
50
    """
51

52
def hash_assets_for_files(assets: list, theme_static: Path, context, app):
53
    """
54
    Generate hashes for specific asset files and update context.
55
    
56
    Parameters:
57
    - assets: List of asset paths relative to theme static folder
58
    - theme_static: Path to theme's static asset directory
59
    - context: Template context containing css_files and script_files
60
    - app: Sphinx application for adding assets with digests
61
    """
62
```
63

64
### Template Processing
65

66
Updates template configurations and processes template sections for flexible content layout.
67

68
```python { .api }
69
def update_templates(app, pagename, templatename, context, doctree):
70
    """
71
    Update template names and process template sections.
72
    
73
    Processes template sections like 'theme_footer_content_items',
74
    handling comma-separated strings and adding .html extensions
75
    to template names without suffixes.
76
    
77
    Parameters:
78
    - app: Sphinx application instance
79
    - pagename: Name of the page being processed
80
    - templatename: Template being used
81
    - context: Template context (modified for template processing)
82
    - doctree: Document tree for the page
83
    """
84
```
85

86
### Hash Generation
87

88
```python { .api }
89
def _gen_hash(path: str) -> str:
90
    """
91
    Generate SHA1 digest hash for a file path.
92
    
93
    Uses LRU cache for performance optimization.
94
    
95
    Parameters:
96
    - path: File path to hash
97
    
98
    Returns:
99
    SHA1 hexdigest of file contents
100
    """
101
```
102

103
## Usage Examples
104

105
### Manual Metadata Addition
106

107
```python
108
from sphinx_book_theme import add_metadata_to_page
109

110
# In a Sphinx event handler
111
def my_page_handler(app, pagename, templatename, context, doctree):
112
    # Add theme metadata
113
    add_metadata_to_page(app, pagename, templatename, context, doctree)
114
    
115
    # Access added metadata
116
    print(f"Page title: {context.get('pagetitle')}")
117
    print(f"Page description: {context.get('page_description')}")
118
    print(f"Root title: {context.get('root_title')}")
119
```
120

121
### Asset Hashing
122

123
```python
124
from sphinx_book_theme import hash_html_assets, get_html_theme_path
125

126
# Hash theme assets for a page
127
def process_assets(app, pagename, templatename, context, doctree):
128
    hash_html_assets(app, pagename, templatename, context, doctree)
129
    
130
    # Assets now have digest hashes:
131
    # styles/sphinx-book-theme.css?digest=abc123
132
    # scripts/sphinx-book-theme.js?digest=def456
133
```
134

135
### Custom Asset Hashing
136

137
```python
138
from sphinx_book_theme import hash_assets_for_files, get_html_theme_path
139

140
# Hash custom assets
141
custom_assets = ["styles/custom.css", "scripts/custom.js"]
142
theme_static = get_html_theme_path() / "static"
143

144
hash_assets_for_files(custom_assets, theme_static, context, app)
145
```