Customizing advertising

Warning

This document details features that are a work in progress. To discuss this document, please get in touch in the issue tracker.

In addition to allowing users and documentation authors to opt out of advertising, we allow some additional controls for documentation authors to control the positioning and styling of advertising. This can improve the performance of advertising or make sure the ad is in a place where it fits well with the documentation.

Controlling the placement of an ad

It is possible for a documentation author to instruct Read the Docs to position advertising in a specific location. This is done by adding a specific element to the generated body. The ad will be inserted into this container wherever this element is in the document body.

<div id="ethical-ad-placement"></div>

In Sphinx

In Sphinx, this is typically done by adding a new template (under templates_path) for inclusion in the HTML sidebar in your conf.py.

## In conf.py
html_sidebars = {
    "**": [
        "localtoc.html",
        "ethicalads.html",  # Put the ad below the navigation but above previous/next
        "relations.html",
        "sourcelink.html",
        "searchbox.html",
    ]
}

<!-- In _templates/ethicalads.html -->
<div id="ethical-ad-placement"></div>