# Upgrading from 0.x to 1.0

This guide explains how to upgrade the version of the ScyllaDB Sphinx Theme.

## How to check your current theme version

The theme version is displayed in the footer of the project’s documentation site.

![image](upgrade/version.png)

If your project theme’s version is <1.0, follow this guide to get the latest version.

## Upgrade to version 1.0

Here are the main breaking changes between the 0.x and 1.0 versions.

1. Set `sphinx-scylladb-theme` in `docs/pyproject.toml` to `sphinx-scylladb-theme = "~1.0.0"`.
2. Edit `conf.py`:
   > #### NOTE
   > Depending on your project configuration, you may find `conf.py` under `docs/source/conf.py` or `docs/conf.py`.

   > 1. Remove the option `header_links` from `html_theme_options`.
   > 2. If exists, remove the option `show_sidebar_index` from `html_theme_options`. If this option was set to `true`, set `"hide_sidebar_index": "false"`.
   > 3. If they exist, remove or comment out the following lines:
   >    > ```python
   >    > # Add ExpertRec Search
   >    > # html_js_files = ['expertrec.js']
   >    > ```
3. Edit `docs/Makefile`:
   > 1. Under the section `# Internal variables`, add the following line after the variable `ALLSPHINXOPTS`:
   >    > ```default
   >    > TESTSPHINXOPTS  = $(ALLSPHINXOPTS) -W --keep-going
   >    > ```
   > 2. Add the following lines at the end of the `Makefile`:
   >    > ```default
   >    > .PHONY: test
   >    > test: setup
   >    >     $(SPHINXBUILD) -b dirhtml $(TESTSPHINXOPTS) $(BUILDDIR)/dirhtml
   >    >     @echo
   >    >     @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
   >    > ```
4. Remove the file `.github/workflows/pages.yml`. Then, copy the new workflows in the `.github/workflows` folder. You can download the latest workflows [here](https://github.com/scylladb/sphinx-scylladb-theme/tree/master/.github/workflows).

To check if the upgrade completed successfully, run the command [make preview](https://sphinx-theme.scylladb.com/stable/commands.md). Then, check if the site footer displays version 1.0 or greater.

## Optional features

<a id="new-landing-page"></a>

### New landing page

With 1.0, you can add a custom landing page for your project using the new [topic box](https://sphinx-theme.scylladb.com/stable/examples/topic-box.md) components.
For example, check out [ScyllaDB Sphinx Theme](https://sphinx-theme.scylladb.com/stable/) landing page for inspiration.

To add a landing page to your project:

1. Create a new `docs/source/index.rst` file. Here you can find a [sample template](https://github.com/scylladb/sphinx-scylladb-theme/blob/master/docs/source/index.rst) ready to be adapted.
2. Set `"hide_sidebar_index": "false"` in `html_theme_options` (`conf.py`).

### New “Edit on GitHub” button

If your project is open-source, we invite you to enable the new “Edit on GitHub” option.
For more information, see [Template Options / Contribute button](https://sphinx-theme.scylladb.com/stable/configuration/template.md).