{"id":13472410,"url":"https://github.com/jbms/sphinx-immaterial","last_synced_at":"2025-05-15T05:07:00.680Z","repository":{"id":37404848,"uuid":"410185773","full_name":"jbms/sphinx-immaterial","owner":"jbms","description":"Adaptation of the popular mkdocs-material material design theme to the sphinx documentation system","archived":false,"fork":false,"pushed_at":"2025-05-10T03:04:44.000Z","size":124061,"stargazers_count":229,"open_issues_count":44,"forks_count":34,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-05-10T04:18:48.371Z","etag":null,"topics":["documentation","material-design","sphinx","static","theme"],"latest_commit_sha":null,"homepage":"https://jbms.github.io/sphinx-immaterial/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jbms.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-09-25T05:35:19.000Z","updated_at":"2025-05-02T22:43:51.000Z","dependencies_parsed_at":"2023-10-04T08:57:57.099Z","dependency_job_id":"a291cda1-daa5-43a9-8312-e9cd36a48293","html_url":"https://github.com/jbms/sphinx-immaterial","commit_stats":{"total_commits":176,"total_committers":16,"mean_commits":11.0,"dds":"0.31818181818181823","last_synced_commit":"edbc4fab0dfa6f5fe911d1a56f4be9ee29f8b750"},"previous_names":[],"tags_count":46,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jbms%2Fsphinx-immaterial","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jbms%2Fsphinx-immaterial/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jbms%2Fsphinx-immaterial/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jbms%2Fsphinx-immaterial/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jbms","download_url":"https://codeload.github.com/jbms/sphinx-immaterial/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254276447,"owners_count":22043867,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["documentation","material-design","sphinx","static","theme"],"created_at":"2024-07-31T16:00:54.437Z","updated_at":"2025-05-15T05:06:55.663Z","avatar_url":"https://github.com/jbms.png","language":"Python","readme":"Sphinx-Immaterial Theme\n=======================\n\n|MIT License| |PyPI Package| |CI status| |codecov-badge|\n\nThis theme is an adaptation of the popular `mkdocs-material\n\u003chttps://github.com/squidfunk/mkdocs-material/\u003e`__ theme for the `Sphinx\n\u003chttps://www.sphinx-doc.org/\u003e`__ documentation tool.\n\nThis theme is regularly maintained to stay up to date with the upstream\n`mkdocs-material \u003chttps://squidfunk.github.io/mkdocs-material/\u003e`__ repository.\nThe HTML templates, JavaScript, and styles from the `mkdocs-material\n\u003chttps://squidfunk.github.io/mkdocs-material/\u003e`__ theme are incoroprated directly\nwith mostly minor modifications.\n\nThis theme is a fork of the `sphinx-material\n\u003chttps://github.com/bashtage/sphinx-material\u003e`__ theme, which proved the concept\nof a Sphinx theme based on an earlier version of the `mkdocs-material\n\u003chttps://squidfunk.github.io/mkdocs-material/\u003e`__ theme, but has now\nsignificantly diverged from the upstream `mkdocs-material\n\u003chttps://squidfunk.github.io/mkdocs-material/\u003e`__ repository.\n\nSee `this theme's own documentation\n\u003chttps://jbms.github.io/sphinx-immaterial/\u003e`__ for a demonstration.\n\nWARNING: This theme is still in beta.  While it is already very usable, breaking\nchanges will still be made prior to the 1.0 release.\n\nInstallation\n------------\n\nInstall via pip:\n\n.. code-block:: bash\n\n    $ pip install sphinx-immaterial\n\nor if you have the code checked out locally:\n\n.. code-block:: bash\n\n    $ pip install -e .\n\nConfiguration\n-------------\n\nIn your `conf.py` add `sphinx_immaterial` as an extension:\n\n.. code-block:: python\n\n    extensions = [\n        ...,\n        \"sphinx_immaterial\"\n    ]\n\nand add the following:\n\n.. code-block:: python\n\n    html_theme = 'sphinx_immaterial'\n\nto set the theme.\n\nCustomizing the layout\n----------------------\n\nYou can customize the theme by overriding Jinja template blocks. For example,\n'layout.html' contains several blocks that can be overridden or extended.\n\nPlace a 'layout.html' file in your project's '/_templates' directory.\n\n.. code-block:: bash\n\n    mkdir source/_templates\n    touch source/_templates/layout.html\n\nThen, configure your 'conf.py':\n\n.. code-block:: python\n\n    templates_path = ['_templates']\n\nFinally, edit your override file 'source/_templates/layout.html':\n\n::\n\n    {# Import the theme's layout. #}\n    {% extends '!layout.html' %}\n\n    {%- block extrahead %}\n    {# Add custom things to the head HTML tag #}\n    {# Call the parent block #}\n    {{ super() }}\n    {%- endblock %}\n\nDifferences from mkdocs-material\n--------------------------------\n\nThis theme closely follows the upstream `mkdocs-material\n\u003chttps://github.com/squidfunk/mkdocs-material/\u003e`__ repository, but there are a\nfew differences, primarily due to differences between Sphinx and MkDocs:\n\n- This theme adds styles for Sphinx object descriptions, commonly used for API\n  documentation (e.g. class and function documentation).  This is a core element\n  of Sphinx for which there is no corresponding feature in MkDocs.\n\n- mkdocs-material uses `lunr.js \u003chttps://lunrjs.com/\u003e`__ for searching, and has\n  custom UI components for displaying search results in a drop-down menu as you\n  type the search query.  This theme uses a separate search implementation based\n  on the custom index format used by Sphinx, which fully integrates with the\n  search UI provided by mkdocs-material.\n\n.. |MIT License| image:: https://img.shields.io/badge/License-MIT-blue.svg\n   :target: https://opensource.org/licenses/MIT-Clause\n\n.. |PyPI Package| image:: https://img.shields.io/pypi/v/sphinx-immaterial\n   :target: https://pypi.org/project/sphinx-immaterial\n\n.. |CI status| image:: https://github.com/jbms/sphinx-immaterial/actions/workflows/build.yml/badge.svg\n   :target: https://github.com/jbms/sphinx-immaterial/actions/workflows/build.yml\n\n.. |codecov-badge| image:: https://codecov.io/gh/jbms/sphinx-immaterial/graph/badge.svg?token=IGK0B3WN42\n   :alt: codecov\n   :target: https://codecov.io/gh/jbms/sphinx-immaterial\n","funding_links":[],"categories":["Python"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjbms%2Fsphinx-immaterial","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjbms%2Fsphinx-immaterial","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjbms%2Fsphinx-immaterial/lists"}