Alabaster

1.0.0 · active · verified Sun Mar 29

Alabaster is a visually clean, responsive, and configurable theme for the Sphinx documentation system. It is currently at version 1.0.0 and is actively maintained, with releases typically tied to Sphinx compatibility and feature enhancements. It started as a third-party theme but is now an install-time dependency and the default theme for Sphinx since version 1.3.

Warnings

breaking Alabaster 1.0.0 dropped support for Python 3.9 and earlier, and Sphinx 6.1 and earlier.
Fix: Ensure your project uses Python 3.10+ and Sphinx 6.2+ before upgrading to Alabaster 1.0.0.
breaking The layout changed significantly between Alabaster 0.7.16 and 1.0.0 due to the removal of `@import url("basic.css");` from `alabaster.css`. This can cause tables, TOCs, and figures to display incorrectly, potentially extending beyond screen width.
Fix: If you use a custom stylesheet, you might need to add `@import '../basic.css';` to your `custom.css` file to re-include the basic Sphinx styling. It is also recommended to review your theme options and custom CSS for compatibility after the upgrade.
deprecated The `canonical_url` theme option was deprecated in Alabaster 0.7.15 in favor of Sphinx's `html_baseurl` configuration.
Fix: Use `html_baseurl` directly in your `conf.py` instead of setting `canonical_url` within `html_theme_options`.
gotcha Some older theme options (implemented prior to 0.7.8) that modify minor styles might be more appropriately handled via custom CSS stylesheet overrides. The theme maintainers now generally prefer custom stylesheets for small CSS modifications.
Fix: For minor style adjustments not directly covered by `html_theme_options`, consider creating a custom CSS file (e.g., `_static/custom.css`) and referencing it in `conf.py` using `html_static_path = ['_static']` and `html_css_files = ['css/custom.css']`.

Install

pip install alabaster Install Alabaster

Imports

alabaster.get_path
```
import alabaster
html_theme_path = [alabaster.get_path()]
extensions = ['alabaster']
html_theme = 'alabaster'
```
`alabaster.get_path()` dynamically returns the install location, ensuring Sphinx can find the theme regardless of installation method. Manually copying theme files or directly modifying Jinja templates for customization is generally not the recommended approach.

Quickstart

This quickstart guides you through configuring an existing Sphinx project to use the Alabaster theme. It demonstrates how to set the theme path using `alabaster.get_path()`, enable the `alabaster` extension, and apply common `html_theme_options` and `html_sidebars` configurations within your Sphinx `conf.py` file.

# 1. First, set up a basic Sphinx project (if you haven't already):
#    sphinx-quickstart
#    (accept defaults or configure as needed)

# 2. In your conf.py (located in your Sphinx project's source directory):
import os
import sys
import alabaster

# Project information
project = 'My Awesome Project'
copyright = '2026, Your Name'
author = 'Your Name'
release = '0.1.0'

# -- General configuration ---------------------------------------------------
extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon',
    'sphinx.ext.viewcode',
    'alabaster' # Important: include 'alabaster' in extensions
]

templates_path = ['_templates']
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']

# -- Options for HTML output -------------------------------------------------
html_theme = 'alabaster'
html_theme_path = [alabaster.get_path()] # This dynamically sets the theme path

# Optional: Alabaster theme options (customize appearance)
html_theme_options = {
    'logo': 'logo.png', # Requires a logo.png in _static/ if used
    'github_user': 'your-github-user',
    'github_repo': 'your-github-repo',
    'description': 'A brief description of your project.',
    'fixed_sidebar': True,
    'show_relbars': True,
    'show_related': True,
    'sidebar_width': '250px'
    # Many other options available, see Alabaster documentation
}

# Optional: Custom sidebar templates, maps document names to template names.
# Alabaster provides about.html, navigation.html, searchbox.html, donate.html
# searchbox.html comes with Sphinx itself.
html_sidebars = {
    '**': [
        'about.html',
        'navigation.html',
        'searchbox.html',
        'donate.html'
    ]
}

# If you have custom CSS, add it here (e.g., in _static/custom.css)
# html_static_path = ['_static']
# html_css_files = [
#     'css/custom.css',
# ]

# To build your docs:
# cd <your_sphinx_project_root>
# make html

view raw JSON →