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

Standardise documentation links to ensure they work across local and production environments #4395

New Issue
Closed
opened 2025-12-29 18:35:33 +01:00 by adam · 5 comments
adam commented 2025-12-29 18:35:33 +01:00
Owner
Copy Link

Originally created by @marcus-crane on GitHub (Dec 22, 2020).

Originally assigned to: @marcus-crane on GitHub.

Change Type

[ ] Addition
[ ] Correction
[ ] Deprecation
[x] Cleanup (formatting, typos, etc.)

Area

[x] Installation instructions
[x] Configuration parameters
[x] Functionality/features
[x] REST API
[x] Administration/development
[x] Other

Proposed Changes

tl;dr Change all links to follow the [Document title](../category/name.md#ref) format for ease of development

I've noticed a couple of broken links in the production version of the Netbox documentation that work fine locally.

The links in question use the /category/blah style of URL which works fine locally but doesn't work in production as this type of link translates into netbox.readthedocs.io/category/blah which invalid because the documentation lives under netbox.readthedocs.io/en/stable/category.blah

Similarly, most every working link is formatted as ../../category/blah which works fine locally and in production but has no correlation to the folder structure on disc, adding a bit of overhead when juggling between the disk layout and the deploy layout

I notice that mkdocs will transform a filesystem link (ie ../configuration/index.md#blah) into a proper URL (ie ../../configuration/) and seems like the best of both worlds. You only have to think about the folder structure on disc and it has the added benefit of being a valid link locally so you can traverse through the documentation while using markdown preview built into text editors or a dedicated markdown previewer such as MacDown

I've gone through the documentation locally and made these changes but as this would be my first pull request on behalf of my employer (Daimler / Mercedes-Benz Trucks), I've still yet to gain access to our Github org which is a blocker for my contributing a PR. For now, I'll just post a proposal anyway to see if it's accepted 🙂

Marcus Crane, marcus.crane@daimler.com, Mercedes-Benz New Zealand Ltd on behalf of Daimler Truck AG on behalf of Daimler TSS (Imprint)

Originally created by @marcus-crane on GitHub (Dec 22, 2020). Originally assigned to: @marcus-crane on GitHub. ### Change Type [ ] Addition [ ] Correction [ ] Deprecation [x] Cleanup (formatting, typos, etc.) ### Area [x] Installation instructions [x] Configuration parameters [x] Functionality/features [x] REST API [x] Administration/development [x] Other ### Proposed Changes tl;dr Change all links to follow the `[Document title](../category/name.md#ref)` format for ease of development I've noticed a couple of broken links in the production version of the Netbox documentation that work fine locally. The links in question use the `/category/blah` style of URL which works fine locally but doesn't work in production as this type of link translates into `netbox.readthedocs.io/category/blah` which invalid because the documentation lives under `netbox.readthedocs.io/en/stable/category.blah` Similarly, most every working link is formatted as `../../category/blah` which works fine locally and in production but has no correlation to the folder structure on disc, adding a bit of overhead when juggling between the disk layout and the deploy layout I notice that `mkdocs` will transform a filesystem link (ie `../configuration/index.md#blah`) into a proper URL (ie `../../configuration/`) and seems like the best of both worlds. You only have to think about the folder structure on disc and it has the added benefit of being a valid link locally so you can traverse through the documentation while using markdown preview built into text editors or a dedicated markdown previewer such as MacDown I've gone through the documentation locally and made these changes but as this would be my first pull request on behalf of my employer (Daimler / Mercedes-Benz Trucks), I've still yet to gain access to our Github org which is a blocker for my contributing a PR. For now, I'll just post a proposal anyway to see if it's accepted 🙂 <sup>Marcus Crane, marcus.crane@daimler.com, Mercedes-Benz New Zealand Ltd on behalf of Daimler Truck AG on behalf of Daimler TSS ([Imprint](https://github.com/Daimler/daimler-foss/blob/master/LEGAL_IMPRINT.md))</sup>
adam added the status: acceptedtype: documentation labels 2025-12-29 18:35:33 +01:00
adam closed this issue 2025-12-29 18:35:33 +01:00
adam commented 2025-12-29 18:35:34 +01:00
Author
Owner
Copy Link

@DanSheps commented on GitHub (Jan 5, 2021):

Just a note, you can do the PR under your personal account.

I am not sure how this would affect our readthedocs build yet.

@DanSheps commented on GitHub (Jan 5, 2021): Just a note, you can do the PR under your personal account. I am not sure how this would affect our readthedocs build yet.
adam commented 2025-12-29 18:35:34 +01:00
Author
Owner
Copy Link

@marcus-crane commented on GitHub (Jan 10, 2021):

@DanSheps Heya, normally I'd just use my personal account but it's part of the contributing guidelines we have internally that we first fork to the Daimler Github org and then file a pull request from there.

I think there are a few instances already of documentation links following the ../category/document.md style so I'd expect them to work as expected in production without any changes to the current readthedocs configuration.

I can file a PR for review once/if this is marked as accepted given the contribution guidelines say that any PRs before then will be rejected 🙂

Given that, you can feel free to assign this issue to me as well.

Marcus Crane, marcus.crane@daimler.com, Mercedes-Benz New Zealand Ltd on behalf of Daimler Truck AG on behalf of Daimler TSS (Imprint)

@marcus-crane commented on GitHub (Jan 10, 2021): @DanSheps Heya, normally I'd just use my personal account but it's part of the contributing guidelines we have internally that we first fork to the Daimler Github org and then file a pull request from there. I think there are a few instances already of documentation links following the `../category/document.md` style so I'd expect them to work as expected in production without any changes to the current readthedocs configuration. I can file a PR for review once/if this is marked as accepted given the contribution guidelines say that any PRs before then will be rejected 🙂 Given that, you can feel free to assign this issue to me as well. <sup>Marcus Crane, marcus.crane@daimler.com, Mercedes-Benz New Zealand Ltd on behalf of Daimler Truck AG on behalf of Daimler TSS ([Imprint](https://github.com/Daimler/daimler-foss/blob/master/LEGAL_IMPRINT.md))</sup>
adam commented 2025-12-29 18:35:34 +01:00
Author
Owner
Copy Link

@marcus-crane commented on GitHub (Jan 19, 2021):

Heya,

Just following up on this issue as I'm not able to contribute my documentation changes without this issue being marked as accepted.

For what it's worth, there are a few broken links in the current live documentation site such as Development -> Getting Started which I personally fumbled with while trying to set up Netbox and write a plugin. I'm hoping I can fix these for other users going forward.

Regarding the understandable concern about how this would work with the Read The Docs build, you're already using some of the relative links I described in production right now. Here is an example which you can see with the "Installation docs" link.

Let me know if you need anything else from my end, or if there are any other considerations to take into account.

Thanks!

Marcus Crane, marcus.crane@daimler.com, Mercedes-Benz New Zealand Ltd on behalf of Daimler Truck AG on behalf of Daimler TSS (Imprint)

@marcus-crane commented on GitHub (Jan 19, 2021): Heya, Just following up on this issue as I'm not able to contribute my documentation changes without this issue being marked as accepted. For what it's worth, there are a few broken links in the current live documentation site such as [Development -> Getting Started](https://netbox.readthedocs.io/en/stable/development/getting-started/) which I personally fumbled with while trying to set up Netbox and write a plugin. I'm hoping I can fix these for other users going forward. Regarding the understandable concern about how this would work with the Read The Docs build, you're already using some of the relative links I described in production right now. [Here](https://github.com/netbox-community/netbox/blob/develop/docs/administration/replicating-netbox.md) is an example which you can see with the "Installation docs" link. Let me know if you need anything else from my end, or if there are any other considerations to take into account. Thanks! <sup>Marcus Crane, marcus.crane@daimler.com, Mercedes-Benz New Zealand Ltd on behalf of Daimler Truck AG on behalf of Daimler TSS ([Imprint](https://github.com/Daimler/daimler-foss/blob/master/LEGAL_IMPRINT.md))</sup>
adam commented 2025-12-29 18:35:35 +01:00
Author
Owner
Copy Link

@marcus-crane commented on GitHub (Mar 14, 2021):

Hi there,

I just wanted to know if this was still under review?

The links mentioned are still broken in your production documentation but if there's no interest, I'm happy to close this issue.

I've had a branch with the changes sitting on my hard drive since December so I'm happy to own this issue but I can't submit a PR until this issue is reviewed as was requested in the Netbox contributor guidelines

Kind Regards 😊

Marcus Crane, marcus.crane@daimler.com, Mercedes-Benz New Zealand Ltd on behalf of Daimler Truck AG on behalf of Daimler TSS (Imprint)

@marcus-crane commented on GitHub (Mar 14, 2021): Hi there, I just wanted to know if this was still under review? The links mentioned are still broken in your production documentation but if there's no interest, I'm happy to close this issue. I've had a branch with the changes sitting on my hard drive since December so I'm happy to own this issue but I can't submit a PR until this issue is reviewed as was requested in the Netbox contributor guidelines Kind Regards 😊 <sup>Marcus Crane, marcus.crane@daimler.com, Mercedes-Benz New Zealand Ltd on behalf of Daimler Truck AG on behalf of Daimler TSS ([Imprint](https://github.com/Daimler/daimler-foss/blob/master/LEGAL_IMPRINT.md))</sup>
adam commented 2025-12-29 18:35:35 +01:00
Author
Owner
Copy Link

@DanSheps commented on GitHub (Mar 15, 2021):

Sorry, you can go ahead and submit the PR.

@DanSheps commented on GitHub (Mar 15, 2021): Sorry, you can go ahead and submit the PR.
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#4395
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?