Use environment variable to control indexing of rendered docs #9455

New Issue

adam · 2025-12-29T20:50:07+01:00

adam commented

2025-12-29 20:50:07 +01:00

Originally created by @jeremystretch on GitHub (Apr 8, 2024).

Originally assigned to: @jeremystretch on GitHub.

Proposed Changes

When the NetBox documentation is rendered using mkdocs, we ensure that indexing by search engines is disabled unless it has been built for ReadTheDocs. This is done to avoid search engines accidentally caching the local documentation served by publicly-exposed NetBox deployments in the wild, which taints search results.

This is currently accomplished by checking that the page.canonical_url context variable is set to docs.netbox.dev:

b7668fbfc3/docs/_theme/main.html (L6-L8)

This approach is taken because ReadTheDocs currently does not support the use of environment variables within mkdocs configuration files. However, per this recent blog post, support for referencing environment variables will be introduced on April 15. (See also this comment.)

I've opened this issue to track the switch to using an environment variable instead of the context variable (essentially reverting efd86526f41ca6e4c4eba44fd508ca96811ef496).

Justification

The environment approach is more flexible as it more customizable and does not rely on an exact string match.

Originally created by @jeremystretch on GitHub (Apr 8, 2024). Originally assigned to: @jeremystretch on GitHub. ### Proposed Changes When the NetBox documentation is rendered using `mkdocs`, we ensure that indexing by search engines is disabled unless it has been built for ReadTheDocs. This is done to avoid search engines accidentally caching the local documentation served by publicly-exposed NetBox deployments in the wild, which taints search results. This is currently accomplished by checking that the `page.canonical_url` context variable is set to `docs.netbox.dev`: https://github.com/netbox-community/netbox/blob/b7668fbfc3a81abf2c6a8ace98047647fd9244c9/docs/_theme/main.html#L6-L8 This approach is taken because ReadTheDocs currently does not support the use of environment variables within `mkdocs` configuration files. However, per [this recent blog post](https://about.readthedocs.com/blog/2024/03/mkdocs-yaml-manipulation/), support for referencing environment variables will be introduced on April 15. (See also [this comment](https://github.com/readthedocs/readthedocs.org/issues/8529#issuecomment-2042328766).) I've opened this issue to track the switch to using an environment variable instead of the context variable (essentially reverting efd86526f41ca6e4c4eba44fd508ca96811ef496). ### Justification The environment approach is more flexible as it more customizable and does not rely on an exact string match.

adam added the status: accepted type: housekeeping labels 2025-12-29 20:50:07 +01:00

adam closed this issue

2025-12-29 20:50:07 +01:00

Sign in to join this conversation.

Branches Tags

main

21102-fix-graphiql-explorer

update-changelog-comments-docs

20911-dropdown

20239-plugin-menu-classes-mutable-state

21097-graphql-id-lookups

feature

fix_module_substitution

20923-dcim-templates

20044-elevation-stuck-lightmode

feature-ip-prefix-link

v4.5-beta1-release

20068-import-moduletype-attrs

20766-fix-german-translation-code-literals

20378-del-script

7604-filter-modifiers-v3

circuit-swap

12318-case-insensitive-uniqueness

20637-improve-device-q-filter

20660-script-load

19724-graphql

20614-update-ruff

14884-script

02496-max-page

19720-macaddress-interface-generic-relation

19408-circuit-terminations-export-templates

20203-openapi-check

fix-19669-api-image-download

7604-filter-modifiers

19275-fixes-interface-bulk-edit

fix-17794-get_field_value_return_list

11507-show-aggregate-and-rir-on-api

9583-add_column_specific_search_field_to_tables

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: starred/netbox#9455