Customization¶
Alabaster’s behavior & style can be customized in multiple ways:
Various template-level or nontrivial-style settings can be configured via your
conf.py
inhtml_theme_options
; see Theme options.As of Alabaster 0.7.8, you can provide your own CSS stylesheet overrides via a custom stylesheet. This is suitable for changes that only need minor CSS modifications.
Note
Some theme options implemented prior to 0.7.8 would have been more suitable as local custom stylesheet overrides. Therefore:
We no longer accept feature requests which are more appropriately solved by using this functionality instead.
In future backwards-incompatible versions we may deprecate some of those options; as such we highly recommend leveraging the custom stylesheet whenever possible, even if an option is present below.
When in doubt, simply check the built-in stylesheet’s template to see whether the option you’re looking at is a basic variable insertion or something more complicated.)
Custom stylesheet¶
If you need to modify Alabaster’s default CSS styles in a way not covered by the theme options from the next section, you may provide a custom CSS stylesheet as follows:
Create a file named
custom.css
anywhere you prefer (typically_static/
, but this is solely convention) containing your desired overrides to the CSS found in Alabaster’sstatic/alabaster_css_t
.Set the core Sphinx option html_static_path to either that file’s path, or the directory it lives within.
Theme options¶
Alabaster’s primary configuration route is the html_theme_options
variable,
set in conf.py
alongside the rest, e.g.:
html_theme_options = {
'logo': 'logo.png',
'github_user': 'bitprophet',
'github_repo': 'alabaster',
}
The following subsections detail available such options, including notes about behavior & default values.
Variables and feature toggles¶
logo
: Relative path (from$PROJECT/_static/
) to a logo image, which will appear in the upper left corner above the name of the project.If
logo
is not set, yourproject
name setting (from the top level Sphinx config) will be used in a text header instead. This preserves a link back to your homepage from inner doc pages.
logo_name
: Set totrue
to insert your site’sproject
name under the logo image as text. Useful if your logo doesn’t include the project name itself. Defaults tofalse
.logo_text_align
: Which CSStext-align
value to use for logo text (if there is any.)body_text_align
: Which CSStext-align
value to use for body text (if there is any.)description
: Text blurb about your project, to appear under the logo.description_font_style
: Which CSSfont-style
to use for description text. Defaults tonormal
.github_user
,github_repo
: Used bygithub_button
andgithub_banner
(see below); does nothing if both of those are set tofalse
.github_button
:true
orfalse
(default:true
) - whether to link to your Github.If
true
, requires that you setgithub_user
andgithub_repo
.See also these other related options, which behave as described in Github Buttons’ documentation:
github_type
: Defaults towatch
.github_count
: Defaults totrue
.
github_banner
:true
orfalse
(default:false
) - whether to apply a ‘Fork me on Github’ banner in the top right corner of the page.If
true
, requires that you setgithub_user
andgithub_repo
.May also submit a string file path (as with
logo
, relative to$PROJECT/_static/
) to be used as the banner image instead of the default.
travis_button
:true
,false
or a Github-style"account/repo"
string - used to display a Travis-CI build status button in the sidebar. Iftrue
, uses yourgithub_(user|repo)
settings; defaults tofalse.
codecov_button
:true
,false
or a Github-style"account/repo"
string - used to display a Codecov build status button in the sidebar. Iftrue
, uses yourgithub_(user|repo)
settings; defaults tofalse.
gratipay_user
: Set to your Gratipay username if you want a Gratipay ‘Donate’ section in your sidebar.This used to be
gittip_user
before that service changed its name to Gratipay; we’ve left the old setting in place as an alias for backwards compatibility reasons. It may be removed in the future.If both options are given,
gratipay_user
wins.
analytics_id
: Set to your Google Analytics ID (e.g.UA-#######-##
) to enable tracking.touch_icon
: Path to an image (as withlogo
, relative to$PROJECT/_static/
) to be used for an iOS application icon, for when pages are saved to an iOS device’s home screen via Safari.canonical_url
: If set, is used as the base URL (set before the relative path/pagename) for a<link rel="canonical">
canonical URL header tag.Note
This value must end with a trailing slash.
extra_nav_links
: Dictionary mapping link names to link targets; these will be added in a UL below the main sidebar navigation (provided you’ve enablednavigation.html
via thehtml_sidebars
option; see Installation.) Useful for static links outside your Sphinx doctree.sidebar_includehidden
: Boolean determining whether the TOC sidebar should include hidden Sphinx toctree elements. Defaults totrue
so you can use:hidden:
in your index page’s root toctree & avoid having 2x copies of your navigation on your landing page.sidebar_collapse
: Boolean determining whether all TOC entries thatare not ancestors of the current page are collapsed. You can read more about this in the Sphinx toctree docs.
show_powered_by
: Boolean controlling display of thePowered by Sphinx N.N.N. & Alabaster M.M.M
section of the footer. Whentrue
, is displayed next to the copyright information; whenfalse
, is hidden.show_related
: Boolean controlling whether the ‘next/previous/related’ secondary navigation elements are hidden or displayed. Defaults tofalse
since on many sites these elements are superfluous.page_width
: CSS width specifier controlling default content/page width. Defaults to940px
.sidebar_width
: CSS width specifier controlling default sidebar width. Defaults to220px
.fixed_sidebar
: Makes the sidebar ‘fixed’ or pinned in place, so that the main body of the page scrolls but the sidebar remains visible. (Applies only to desktop window sizes; the mobile view is unaffected.) Defaults tofalse
.
Style colors¶
These should be fully qualified CSS color specifiers such as #004B6B
or
#444
. The first few items in the list are “global” colors used as defaults
for many of the others; update these to make sweeping changes to the
colorscheme. The more granular settings can be used to override as needed.
gray_1
: Dark gray.gray_2
: Light gray.gray_3
: Medium gray.pink_1
: Light pink.pink_2
: Medium pink.body_text
: Main content text.footer_text
: Footer text (includes links.)link
: Non-hovered body links.link_hover
: Body links, hovered.sidebar_header
: Sidebar headers. Defaults togray_1
.sidebar_text
: Sidebar paragraph text.sidebar_link
: Sidebar links (there is no hover variant.) Applies to both header & text links. Defaults togray_1
.sidebar_link_underscore
: Sidebar links’ underline (technically a bottom-border).sidebar_search_button
: Background color of the search field’s ‘Go’ button.sidebar_list
: Foreground color of sidebar list bullets & unlinked text.sidebar_hr
: Color of sidebar horizontal rule dividers. Defaults togray_3
.anchor
: Foreground color of section anchor links (the ‘paragraph’ symbol that shows up when you mouseover page section headers.)anchor_hover_fg
: Foreground color of section anchor links (as above) when moused over. Defaults togray_1
.anchor_hover_bg
: Background color of above.note_bg
: Background of.. note::
blocks. Defaults togray_2
.note_border
: Border of same.seealso_bg
: Background of.. seealso::
blocks. Defaults togray_2
.seealso_border
: Border of same.warn_bg
: Background of.. warn::
blocks. Defaults topink_1
.warn_border
: Border of same. Defaults topink_2
.footnote_bg
: Background of footnote blocks.footnote_border
: Border of same. Defaults togray_2
.pre_bg
: Background of preformatted text blocks (including code snippets.) Defaults togray_2
.narrow_sidebar_bg
: Background of ‘sidebar’ when narrow window forces it to the bottom of the page.narrow_sidebar_fg
: Text color of same.narrow_sidebar_link
: Link color of same. Defaults togray_3
.code_highlight
: Color of highlight when using:emphasize-lines:
in a code block.
Fonts¶
font_family
: Font family of body text. Defaults to'goudy old style', 'minion pro', 'bell mt', Georgia, 'Hiragino Mincho Pro', serif
.font_size
: Font size of body text. Defaults to17px
(1.0625em
).head_font_family
: Font family of headings. Defaults to'Garamond', 'Georgia', serif
.code_font_size
: Font size of code block text. Defaults to0.9em
.code_font_family
: Font family of code block text. Defaults to'Consolas', 'Menlo', 'Deja Vu Sans Mono', 'Bitstream Vera Sans Mono', monospace
.caption_font_size
: Font size of caption block text. Defaults tofont-size
.caption_font_family
: Font family of caption block text. Defaults tofont-family
.