tessl/pypi-sphinxawesome-theme

An awesome theme for the Sphinx documentation generator with enhanced features, custom code highlighting, and modern responsive design

Overview

Eval results

Files

Template Functions

Name: tessl/pypi-sphinxawesome-theme
Author: tessl

Custom Jinja2 functions and template modifications that enhance template rendering with canonical URL fixes, directory builder support, and improved template context management for better SEO and navigation.

Capabilities

Jinja2 Template Setup

Main function that registers custom template functions and fixes builder-specific issues.

def setup_jinja(app: Sphinx, pagename: str, templatename: str, 
               context: dict[str, Any], doctree: Node) -> None:
    """
    Register a function as a Jinja2 filter and fix canonical URLs.
    
    Handles the html-page-context event to:
    - Fix canonical URL generation for dirhtml builder
    - Register custom template functions
    - Enhance template context with theme-specific data
    
    Parameters:
    - app (Sphinx): The Sphinx application instance
    - pagename (str): Current page name being rendered
    - templatename (str): Name of the template being used
    - context (dict[str, Any]): Template context dictionary
    - doctree (Node): Document tree node for the page
    """

Canonical URL Generation

Internal function that creates proper canonical URLs for directory-based builders.

def _make_canonical(app: Sphinx, pagename: str) -> str:
    """
    Turn a filepath into the correct canonical link.
    
    Fixes canonical URL generation for the dirhtml builder, which
    upstream Sphinx builds incorrectly. Ensures proper SEO and
    URL structure for directory-based site organization.
    
    Parameters:
    - app (Sphinx): The Sphinx application instance
    - pagename (str): Page name to convert to canonical URL
    
    Returns:
    str: Properly formatted canonical URL with trailing slash
    """

URL Generation Issues

Directory Builder Problem

The Sphinx dirhtml builder generates URLs like /page/ instead of /page.html, but the canonical URL generation doesn't account for this properly. The template functions fix this issue.

Before Fix (Incorrect)

# Sphinx generates incorrect canonical URLs for dirhtml builder
canonical = "https://example.com/docs/installation.html"  # Wrong for dirhtml

After Fix (Correct)

# Template function generates correct canonical URLs
canonical = "https://example.com/docs/installation/"  # Correct for dirhtml

Template Context Enhancements

The template functions enhance the Jinja2 context with corrected values:

Page URL Override

# For dirhtml builder with html_baseurl configured
if app.builder.name == "dirhtml" and app.config.html_baseurl:
    context["pageurl"] = _make_canonical(app, pagename)

This ensures templates have access to properly formatted page URLs for:

Canonical link tags
Social media meta tags
Sitemap generation
Cross-page navigation

Usage in Templates

Canonical Link Generation

<!-- In base template -->
{% if pageurl %}
<link rel="canonical" href="{{ pageurl }}">
{% endif %}

Social Media Meta Tags

<!-- Open Graph tags -->
<meta property="og:url" content="{{ pageurl }}">
<meta property="og:type" content="website">

<!-- Twitter Card tags -->
<meta name="twitter:url" content="{{ pageurl }}">

Structured Data

<!-- JSON-LD structured data -->
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "WebPage",
  "url": "{{ pageurl }}",
  "name": "{{ title }}"
}
</script>

Builder Compatibility

HTML Builder

Standard HTML builder generates files like page.html:

No special URL handling needed
Standard Sphinx canonical generation works correctly

Directory HTML Builder

Directory HTML builder generates directory structure:

Files saved as page/index.html
URLs accessed as /page/
Requires custom canonical URL generation

Configuration Example

# In conf.py
html_baseurl = "https://example.com/docs/"

# For dirhtml builder
extensions = [
    # ... other extensions
]

# The template functions automatically detect dirhtml builder
# and fix canonical URLs when html_baseurl is configured

SEO Benefits

Proper Canonical URLs

Correct canonical URLs help search engines:

Understand the preferred URL structure
Avoid duplicate content penalties
Index pages with consistent URL patterns

URL Structure Consistency

Consistent URL patterns improve:

User experience with predictable URLs
Link sharing and bookmarking
Site navigation and hierarchy understanding

Event Integration

The template functions integrate with Sphinx's event system:

# In theme setup
app.connect("html-page-context", setup_jinja)

This ensures the functions run for every page during the build process, providing consistent URL handling across the entire site.

Error Handling

The template functions include robust error handling:

# Safe canonical URL generation
if app.builder.name == "dirhtml" and app.config.html_baseurl:
    # Only modify context if conditions are met
    context["pageurl"] = _make_canonical(app, pagename)

This prevents issues when:

html_baseurl is not configured
Different builders are used
Template context is missing expected values

Install with Tessl CLI

npx tessl i tessl/pypi-sphinxawesome-theme

docs

code-highlighting.md

deprecated-options.md

html-postprocessing.md

index.md

json-serialization.md

logo-management.md

template-functions.md

theme-builder.md

theme-configuration.md

toc-manipulation.md

tile.json

tessl/pypi-sphinxawesome-theme