jenkins.io
jenkins.io copied to clipboard
jenkins-infra
Use same navigation for dev docs as for user handbook
Use same navigation for dev docs as for user handbook
The user handbook on www.jenkins.io includes
- left side navigation list that expands and collapses as the user moves from one page to another
- current page is highlighted in bold text to show the user context
- links to the subsections of the page in the upper right corner, usable as external xrefs
- breadcrumbs at the top of the page for navigation from page to page and to the index
The developer documentation uses a simple list without expand and collapse and without any of the navigation improvements.
Make the developer documentation navigation use the same navigation assistance as the user handbook.
This is a more involved issue report because it requires changes to the templates that define the developer doc pages so that they will be more like the user handbook pages.
This will likely require multiple pull requests before it is fully resolved.
That would be great @krisstern . Let me know if you need help. I'll assign the issue to you. Also let me know if you reach a point where you're not able to proceed and we'll unassign it.
Thanks so much @MarkEWaite! Sure, I would like a very very brief overview of the architecture of the dev docs, to save me some time prepping for the pull requests. Do you happened to have any info on this?
Also, by dev docs you meant this?: https://www.jenkins.io/doc/developer/
That's correct.
The user handbook has a menu structure that expands, contracts, and highlights the current entry. When I open the installing Linux page, the left side expands the "installing" section and emphasizes the "Linux" entry in that section.
The developer handbook has several different top level entries, including "How-To Guides", "Improve a plugin tutorial", developer reference, and extensions index.
The "How-to Guides", "Improve a plugin tutorial", and developer reference each open to the same left side panel, but do not expand or contract.
Cool, now I see what I will need to do clearly. Let me start work on this issue soon!
Hi @MarkEWaite I am wondering what is the most efficient way to test out changes in the codebase for the dev docs?
For development purposes, I build the site locally @krisstern using the instructions in the CONTRIBUTING document. I typically start my text editor and invoke a make run in a terminal window of the text editor, open the pages I'm modifying in a web browser to http://localhost:4242/ and then make the changes. The changes are usually detected automatically and rebuilt by the make run. Sometimes I need to stop the make run and call it again.
Thanks @MarkEWaite! That's what I have tried as well. Appreciate the details.
Just come up with this, however since I am not yet very familiar with the code base the anchor href are currently hardcoded and not fetched by code iteratively:
