If I create some RST like:

.. image:: ../my_image.png
  :align: center
  :scale: 60%

I noticed that unlike vanilla Sphinx the image is not aligned to the center of the page, and is still right justified instead.

• reference to docs about .. image::

00385d6#diff-b4ef698db8ca845e5845c4618278f29aR6 added slugify dependency which was not released since 2010 year (https://pypi.org/project/slugify/#history) and seems unmaintained. This package supports only Python 2.

https://pypi.org/project/python-slugify/ is the right dependency and it is already at requirements.txt

PS: hm... tag for 0.0.29 release is missed at github, but presents at pypi

Hey. Not sure this is in scope or not. Maybe it would be nice to add a copy button to each snippet, like what is done here. Maybe be using clipboard.js?

Hi,
First, lots of thanks for providing this pretty theme.

My question is: does this theme provide a way to show an icon after each external link?

Example:

Thanks,
Coco

Hey, great work on this.

I just tried it out and got the following error when running make html: WARNING: unsupported theme option 'nav_name' given

#70 fixed alignment for images, but list-tables seem to still not be aligned when :align: center is specified.

.. list-table:: My Table
   :header-rows: 1
   :align: center

   * - Column 1
     - Column 2
   * - Item 1
     - Item 2

The resulting table will be right justified rather than centered.

Related to #64

On the example page:

https://bashtage.github.io/sphinx-material/index.html#

The title bar text links are white and the side bar links are black and turn to blue when selected.

But when I try a simple configuration:

html_sidebars = {
    "**": ["logo-text.html", "globaltoc.html", "localtoc.html", "searchbox.html"]
}

html_theme = 'sphinx_material'

html_theme_options = {
    'nav_title': 'Test',
}

All of my links are blue even before or after clicking. I've tried changing color_* and theme_color but haven't been able to emulate what the demonstration site is doing.

First off, thank you for this wonderful theme! In migrating my python lib's docs to using it, I noticed that all the code-blocks are clipping the first 2 characters (and the last 2 characters of the longest lines) when viewing it on a mobile display. Maybe "clipping" isn't the right description because the code in code-blocks without linenumbers just overflow the code-blocks' background box.

For examples you can load the demonstration site's "Additional Samples->Code" on a phone or shrink the browser window to minimum width.

I'm not sure you would qualify this as a bug, but it's certainly strange. The global TOC always include the page's content (titles up to the given globaltoc_depth), even if:

• a contents directive is included in the current document
• the localtoc.html template is selected

Which means there can be up to three times the same information on a given page, which looks odd and occupy space with no benefit. Is there a way to modify this behaviour to:

• hide contents completely from the global TOC (that would be enough for me since I always display the local TOC)
• hide document content only if either the local TOC is visible

Note that in both cases I want to keep nested TOC entries in the global TOC. I also would like to avoid modifying documents to achieve this.

I say it's not a bug because it also happens in the example doc:

It's very confusing that Configuration Options, Sidebars, etc. appears in the global TOC. It's confusing for (at least) three reasons:

