sphinx-basic-ng

sphinx-basic-ng is a foundational Sphinx theme designed to be extended rather than used directly. It replaces Sphinx’s built-in basic theme with a modern, responsive three-column skeleton and a set of unstyled HTML components — breadcrumbs, edit-this-page links, sidebars, and more — that theme authors compose into their own designs.

The project deliberately avoids providing visual styling or requiring any Python or JavaScript to use its components, keeping the surface area small so downstream themes can layer their own CSS and behavior on top. It’s best known as the base that the widely used Furo theme builds upon.

What You Get

• A responsive 3-column HTML/Jinja2 skeleton (primary sidebar, content, secondary sidebar) registered as the basic-ng Sphinx theme
• A component library covering breadcrumbs, edit-this-page, view-this-page, related pages, search input, and sidebar toggles
• Section-level templates (header, footer, article, announcements) that can be overridden independently in a derivative theme
• A barebones test/demo site plus nox tasks for previewing the skeleton locally without building a full theme first

Common Use Cases

• Bootstrapping a brand-new Sphinx theme instead of reimplementing page structure from scratch
• Sharing components across a family of related themes, the way Furo builds on this project
• Prototyping a 3-column documentation layout before adding custom styling
• Using the components as a reference implementation for common Sphinx theme UI patterns

Under The Hood

Architecture The package is intentionally minimal — a single Python module (src/sphinx_basic_ng/__init__.py) whose setup() function registers an HTML theme with Sphinx via app.add_html_theme(), pointing at a theme/basic-ng/ directory of Jinja2 templates. All real behavior lives in the template layer, not Python: layout.html composes sections/*.html (header, footer, sidebars, article), each of which further composes components/*.html snippets (breadcrumbs, search box, edit-this-page) using Sphinx’s built-in template context. There is no plugin or hook system beyond the theme registration itself and no JS build step — the architecture is a template-inheritance tree, and downstream themes like Furo extend it by overriding individual section and component templates by filename convention.

Tech Stack The only runtime dependency is sphinx>=4.0, targeting Python 3.7+; packaging is plain setuptools via setup.cfg/setup.py, with no pyproject.toml build backend declared. The docs extra pulls in furo, myst-parser, sphinx-copybutton, sphinx-inline-tabs, and ipython, and the project’s own documentation site is built with Furo, dogfooding the theme it underpins. Task automation runs through nox (notably a docs-live task for previewing the skeleton against the tests/barebones fixture site), with .flake8 and .pre-commit-config.yaml for linting and Prettier configured for template/CSS formatting. Docs are hosted on Read the Docs per .readthedocs.yml.

Code Quality There is effectively one Python file of substance, using type hints throughout (Dict[str, Any]) but too small to demonstrate broader conventions. No automated test suite was found — tests/barebones/ is a fixture Sphinx project intended for manual visual verification via nox -s docs-live, not pytest-based assertions. Linting and formatting are enforced through pre-commit hooks (flake8, Prettier) rather than a CI test matrix.

API Design The extension surface is deliberately tiny: a theme author adopts the base by setting html_theme = "basic-ng" and then overrides individual section or component templates by filename, with no subclassing, Python hooks, or JS build step required to use or extend a component. That convention-based, filename-driven override model keeps the barrier to entry low for template-literate theme authors, though the project itself is explicit that it carries no backwards-compatibility guarantees while in its alpha state.