manual_teachbooks/book/features/apa.md

```{admonition} User types
:class: tip
This page is useful for user type 4 and 5.
```

{bdg-primary}`(To be converted into) Sphinx Extension`
{bdg-link-secondary}`Supported by TeachBooks package <./teachbooks_intro.html>`

(apa)=

APA References

This feature is stable but because it relies on a local extension that is part of your book files and _not_ managed as part of a computing environment (e.g., `pip` or `conda`), unknown issues may arise. We would like to convert this feature into an independent Sphinx extension and/or Pybtext plugin. Visit the README in the [project page on GitHub](https://github.com/orgs/TeachBooks/projects/17?pane=info) to learn more.

The instructions provided here will work under conventional usage with TeachBooks and Jupyter Book v1 (e.g., `jupyter book build book`).

A temporary fix has also been implemented in the TeachBooks package for use with the Deploy Book Workflow (release mode) (see [release notes from v0.1.0](https://github.com/TeachBooks/TeachBooks/releases/tag/v0.1.0)).

_Update, October 21, 2025:_ a new fix was necessitated due to dependency issues with docutils making it no longer necessary to pin this package. See [PR 207 of the Manual for a description](https://github.com/TeachBooks/manual/pull/207).

Introduction

Do you include references in your book, but you're tired of the default options available in a TeachBook / Jupyter Book v1? For example, the square-bracket style of citation and reference, where the first three letters of the name year are combined in a way that seems designed to minimize transparency?

There is a solution! This extension allows you to have APA formatting in your book.

Installation

To use APA-references, a set of Python files need to be manually loaded into your book.

Step 1: files to root directory of your book

Download this zip-file apa_config.zip, which contains the necessary files, located in two subdirectories: _ext and _static. Unzip and place the contents in the root of your book directory so that it looks like the schematic here:

book
├── _ext/
│   ├── pybtexapastyle/
│   ├── apastyle.py
│   └── bracket_citation_style.py
├── _static/
|   ├── ...
│   └── apastyle.css
├── _config.yml
├── _toc.yml
├── requirements.txt
├── <book files>

Note that you may or may not already have a _static subdirectory, to which the file apastyle.css should be added.

Step 2: Enable in _config.yml

In your _config.yml file, add a bibtex_default_style, bybtex_reference_style and the local extensions apastyle and bracket_citation_style.py. This enables the (local) extension.

sphinx:
  config:
    ...
    bibtex_default_style: myapastyle
    bibtex_reference_style: author_year_round
  local_extensions:
    apastyle: _ext/
    bracket_citation_style: _ext/
  ...

Usage

All references are now made in APA-style. See for example this reference: {cite:t}jason_moore which shows up on the references page too. The form of the citation looks like this:

{cite:t}`jason_moore`

Here are three examples for making citations:

Syntax	Result
{cite:t}	{cite:t}jason_moore
{cite:p}	{cite:p}jason_moore
{cite}	{cite}jason_moore

For more options on the in-line citation style, see https://jupyterbook.org/v1/content/citations.html#change-the-in-line-citation-style.

Known Issues

Two issues are known:

• During the build, warning will be raised with ... WARNING: duplicate label for keys .... In most cases, these warnings can be ignored. As noted above, the book will not build references properly
• In case you have both an .ipynb and .md version of a file, the .md version will always be used whenever this extension is used. This removes the possibility to show code outputs.

Implementation

The extension is based on pybtex, which is a BibTeX-compatible bibliography processor in Python that is extendible with plugins.

Although some customization is possible with the standard Jupyter Book v1 features, as described here, this extension implements the complete APA style, as well as enforcing round brackets (like this).

The need to include a CSS file is an easy solution to the issue where empty brackets [] are left on the references page (to try it, simply delete apastyle.css).

Contribute

This tool needs to be developed further to make it into a proper sphinx-extension (and/or an independent pybtext plugin). The process is described in the README of this project page on GitHub. If you've ideas or questions, please reach out to us at info@teachbooks.io!