1. it's not global
2. it already appears in the local TOC
3. its mixed with actual TOC (which we don't see here but h1 title from the page are mixed with depth 2 TOC entries)

The global toctree does not always render very well on mobile after #49 . This should be improved.

The HTML context object provided by this package contains functions as values. As a result, the config hash in the .buildinfo generated by the HTML builder changes on every build, since it includes the str of a function, which includes an address in memory that changes each time (e.g., <function table_fix at 0x7f5dcdef2738>). Therefore the caching is broken and Sphinx does a full rebuild each time.

I've also opened an issue on the Sphinx repo, since I don't know whether this case is intended to be supported or not.

Steps to reproduce the behavior:

$ wget https://github.com/sphinx-doc/sphinx/files/4146498/sphinx-test.zip
$ unzip sphinx-test.zip
$ cd sphinx-test
$ pip install -r requirements.txt
$ make html
...
building [html]: targets for 1 source files that are out of date
...
$ make html
...
building [html]: targets for 1 source files that are out of date
...

The second time, there should be no files marked out of date.

Issue

When the index has multiple tocs, with their own captions, the globaltoc only shows the last caption.

Expected Behavior

That the captions will be rendered as expected.

Example

.. include:: ../README.rst

.. toctree::
   :caption: Theme Documentation
   :maxdepth: 2

   installing
   configuring
   contributing

.. toctree::
   :maxdepth: 1
   :hidden:

   changelog

.. toctree::
    :maxdepth: 2
    :numbered:
    :caption: Demo Documentation

    demo/structure
    demo/demo
    demo/lists_tables
    demo/api

.. toctree::
    :maxdepth: 3
    :numbered:
    :caption: This is an incredibly long caption for a long menu

    demo/long

This will not render properly. It will go through each toctree and grab the listed documents, but not include the captions. Instead, only the last caption is rendered. Looking at the Ansible documentation that is using Read The Docs theme, the captions render properly when using that theme but not when using Material.

Is this something that can be fixed, or added as a supported feature? It looks like the globaltoc file would need to be edited.

Hi, I am using this theme for my docs, and I access the web pages via broswer from China. Always get an error, like this:

GET https://fonts.googleapis.com/css?family=Roboto+Mono:400,500,700|Roboto:300,400,400i,700&display=fallback net::ERR_TIMED_OUT

So, everytime I have to wait a few seconds until time out. Is it necessary add this link in layout.html? And how can I (and so many Chinese) aviod this error?

Thanks! ❤️

Currently there is no space between [source] and a function or class declaration.

e.g. (copied text):

class MyClass(args)[source]¶

Maybe a space/set of spaces could be added/the [source] text could be aligned to the right?:

class MyClass(args) [source]¶

Good morning

First, thanks a lot for this theme, which is in my opinion the best-looking theme for sphinx ever.

I had a little problem with the right toc overflowing to the right with certain dimensions, including maximized browser on a standard 15in macbook pro. Here is a screenshot in Safari, but it's the same in Chrome and Firefox.

As a workaround, I created a custom css and put this in

nav.md-nav--secondary {
margin-right: 2em;
}

which seems to solve the problem at all sizes now (screenshot).

I know this is only a workaround, but I wanted to let you know.

Thanks again,

Félix

Python 3.8
Pip 20

ERROR: Command errored out with exit status 1:
     command: /usr/local/bin/python -c 'import sys, setuptools, tokenize; sys.argv[0] = '"'"'/tmp/pip-install-3291xvju/sphinx-material/setup.py'"'"'; __file__='"'"'/tmp/pip-install-3291xvju/sphinx-material/setup.py'"'"';f=getattr(tokenize, '"'"'open'"'"', open)(__file__);code=f.read().replace('"'"'\r\n'"'"', '"'"'\n'"'"');f.close();exec(compile(code, __file__, '"'"'exec'"'"'))' egg_info --egg-base /tmp/pip-install-3291xvju/sphinx-material/pip-egg-info
         cwd: /tmp/pip-install-3291xvju/sphinx-material/
    Complete output (5 lines):
    Traceback (most recent call last):
      File "<string>", line 1, in <module>
      File "/tmp/pip-install-3291xvju/sphinx-material/setup.py", line 5, in <module>
        with open("requirements.txt") as reqs:
    FileNotFoundError: [Errno 2] No such file or directory: 'requirements.txt'
    ----------------------------------------
ERROR: Command errored out with exit status 1: python setup.py egg_info Check the logs for full command output.

The error is fairly straightforward. I've been bitten by this myself personally. I downloaded your tar from pypi and it's missing the requirements.txt file. Your setup.py is trying to read that file.

I suggest you delete the requirements.txt and requirements-dev.txt and stick to using only the setup.py so you don't forget these files in the future.

Hi! I am using this sphinx theme for a project documentation in GitLab.

I have noticed that in the documentation there is an option in html_theme_options to change the repository type (repo_type) to one of "github"; "gitlab" or "bitbucket". However, when I set it to "gitlab" (having specified the repo_url, of course), I don't get an icon nor the starts/forks of the project (just the title of the project), as I would in the GitHub counterpart.

Is that the expected behavior for now or am I doing something wrong?

This is the schema of my current HTML options in conf.py:

html_theme_options = {
    # Set the name of the project to appear in the navigation.
    "nav_title": "repo",
    "repo_url": "url to gitlab package",
    "repo_name": "repo_name",
    "repo_type": "gitlab",
    "html_minify": False,
    "html_prettify": True,
    "css_minify": True,
    "globaltoc_depth": 2,
    "color_primary": "green",
    "color_accent": "light-green",
    "theme_color": "#2196f3",
    "master_doc": False,
    "heroes": {
          ...
    },
}

Thank you!

Hi, first off, thanks for this amazing project!
Is there a way to set primary_color to a custom hex value? Material-UI implementations usually allow it but it doesn't seem to work to simply write primary_color = '#0062ab' in conf.py.

Good day. First of all - awesome project!

For some reason all code block backgrounds are yellow:

While in your examples they are gray. Do you have an idea why and how do I control it? I tried comparing my config with yours in this repo and didn't find any relevant knobs.

Thank you!

Revert #35 which has cause a number of issues.

Same issue as typlog/sphinx-typlog-theme#17

See for example https://nbsphinx.readthedocs.io/en/material-theme/code-cells.html#ANSI-Colors

Hi, thanks for this amazing theme!

However, for me the global TOC does not appear on the right. I use sphinx version 3.2.1. The console shows a few errors but I don't think they explain the missing TOC

Access to XMLHttpRequest at 'file:///Users/stef/bodyschema/bs-pose-fit/doc/build/html/versions.json' from origin 'null' has been blocked by CORS policy: Cross origin requests are only supported for protocol schemes: http, data, chrome, chrome-extension, chrome-untrusted, https.
versions.json:1 Failed to load resource: net::ERR_FAILED
application.js:244 Uncaught TypeError: Cannot read property 'style' of undefined
    at e.t.reset (application.js:244)
    at e.t.unlisten (application.js:74)
    at MediaQueryList.MatchMedia.handler_ (application.js:79)
t.reset @ application.js:244
t.unlisten @ application.js:74
MatchMedia.handler_ @ application.js:79
application.js:244 Uncaught TypeError: Cannot read property 'style' of undefined
    at e.t.reset (application.js:244)
    at e.t.unlisten (application.js:74)
    at MediaQueryList.MatchMedia.handler_ (application.js:79)

Hello, I am trying to install this theme locally on ReadTheDocs (Sphinx Engine). I cloned the git repository, ran the setup.py script and copied the generated sphinx-material directory to my docs/_theme folder and set the theme path on my conf.py but I get following error:

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/invstr-invstr-doc-test/envs/latest/lib/python3.7/site-packages/sphinx/cmd/build.py", line 303, in build_main
    args.tags, args.verbosity, args.jobs, args.keep_going)
  File "/home/docs/checkouts/readthedocs.org/user_builds/invstr-invstr-doc-test/envs/latest/lib/python3.7/site-packages/sphinx/application.py", line 263, in __init__
    self._init_builder()
  File "/home/docs/checkouts/readthedocs.org/user_builds/invstr-invstr-doc-test/envs/latest/lib/python3.7/site-packages/sphinx/application.py", line 324, in _init_builder
    self.builder.init()
  File "/home/docs/checkouts/readthedocs.org/user_builds/invstr-invstr-doc-test/envs/latest/lib/python3.7/site-packages/sphinx/builders/html.py", line 329, in init
    self.init_templates()
  File "/home/docs/checkouts/readthedocs.org/user_builds/invstr-invstr-doc-test/envs/latest/lib/python3.7/site-packages/sphinx/builders/html.py", line 375, in init_templates
    self.theme = theme_factory.create(themename)
  File "/home/docs/checkouts/readthedocs.org/user_builds/invstr-invstr-doc-test/envs/latest/lib/python3.7/site-packages/sphinx/theming.py", line 286, in create
    '(missing theme.conf?)') % name)
