starred/netbox
1
0
Fork 0
mirror of https://github.com/netbox-community/netbox.git synced 2026-01-11 21:10:29 +01:00
Code Issues 273 Packages Projects Releases 10 Wiki Activity

Inconsistent relative paths in doc includes #5306

New Issue
Closed
opened 2025-12-29 19:26:28 +01:00 by adam · 2 comments
adam commented 2025-12-29 19:26:28 +01:00
Owner
Copy Link

Originally created by @m2martin on GitHub (Sep 2, 2021).

Originally assigned to: @jeremystretch on GitHub.

NetBox version

v3.0.1

Python version

3.9

Steps to Reproduce

  1. Open static docs from your installation
  2. Navigate to 'Core Functionality' -> 'Devices and Cabling'
  3. Click on 'NAPALM' link in section 'Platforms'

Expected Behavior

Direct link to page 'Additional Features' -> 'NAPALM'

Observed Behavior

HTTP 404 because it is linked to /static/docs/additional-features/napalm.md instead of /static/docs/additional-features/napalm/.

Originally created by @m2martin on GitHub (Sep 2, 2021). Originally assigned to: @jeremystretch on GitHub. ### NetBox version v3.0.1 ### Python version 3.9 ### Steps to Reproduce 1. Open static docs from your installation 2. Navigate to 'Core Functionality' -> 'Devices and Cabling' 3. Click on 'NAPALM' link in section 'Platforms' ### Expected Behavior Direct link to page 'Additional Features' -> 'NAPALM' ### Observed Behavior HTTP 404 because it is linked to `/static/docs/additional-features/napalm.md` instead of `/static/docs/additional-features/napalm/`.
adam added the status: acceptedtype: documentation labels 2025-12-29 19:26:28 +01:00
adam closed this issue 2025-12-29 19:26:28 +01:00
adam commented 2025-12-29 19:26:28 +01:00
Author
Owner
Copy Link

@m2martin commented on GitHub (Sep 2, 2021):

The path depth seems to be the problem. Because the .md file was not found while compiling, Mkdocs simply uses the relative link.

On mkdocs build you'll hit the warning:

WARNING - Documentation file 'core-functionality/devices.md' contains a link to '../additional-features/napalm.md' which is not found in the documentation files.

To clarify:

  • docs/core-functionality/devices.md includes docs/models/dcim/platform.md
  • docs/models/dcim/platform.md refers to ../../additional-features/napalm.md

In this case the relative target in docs/models/dcim/platform.md is not valid because it is scoped on docs/core-functionality/devices.md (path depth +1) by markdown-include.

I could not find any config flag which could be used to change the scope to the child document.

Changing docs/models/dcim/platform.md
from ../../additional-features/napalm.md to ../additional-features/napalm.md solves the problem but also breaks links if the document is included elsewhere.

Btw. the same may apply to the following warnings:

WARNING  -  Documentation file 'core-functionality/devices.md' contains a link to '../additional-features/napalm.md' which is not found in the documentation files.
WARNING  -  Documentation file 'core-functionality/devices.md' contains a link to '../media/models/dcim_cable_trace.png' which is not found in the documentation files.
WARNING  -  Documentation file 'core-functionality/power.md' contains a link to '../media/power_distribution.png' which is not found in the documentation files.
WARNING  -  Documentation file 'customization/custom-scripts.md' contains a link to '../media/admin_ui_run_permission.png' which is not found in the documentation files.
WARNING  -  Documentation file 'customization/reports.md' contains a link to '../media/admin_ui_run_permission.png' which is not found in the documentation files.
@m2martin commented on GitHub (Sep 2, 2021): The path depth seems to be the problem. Because the `.md` file was not found while compiling, Mkdocs simply uses the relative link. On `mkdocs build` you'll hit the warning: `WARNING - Documentation file 'core-functionality/devices.md' contains a link to '../additional-features/napalm.md' which is not found in the documentation files.` To clarify: - `docs/core-functionality/devices.md` includes `docs/models/dcim/platform.md` - `docs/models/dcim/platform.md` refers to `../../additional-features/napalm.md` In this case the relative target in `docs/models/dcim/platform.md` is not valid because it is scoped on `docs/core-functionality/devices.md` (path depth +1) by `markdown-include`. I could not find any config flag which could be used to change the scope to the child document. Changing `docs/models/dcim/platform.md` from `../../additional-features/napalm.md` to `../additional-features/napalm.md` solves the problem but also breaks links if the document is included elsewhere. Btw. the same may apply to the following warnings: ``` WARNING - Documentation file 'core-functionality/devices.md' contains a link to '../additional-features/napalm.md' which is not found in the documentation files. WARNING - Documentation file 'core-functionality/devices.md' contains a link to '../media/models/dcim_cable_trace.png' which is not found in the documentation files. WARNING - Documentation file 'core-functionality/power.md' contains a link to '../media/power_distribution.png' which is not found in the documentation files. WARNING - Documentation file 'customization/custom-scripts.md' contains a link to '../media/admin_ui_run_permission.png' which is not found in the documentation files. WARNING - Documentation file 'customization/reports.md' contains a link to '../media/admin_ui_run_permission.png' which is not found in the documentation files. ```
adam commented 2025-12-29 19:26:29 +01:00
Author
Owner
Copy Link

@jeremystretch commented on GitHub (Sep 2, 2021):

Yeah, this one is tricky. I haven't found a good solution for this problem generally. I think for now it's reasonable to just omit the hyperlink. Thanks for the report!

@jeremystretch commented on GitHub (Sep 2, 2021): Yeah, this one is tricky. I haven't found a good solution for this problem generally. I think for now it's reasonable to just omit the hyperlink. Thanks for the report!
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
beta
breaking change
complexity: high
complexity: low
complexity: medium
needs milestone
netbox
pending closure
plugin candidate
pull-request
Mirrored from GitHub Pull Request
 severity: high
severity: low
severity: medium
status: accepted
status: backlog
status: blocked
status: duplicate
status: needs owner
status: needs triage
status: revisions needed
status: under review
topic: GraphQL
topic: Internationalization
topic: OpenAPI
topic: UI/UX
topic: cabling
topic: event rules
topic: htmx navigation
topic: industrialization
topic: migrations
topic: plugins
topic: scripts
topic: templating
topic: testing
type: bug
type: deprecation
type: documentation
type: feature
type: housekeeping
type: translation
No Label status: accepted type: documentation
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
adam
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: starred/netbox#5306
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?