{"id":2773,"library":"sphinx-basic-ng","title":"Sphinx Basic NG","description":"Sphinx Basic NG (sphinx-basic-ng) is a modernised skeleton for Sphinx themes, providing a foundational three-column layout and shared implementations of common components. It aims to simplify Sphinx theme development by offering a consistent vocabulary and a robust base to build upon, serving as an advanced alternative to Sphinx's built-in basic theme. The current version is 1.0.0b2. As a foundational toolkit, its release cadence is likely tied to major Sphinx updates and the evolution of documentation design patterns.","status":"active","version":"1.0.0b2","language":"en","source_language":"en","source_url":"https://github.com/pradyunsg/sphinx-basic-ng","tags":["Sphinx","Theme","Documentation","Theming","Beta"],"install":[{"cmd":"pip install sphinx-basic-ng","lang":"bash","label":"Install latest beta version"}],"dependencies":[{"reason":"Sphinx-basic-ng is a theme skeleton for Sphinx and requires Sphinx to build documentation.","package":"Sphinx","optional":false}],"imports":[{"note":"Sphinx themes are activated by setting the 'html_theme' configuration variable in your project's conf.py file.","symbol":"html_theme","correct":"# in conf.py\nhtml_theme = \"sphinx_basic_ng\""}],"quickstart":{"code":"import os\nimport sys\n\n# Basic Sphinx project setup (run sphinx-quickstart first)\nproject = 'My Awesome Project'\ncopyright = '2024, Your Name'\nauthor = 'Your Name'\nrelease = '0.1.0'\n\n# -- General configuration ---------------------------------------------------\nextensions = [\n    'sphinx.ext.autodoc',\n    'sphinx.ext.napoleon',\n    'sphinx.ext.viewcode',\n    'sphinx.ext.todo',\n]\n\ntemplates_path = ['_templates']\nexclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']\n\n# -- Options for HTML output -------------------------------------------------\nhtml_theme = 'sphinx_basic_ng'\nhtml_static_path = ['_static']\n\n# Example of theme options (customize as needed)\nhtml_theme_options = {\n    'sidebar_hide_logo': False,\n    'light_css_variables': {\n        'color-brand-primary': '#6200EE',\n        'color-brand-content': '#00B0FF',\n    },\n    'dark_css_variables': {\n        'color-brand-primary': '#BB86FC',\n        'color-brand-content': '#00B0FF',\n    }\n}","lang":"python","description":"After initializing a Sphinx project with `sphinx-quickstart`, modify your `conf.py` file to set `html_theme = 'sphinx_basic_ng'`. You can further customize the theme via `html_theme_options`."},"warnings":[{"fix":"Review changelogs and migration guides for each new release. Pin dependencies to specific versions to manage updates.","message":"As a beta release (1.0.0b2), the API and internal structure of sphinx-basic-ng may not be stable. Expect potential breaking changes in future minor or patch releases before a stable 1.0.0.","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"Understand that `sphinx-basic-ng` provides components and a layout structure. You will need to write custom CSS/JS and potentially override Jinja2 templates to achieve a complete theme. Refer to its documentation for how to extend and customize.","message":"sphinx-basic-ng is a 'skeleton' or 'base' theme, not a fully-fledged, ready-to-use theme. Users are expected to build their own themes on top of it, which requires custom templating, CSS, and potentially JavaScript. Simply activating it will provide a minimal, unstyled foundation.","severity":"gotcha","affected_versions":"All"},{"fix":"Ensure your project's `conf.py` includes `needs_sphinx = 'X.Y'` where `X.Y` is a Sphinx version known to be compatible with your `sphinx-basic-ng` version. Check the `sphinx-basic-ng` documentation or its `pyproject.toml` for supported Sphinx ranges.","message":"Compatibility with specific Sphinx versions is crucial. Past alpha versions explicitly bumped support (e.g., 'Bump up to Sphinx 4'). Incompatible Sphinx versions can lead to build errors or unexpected rendering issues.","severity":"gotcha","affected_versions":"All"},{"fix":"Avoid relying on underscored (private) attributes or undocumented APIs. Use officially exposed theme options and extension points. If customization requires deeper integration, track the `sphinx-basic-ng` and Sphinx changelogs closely.","message":"Internal APIs, like direct access to `_html_page_context`, have been removed in earlier alpha versions. Relying on undocumented internal Sphinx or `sphinx-basic-ng` structures may lead to breakage in updates.","severity":"deprecated","affected_versions":"Older alpha versions (e.g., prior to 0.0.1.alpha8)"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}