sphinx.errors.ThemeError: no theme named 'sphinx_material' found (missing theme.conf?)

Theme error:
no theme named 'sphinx_material' found (missing theme.conf?)

Thanks in advance, really nice theme.

• Minimize javascript
• Reconsider location and spacing
• Reduce to side bar for responsive

Example code: https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#grammar-production-displays

It's bad security practice to save any secrets, encrypted or otherwise, within a code repository:

• https://github.com/bashtage/sphinx-material/blob/master/github_deploy_key_bashtage_sphinx_material.enc

I'm not sure what you are using it for, but it may be a good idea to look into alternative means of whatever it is used for (and potentially recreate whatever the key is meant for). GitHub Actions may have what you are looking for, if it is meant to work with the GitHub API. You can use secrets in CI tooling without needing to save them to a code repository.

Example for code formatting below - the gray background color is applied to the whitespace after the item the formatting is applied to.

Extra space added after internal reference:

I see the following TODO item in the theme.conf:

https://github.com/bashtage/sphinx-material/blob/master/sphinx_material/sphinx_material/theme.conf#L9

Is this about how mkdocs has implemented theirs:

• https://squidfunk.github.io/mkdocs-material/ (different home/index page, and then docs pages navigated to via headers)

If so, I'd love to help implement this but I am not quite sure where to start? If you have guidance, I can take a shot at attempting to introduce this feature. I suppose it would be something like a template that a user has in their repo that gets

