Skip to content
A material-based, responsive theme inspired by mkdocs-material
CSS JavaScript Python HTML
Branch: master
Clone or download
bashtage ENH: Increase font weights for RobotoMono
Increase font-weight support for RobotoMono

xref #15
Latest commit b1c5f7c Dec 6, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
docs
sphinx_material ENH: Increase font weights for RobotoMono Dec 5, 2019
tools ENH: Repackage toc data to use templates Aug 26, 2019
.gitattributes
.gitignore BLD: Prepare PyPI release Aug 23, 2019
.pep8speaks.yml
.travis.yml ENH: Improve notebook generation Sep 1, 2019
LICENSE.md BLD: Prepare PyPI release Aug 23, 2019
MANIFEST.in BLD: Prepare PyPI release Aug 23, 2019
README.rst
github_deploy_key_bashtage_sphinx_material.enc DOC: Update doctr Aug 23, 2019
requirements.txt DOC: Add badges Aug 26, 2019
setup.cfg ENH: Repackage toc data to use templates Aug 26, 2019
setup.py MAINT: Improve classifiers Aug 29, 2019
versioneer.py ENH: Repackage toc data to use templates Aug 26, 2019

README.rst

Material Sphinx Theme

Continuous Integration

Travis Build Status

Release

PyPI Status

License

MIT License

A Material Design theme for Sphinx documentation. Based on Material for MkDocs, and Guzzle Sphinx Theme.

See the theme's demonstration site for examples of rendered rst.

Installation

Install via pip:

$ pip install git+https://github.com/bashtage/sphinx-material

or if you have the code checked out locally:

$ python setup.py install

Configuration

Add the following to your conf.py:

import sphinx_material

 # Register the theme as an extension to generate a sitemap.xml
extensions.append('sphinx_material')

# Choose the material theme
html_theme = 'sphinx_material'
# Get the them path
html_theme_path = sphinx_material.html_theme_path()
# Register the required helpers for the html context
html_context = sphinx_material.get_html_context()

There are a lot more ways to customize this theme, as this more comprehensive example shows:

import sphinx_material

# Required theme setup
extensions.append('sphinx_material')
html_theme = 'sphinx_material'
html_theme_path = sphinx_material.html_theme_path()
html_context = sphinx_material.get_html_context()

# Material theme options (see theme.conf for more information)
html_theme_options = {

    # Set the name of the project to appear in the navigation.
    'nav_title': 'Project Name',

    # Set you GA account ID to enable tracking
    'google_analytics_account': 'UA-XXXXX',

    # Specify a base_url used to generate sitemap.xml. If not
    # specified, then no sitemap will be built.
    'base_url': 'https://project.github.io/project',

    # Set the color and the accent color
    'color_primary': 'blue',
    'color_accent': 'light-blue',

    # Set the repo location to get a badge with stats
    'repo_url': 'https://github.com/project/project/',
    'repo_name': 'Project',

    # Visible levels of the global TOC; -1 means unlimited
    'globaltoc_depth': 3,
    # If False, expand all TOC entries
    'globaltoc_collapse': False,
    # If True, show hidden TOC entries
    'globaltoc_includehidden': False,
}

Customizing the layout

You can customize the theme by overriding Jinja template blocks. For example, 'layout.html' contains several blocks that can be overridden or extended.

Place a 'layout.html' file in your project's '/_templates' directory.

mkdir source/_templates
touch source/_templates/layout.html

Then, configure your 'conf.py':

templates_path = ['_templates']

Finally, edit your override file 'source/_templates/layout.html':

{# Import the theme's layout. #}
{% extends '!layout.html' %}

{%- block extrahead %}
{# Add custom things to the head HTML tag #}
{# Call the parent block #}
{{ super() }}
{%- endblock %}
You can’t perform that action at this time.