Build your own theme

Build your own theme by changing the templates or CSS.

---

The project has both Python and JavaScript dependencies. If you want to write documentation or modify the Python extensions, install the Python dependencies.

If you want to edit the Jinja2 templates, the CSS, or the JavaScript files, you also need to install the JavaScript dependencies.

Note

Because this theme uses Tailwind CSS to apply styles, you need to build the theme when you make modifications to the styles. It’s best to install the JavaScript dependencies, even if you just want to edit the HTML templates.

Prepare Python environment

To build the Awesome Theme, you’ll need uv and Nox.

Use your preferred installation method to install these tools. For example, if you’re already using uv, run:

uv tool install nox
Copy code

Install the Python dependencies

1. Create a local copy of the repository.

2. Install the Python dependencies:

   uv sync
   Copy code

3. Optional: install and test the pre-commit hooks:

   uv tool install pre-commit
   pre-commit install --hook-type pre-push
   Copy code

   If you don’t plan on publishing any changes to the repository, you can skip this step. You can see the active pre-commit hooks in the file .pre-commit-config.yaml.

   To test hooks, run:

   pre-commit run --all
   Copy code

   Note

   This project runs the hooks before you push instead. More commonly, hooks run before every commit.

4. Test your Nox environment.

   You can run any Nox session to confirm that the environment is working. To list the available sessions, run:

   nox --list-sessions
   Copy code

   For example, run all default sessions:

   nox
   Copy code

Prepare JavaScript environment

1. Confirm that Node.js is installed:

   $ node --version
   v20.00.0
   Copy code

   If the preceding command fails, make sure that you installed Node.js. If you installed Node.js, make sure that the path to the node executable is in your PATH environment variable.

   Tip

   For installing and managing different Node.js versions, see these projects: nvm, fnm, Volta, asdf.

2. Optional: install pnpm:

   npm install --global pnpm
   Copy code

   If you want to use the same versions of JavaScript packages as in the Awesome Theme repository, use the pnpm package manager.

Install JavaScript dependencies

1. Create a local copy of the repository

2. Go to the theme-src/ directory:

   ./sphinxawesome-theme/
   ├── src/
   │   ├── sphinxawesome_theme/
   │   └── theme-src/
   ├── docs/
   ├── tests/
   └── ...
   Copy code

3. Install the JavaScript dependencies:

   pnpm install
   Copy code

4. Build the theme:

   pnpm run build
   Copy code