Unless the title of the previous/next page happens to be "Material"/"Admonition", respectively.

Those titles appear when hovering over the buttons/links.

Suppose I have a page like:

==========
Chapter A
==========

.. toctree::
   :hidden:
   :glob:
   :maxdepth: 1

   a/*

Intro
========

Introduction text

Terminology-wise I'll refer to Intro as an "internal" section heading as this is defined on the same page, and a/* as "external" section headings as they are defined on subpages.

Currently sphinx-material in the global TOC renders all the subsection headings a/* plus Intro directly below Chapter A in the tree, as per what the above syntax defines. In the local TOC however, this renders just Intro directly below Chapter A, i.e. only the internal section heading.

I would like to omit rendering Intro (i.e. the internal section heading) in the global TOC, and only render external section headings, however I couldn't figure out how to change globaltoc.html and localtoc.html to do this. Clearly there is some way of distinguishing the internal vs external section headings, could you please advise?

Hey, just wondering if logo_icon is intended to work with image files (e.g., an SVG file)? I've tried passing a path but it didn't work. I'm aware that I can override the HTML template but I thought it might be nice to support this out of the box.

Any idea how to address this? Thanks!

References
----------

.. [Andersson20] Alma Andersson, Joseph Bergenstråhle, Michaela Asp, Ludvig Bergenstråhle, Aleksandra Jurek, José Fernández Navarro & Joakim Lundeberg (2020),
   *Single-cell and spatial transcriptomics enables probabilistic inference of cell type topography*,
   `Communications Biology <https://www.nature.com/articles/s42003-020-01247-y>`__.

I noticed that statsmodels web page still has the transparent drop down. That was fixed in #23.

Any chance you could do a release before the next commit for statsmodels?

The link pilcrow on headers shows when the cursor hovers on the header, but it does not show for things like Python function generated by autodoc. For instance, see https://bashtage.github.io/sphinx-material/pymethod.html#send_message, there is a pilcrow after the parameter list of the send_message function, but its opacity is 0 and it is not adjusted when the cursor hovers.

I think this is just due to a missing or overly-constrained CSS rule.

tl;dr please remove "black" from "install_requires" in setup.py.

"black" is a development dependency for this project. Unfortunately, it is being treated as a runtime dependency in setup.py and pinned to version 19.3b0. My project uses black version 19.10b0 as a development dependency, which makes my library's development environment unnecessarily incompatible with this sphinx theme.

When setting 'color_primary': '#FFFF00', (yellow), the top bar ends up being colored purple (regardless of the hex code input). Is this a bug?

I'd like to know if there is some documentation I can follow to properly make use of versioneer.py and _version.py when it comes to properly versioning my repo/docs.

Since it looks like an understanding of that implementation is a prerequisite in understanding how to make use of docs/_static/versions.json and the version settings in the html_theme_options.

It looks like the tooling helps tag a point in the repo tied to that version, and that the versions.json helps dictate which versions ultimately become available as documentation to generate and view on the generated website. Though, I don't know how to make use of this in the best way that ensures a working site with versions.

If there is a how-to or tutorial somewhere on how this is managed by this repo and by sites making use of the version management (like https://www.statsmodels.org/stable/index.html), I'd love to test it out and implement it in my own deployments.

Edit: I have managed to do this without many changes and with good enough results - posting results in comment below.

Before anything thank you for the great project. Following from the discussion on #66, this issue is primarily to explore the options and documentation that could be available to extend the current base colours provided.

The context is the following: Currently the colours provided are quite good, however it would be quite useful if there can be a way to provide a custom HEX to override the colours as opposed to these just being the avialable palettes. Specifically for us, the red goes very well with the theme of the brand of the project, but it does become a bit too much for the eyes. We would be keen to change the tone to make the red darker - we have been refraining ourselves from jumping into the CSS overrides as we wanted to ask here first for both roadmap question and best practice on overriding, as in the ideal world we would also like to take a step further and also have a different colour (non-red) for links.

My questions for this are:

1. Is there currently a way to override these in a modular way?
2. If not, is there a best practice in how this shoudl be done via CSS overrides (eg the relevant classes, etc) - perhaps the best answer is just to document this instead of doing the full CSS re-write
3. are there any plans/ thoughts of making this an extensible feature (I can see that in #66 it was mentioned that this may encompass an entire re-write of CSS so may not be desirable)

Thank you.

This page of the docs https://bashtage.github.io/sphinx-material/additional_samples.html#tables says that you can use cssclass on a table as shown below. But if you look at the source, css class is not being used.

When using docutils, the class directive on a table adds the css class. It seems that this theme is stripping those when it changes docutils classes to md.

It is also removing the footnote class, so those can not be styled differently when this theme.

my documentation is up in this URL: http://docs.mehrparsict.com/ahmadiehsan/

and you can see that left sidebar didn't have any title for choose, what is wrong in my configuration?

source directory content:

source/
├── conf.py
├── django.md
├── docker.md
├── elasticsearch.md
├── git.md
├── index.rst
├── kubernetes.md
├── linux.md
├── mysql.md
├── nginx.md
├── postgresql.md
├── python.md
├── react.md
├── _static
├── windows.md
└── wordPress.md

conf.py content

# Configuration file for the Sphinx documentation builder.
#
# This file only contains a selection of the most common options. For a full
# list see the documentation:
# http://www.sphinx-doc.org/en/master/config

# -- Path setup --------------------------------------------------------------

# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))

import sphinx_material


# -- Project information -----------------------------------------------------

project = 'Ehsan Ahmadi Personal Docs'
copyright = '2020, EHSAN AHMADI'
author = 'EHSAN AHMADI'

# The full version, including alpha/beta/rc tags
release = '1.0.0'


# -- General configuration ---------------------------------------------------

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
    'recommonmark',
    'sphinx_markdown_tables',
    'sphinx_material',
    'sphinx_copybutton',
]

# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']

# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = 'en'

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = []


# -- Markdown support configuration ---------------------------------------------------

source_suffix = {
    '.rst': 'restructuredtext',
    '.txt': 'markdown',
    '.md': 'markdown',
}


# -- Options for HTML output -------------------------------------------------

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
#
html_theme = 'sphinx_material'
html_theme_options = {
    'color_primary': 'indigo',
    'color_accent': 'blue',
    'logo_icon': '&#xe869',
    'master_doc': False,
}
html_theme_path = sphinx_material.html_theme_path()
html_context = sphinx_material.get_html_context()

# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']

index.rst content:

Ehsan Ahmadi Personal Docs
==========================

Table of Contents
=================

.. toctree::
   :maxdepth: 2
   :glob:

   *

Well, this project is absolutely great! It brings the best of both world! A nice theme and the power of Sphinx! The only thing bothering me a bit is writing docs in both restructuredtext (for autodoc and in docstrings) and markdown with recommonmark. We'd just need a proper markdown extension for Sphinx that imitates autodoc in markdown (like mkautodoc but with sphinx-autodoc features). Anyway, thank you for this 🙂 !

So my question is: do you plan on adding support for [sources] links and pages? Sometimes it's extremely useful to be able to see the source code of a function without having to leave the documentation site.

I'm trying to modify a page title without having an <h1> tag in my page. Is it possible?

The current behaviour when setting html_title = 'test' is to output <no title> test. I would for example like to remove the <no title> part so my page title is equal to html_title. Do I need to create a template for that?

Hi, thanks for this amazing theme!

However, for me the global TOC does not appear on the left. I use sphinx version 3.2.1. . I copied the default html_theme_options (on the readme) and added "version_dropdown": False. The console shows a single error:

application.js:244 Uncaught TypeError: Cannot read property 'style' of undefined
    at e.t.reset (application.js:244)
    at e.t.unlisten (application.js:74)
    at MediaQueryList.MatchMedia.handler_ (application.js:79)
t.reset @ application.js:244
t.unlisten @ application.js:74
MatchMedia.handler_ @ application.js:79

Examples from https://bashtage.github.io/sphinx-material/additional_samples.html#admonitions:

Regular text is 0.8rem while the text in admonitions is 0.85rem. The visual difference is quite large, and imho doesn't look good. I don't think this difference was done on purpose?

does this theme support RTL languages like Arabic ?

Is there any possibility to build this theme and host it on readthedocs without readthedocs defaulting to its own theme?

Some other custom themes provide a snippet in conf.py which apparently achieves this, e.g. this theme. Readthedocs also provides the same snippet in its documentation

if not on_rtd:  # only import and set the theme if we're building docs locally
     import sphinx_material
     # Required theme setup
     html_theme = 'sphinx_material'
     # html_theme_path = [sphinx_material.get_html_theme_path('sphinx_material')]
     html_theme_path = ["_themes/sphinx_material", ]`
# otherwise, readthedocs.org uses their theme by default, so no need to specify it

When I tried to implement this, html_theme_path = [sphinx_material.get_html_theme_path('sphinx_material')] fails with AttributeError: module 'sphinx_material' has no attribute 'get_html_theme_path', so I directly referenced the theme directory.

It's also unclear how the directory should be structured if just incorporating code into another project (i.e. where init.py and the rest of the sphinx_theme directory structure ought to sit relative to conf.py. In my case, I added an _themes directory one level up from the docs. Inside that, are located the __init__.py and _version.py scripts, and a directory sphinx_materials which houses theme.conf, the static directory and the html pages. I deleted everything else. Is this correctly implemented? Thanks

When parsing rst ordered lists, you can do something like:

a. item A
b. item B

Either sphinx or docutils is converting this into <ol class="loweralpha simple"> etc with the list style being applied in basic.css by the default theme:

ol.arabic {
    list-style: decimal;
}

ol.loweralpha {
    list-style: lower-alpha;
}

ol.upperalpha {
    list-style: upper-alpha;
}

ol.lowerroman {
    list-style: lower-roman;
}

ol.upperroman {
    list-style: upper-roman;
}

sphinx-material does not define these classes however, so these lists end up with roman numerals 1, 2, 3 etc in the generated html, contradicting the rst source code.

It would be really neat if there was a configuration option to enable a dark mode (light text on a dark background). This would enable producing docs that looks like: https://fastapi.tiangolo.com/

Some (or many) material components are not included here (e.g. mdc-card). I think it would be good to allow including components in the configuration script.

I can probably workaround this issue for now by using a custom stylesheet in sphinx.

The original mkdocs material theme is more "compact", i.e. content doesn't occupy all available space:

• (sphinx) https://www.statsmodels.org
• (mkdocs) https://fastapi.tiangolo.com (note available space in the left and right sides)

Is it possible achieve the same compactness with sphinx-material?