# Configuration

A few configuration options for this theme

```{note}
This documentation and the examples below are written with MyST Markdown, a form
of markdown that works with Sphinx. For more information about MyST markdown, and
to use MyST markdown with your Sphinx website,
see [the MyST-parser documentation](https://myst-parser.readthedocs.io/)
```

## Disabling QuantEcon Official Components

If you are a project using this theme please use

```python
html_theme_options = {
    ...
    "quantecon_project": False,
    ...
}
```

as this will remove the QuantEcon logo from the top toolbar.

This will also override some colors styles for a slightly different look
for the theme.

## Source repository buttons

There are a collection of buttons that you can use to link back to your source
repository. This lets users browse the repository, or take actions like suggest
an edit or open an issue. In each case, they require the following configuration
to exist:

```python
html_theme_options = {
    ...
    "repository_url": "https://github.com/{your-docs-url}",
    ...
}
```

### Add a link to your repository

To add a link to your repository, add the following configuration:

```python
html_theme_options = {
    ...
    "repository_url": "https://github.com/{your-docs-url}",
    "use_repository_button": True,
    ...
}
```

### Add a button to open issues

To add a button to open an issue about the current page, use the following
configuration:

```python
html_theme_options = {
    ...
    "repository_url": "https://github.com/{your-docs-url}",
    "use_issues_button": True,
    ...
}
```

### Add a button to suggest edits

You can add a button to each page that will allow users to edit the page text
directly and submit a pull request to update the documentation. To include this
button, use the following configuration:

```python
html_theme_options = {
    ...
    "repository_url": "https://github.com/{your-docs-url}",
    "use_edit_page_button": True,
    ...
}
```

By default, the edit button will point to the `main` branch, but if you'd like
to change this, use the following configuration:

```python
html_theme_options = {
    ...
    "repository_branch": "{your-branch}",
    ...
}
```

By default, the edit button will point to the root of the repository. If your
documentation is hosted in a sub-folder, use the following configuration:

```python
html_theme_options = {
    ...
    "path_to_docs": "{path-relative-to-site-root}",
    ...
}
```

## Use a single-page version of this theme

If your documentation only has a single page, and you don't need the left
navigation bar, then you may configure `quantecon-book-theme` to run in **single page mode**
with the following configuration:

```python
html_theme_options = {
    ...
    "single_page": True
    ...
}
```

## Add authors to your documentation

If you'd like to add a list of authors to your documentation, you can do so with the following configuration:

```python
html_theme_options = {
    ...
    "authors": [
        {"name": "author1", "url": "bio-link1"},
        {"name": "author2", "url": "bio-link2"},
    ]
}
```

Authors with there bio links will be displayed just below the title of the page.

## Use plugins to add/extend features

If you want some extra features in your documentation website or modify an existing one, you can add a list of plugins
in javascript format, to suit your needs:

```python
html_theme_options = {
    ...
    "plugins_list": ["path-relative-to-config-file.js"]
    ...
}
```

## Add a dark mode version of your logo

To optimize your branding for dark mode, consider creating a dedicated dark mode variant of your logo.
Then, configure the theme settings to display this variant when dark mode is active, using the following configuration:

```python
html_theme_options = {
    ...
    "dark_logo": "name-of-dark-logo-image"
    ...
}
```

The image is expected to be in the `_static` folder of your source repository.

## Specifying the hosting location for Download Notebooks

While this location is auto-configured to be `/_notebooks/` (which works in most deployment cases) this option
enables you to specify a different location for more complex url structures such as those found when using
GitHub pages (without a custom URL)

```python
html_theme_options = {
    ...
    "download_nb_path" : https://{{ GitHub Account}}.github.io/{{ repo }}/
    ...
}
```

## Custom Code Syntax Highlighting

By default, the theme uses custom QuantEcon syntax highlighting colors for code blocks. If you'd prefer to use Pygments' built-in syntax highlighting styles instead, you can disable the custom code styling:

```python
# conf.py

# Set the Pygments style you want to use
pygments_style = 'friendly'  # or 'monokai', 'github-dark', 'default', etc.

html_theme_options = {
    ...
    "qetheme_code_style": False,
    ...
}
```

