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

The Awesome Theme uses these Python tools:

Poetry to manage the Python dependencies and building the package
Nox to test and lint the Python code, and to build the docs
Pipx to install Python applications in isolated environments and making them available globally

If you want to use the same versions of the Python tools, you can provide a requirements.txt to the install commands.

To prepare the Python environment, run these commands:

terminal

pip install --user pipx [--requirement=requirements.txt]
pipx install poetry [--pip-args=--requirement=requirements.txt]
pipx install nox [--pip-args=--requirement=requirements.txt]

Install the Python dependencies

Create a local copy of the repository.
Install the Python dependencies:
terminal
```
poetry install
```
Optional: install and test the pre-commit hooks:
terminal
```
poetry run pre-commit install
```
If you don’t plan on committing 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 pre-commit with Poetry, run:
terminal
```
poetry run pre-commit run --all
```
Test your Nox environment.

You can run any Nox session to confirm that the environment is working. To list the available sessions, run:
terminal
```
nox --list-sessions
```
For example, run all default sessions:
terminal
```
nox
```

Prepare JavaScript environment

Confirm that Node.js is installed:
terminal
```
$ node --version
v20.00.0
```
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.
Optional: install yarn:
terminal
```
npm install --global yarn
```
If you want to use the same versions of JavaScript packages as in the Awesome Theme repository, use the Yarn package manager.

Install JavaScript dependencies

Create a local copy of the repository

Go to the theme-src/ directory:

terminal

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

Install the JavaScript dependencies:
terminal
```
yarn install
```
Build the theme:
terminal
```
yarn build
```