Available Pygments styles include: `default`, `friendly`, `monokai`, `github-dark`, `github-light`, `tango`, `vim`, and many others. See the [Pygments documentation](https://pygments.org/styles/) for a full list.

When `qetheme_code_style` is `True` (the default), the custom QuantEcon code highlighting is used and the `pygments_style` setting is ignored. When set to `False`, the theme will respect your `pygments_style` configuration.

## Sticky Table of Contents

The theme supports a sticky right-hand-side table of contents (TOC) that remains visible as you scroll through the page. This feature includes scroll spy functionality to highlight the currently visible section, and optional auto-expansion of subsections.

### Enabling Sticky TOC

To enable the sticky table of contents:

```python
html_theme_options = {
    ...
    "sticky_contents": True,
    ...
}
```

For Jupyter Book projects, add to your `_config.yml`:

```yaml
sphinx:
  config:
    html_theme_options:
      sticky_contents: true
```

### Features

When enabled, the sticky TOC provides:

- **Fixed positioning**: The TOC stays visible as you scroll
- **Active section highlighting**: The currently visible section is highlighted in the TOC
- **Copy section link**: Hover over any TOC entry to reveal a copy icon — click it to copy the full URL with anchor to your clipboard for easy sharing
- **Back to top button**: A discrete "Back to top" button appears after scrolling down 300px
- **Auto-expand subsections**: Subsections automatically expand to show the current hierarchy

### Auto-Expand Subsections

By default, subsections in the TOC automatically expand as you scroll to show the current section hierarchy. This makes it easier to navigate deeply nested content.

To disable auto-expansion while keeping the sticky TOC:

```python
html_theme_options = {
    ...
    "sticky_contents": True,
    "contents_autoexpand": False,
    ...
}
```

When `contents_autoexpand` is `True` (the default when sticky TOC is enabled), the TOC will:
- Highlight the active section with bold text (scroll tracking)
- Expand parent sections to show the active item
- Expand the active item itself to show its subsections
- Collapse unrelated sections to reduce visual clutter

When set to `False`, only top-level section names are displayed with bold highlighting to indicate which section the reader is currently in. This provides a cleaner, more compact TOC view while still tracking scroll position.

## Git-Based Metadata

The theme automatically displays git-based metadata for each page, including the last modified timestamp and an interactive changelog dropdown. This feature requires:

1. Your documentation source files to be tracked in a git repository
2. A configured `repository_url` in your theme options

### Automatic Features

When available, the theme displays:

- **Last modified timestamp**: Shows when the current file was last changed in git
- **Changelog dropdown**: Interactive button showing the last 10 commits affecting the current file
- **Clickable commit hashes**: Each commit hash links directly to the GitHub commit page
- **Full history link**: Links to the complete commit history for the file on GitHub

### Configuration Options

You can customize the git metadata display in your `conf.py`:

```python
html_theme_options = {
    ...
    "repository_url": "https://github.com/{your-org}/{your-repo}",
    "repository_branch": "main",  # default: "main"
    "path_to_docs": "docs",  # if your docs are in a subfolder

    # Git metadata customization
    "last_modified_date_format": "%b %d, %Y",  # default: "%b %d, %Y"
    "changelog_max_entries": 10,  # default: 10
    ...
}
```

For Jupyter Book projects, add to your `_config.yml`:

```yaml
sphinx:
  config:
    html_theme_options:
      repository_url: "https://github.com/{your-org}/{your-repo}"
      repository_branch: "main"
      path_to_docs: "docs"
      last_modified_date_format: "%b %d, %Y"
      changelog_max_entries: 10
```

### Date Format Options

The `last_modified_date_format` option accepts Python `strftime` format codes:

- `%b %d, %Y` → "Nov 22, 2025" (default)
- `%Y-%m-%d` → "2025-11-22"
- `%B %d, %Y` → "November 22, 2025"
- `%m/%d/%Y` → "11/22/2025"

See the [Python strftime documentation](https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes) for all format codes.

### Disabling Git Metadata

The git metadata features are automatically disabled if:
- The source file is not tracked in a git repository
- The `repository_url` is not configured
- The git commands fail or timeout

No additional configuration is needed to handle these cases.

## Customizing Toggle Button Text

The theme supports collapsible content via the `sphinx-togglebutton` extension, which provides two mechanisms for creating expandable sections:

1. **Toggle directives** - Created with `` ```{toggle} `` syntax
2. **Dropdown admonitions** - Created by adding `:class: dropdown` to admonitions

### Customizing Toggle Directive Text

To customize the button text for toggle directives, add the following to your Sphinx configuration:

```python
# conf.py

# Customize toggle button text
togglebutton_hint = "Show"
togglebutton_hint_hide = "Hide"
```

For Jupyter Book projects, add to your `_config.yml`:

```yaml
# _config.yml

sphinx:
  config:
    togglebutton_hint: "Show"
    togglebutton_hint_hide: "Hide"
```

### Dropdown Admonitions

The theme automatically customizes dropdown admonitions (those with `:class: dropdown`) to display "Show"/"Hide" instead of the default "Click to show"/"Click to hide". This styling is built into the theme and requires no additional configuration.

**Example usage:**

````markdown
```{note}
:class: dropdown

This is a collapsible note that will show "Show" when collapsed and "Hide" when expanded.
```

```{toggle}
This is a toggle directive that will use the configured button text.
```
````
which renders:

```{note}
:class: dropdown

This is a collapsible note that will show "Show" when collapsed and "Hide" when expanded.
```

```{toggle}
This is a toggle directive that will use the configured button text.
```

## Text Color Scheme

The theme applies colors to emphasis (italic), bold/strong, and definition list terms
using a built-in color scheme system inspired by [Seoul256](https://github.com/junegunn/seoul256.vim).

### Built-in Schemes

| Scheme | Description |
|---|---|
| `seoul256` (default) | Dark teal (`#005f5f`) for emphasis, dark amber (`#875f00`) for strong — with matching light variants for dark mode |
| `gruvbox` | Earthy aqua (`#427b58`) for emphasis, warm orange (`#af3a03`) for strong — with light variants for dark mode |
| `none` | Restores standard typography — italic for `em`, bold for `strong`, no color |

### Selecting a Scheme

In `conf.py`:

```python
html_theme_options = {
    ...
    "color_scheme": "seoul256",  # or "gruvbox" or "none"
    ...
}
```

For Jupyter Book projects, add to your `_config.yml`:

```yaml
sphinx:
  config:
    html_theme_options:
      color_scheme: "seoul256"
```

### Seoul256 Scheme Colors

| Element | Light Mode | Dark Mode |
|---|---|---|
| **Emphasis** (`em`) | `#005f5f` dark teal | `#5fafaf` medium-light teal |
| **Bold/Strong** (`strong`, `b`) | `#875f00` dark amber | `#d7af5f` light amber-gold |
| **Definitions** (`dl dt`) | Inherits from bold/strong | Inherits from bold/strong |

```css
/* Seoul256 — Light Mode */
em       { color: #005f5f; }  /* dark teal */
strong   { color: #875f00; }  /* dark amber */
dl dt    { color: #875f00; }  /* inherits from strong */

/* Seoul256 — Dark Mode */
em       { color: #5fafaf; }  /* medium-light teal */
strong   { color: #d7af5f; }  /* light amber-gold */
dl dt    { color: #d7af5f; }  /* inherits from strong */
```

### Gruvbox Scheme Colors

| Element | Light Mode | Dark Mode |
|---|---|---|
| **Emphasis** (`em`) | `#427b58` earthy aqua | `#8ec07c` light aqua |
| **Bold/Strong** (`strong`, `b`) | `#af3a03` warm orange | `#fe8019` bright orange |
| **Definitions** (`dl dt`) | Inherits from bold/strong | Inherits from bold/strong |

```css
/* Gruvbox — Light Mode */
em       { color: #427b58; }  /* earthy aqua */
strong   { color: #af3a03; }  /* warm orange */
dl dt    { color: #af3a03; }  /* inherits from strong */

/* Gruvbox — Dark Mode */
em       { color: #8ec07c; }  /* light aqua */
strong   { color: #fe8019; }  /* bright orange */
dl dt    { color: #fe8019; }  /* inherits from strong */
```

### Custom Color Scheme

To define your own text colors, place a `custom_color_scheme.css` file
in your project's `_static/` directory. The theme will automatically detect and
include it. Define any combination of these CSS custom properties:

```css
/* _static/custom_color_scheme.css */
:root {
  --qe-emphasis-color: #005f5f;
  --qe-strong-color: #875f00;
  --qe-definition-color: #875f00;
}
body.dark-theme {
  --qe-emphasis-color: #5fafaf;
  --qe-strong-color: #d7af5f;
  --qe-definition-color: #d7af5f;
}
```

```{note}
The `color_scheme` option is validated at build time. Invalid scheme names
fall back to `seoul256` with a warning. When using a `custom_color_scheme.css`
file, the base scheme still applies — your CSS overrides take precedence.
```
