Header links to highlight the sidebar ToC

[2colours]

This is mostly a TODO for myself to test this idea.

If the sidebar is closed, probably nothing spectacular should happen.

If it's open, it needs to be scrolled into vision, help material: https://www.geeksforgeeks.org/how-to-scroll-to-specific-element-using-jquery/ or https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoView (the latter I've already tried, it can do the right thing, although without animation - but that may be a pro in this situation)

The rest of the challenge is really just to "connect" two elements (the header and the ToC) but that seems pretty easy even if there is no HTML (related material - https://www.geeksforgeeks.org/how-to-affect-other-elements-when-one-element-is-hovered-in-css/).

[2colours]

@finanalyst could you give me some pointers how the POD header tags are gathered into the ToC and their corresponding HTML hN-tags get their id?

[finanalyst]

@2colours a) look at the 'toc' template in Website/plugins/ogdenwebb/replacements works. You probably only need to modify the template that renders the toc structure for each file when it is rendered into a web page.

In more detail. When each source file is rendered, the header block handler in ProcessedPod registers the header, and gives it an id. This data structure is saved for each file in an instance of PodFile. A hash of podfiles can be accessed from the instance of ProcessedPod that is given to each render and compilation callable. The compilation callables are called by Collection after all the source files have been rendered. So all the data collected during the source rendering stage can be accessed from the $pp variable (the first paramater in the signature of a compilation callable). The .podf is a hash with the name of the file as the key, and a pod-file instance as the value.

Hope this helps

[2colours]

@finanalyst thank you for the response.

The 'toc' template probably isn't enough because I want to modify behavior on the side of the headers (highlight the corresponding link) so here the logic would be the other way around, compared to the link.

If I understand it correctly, ProcessedPod is a part of the https://github.com/finanalyst/raku-pod-render stack and that's where I should be looking for the generation of site content, including the headers that need to be altered. Is that correct?

I'll try to get this done by the end of the week, work and other Raku topics made me a bit overwhelmed.

[finanalyst]

@2colours a) If you want to change the header, then look at the header template. This is more complex. More below b) ProcessedPod is part of raku-pod-render. There is a lot of documentation there, including documentation on RakuClosureTemplates. You can ignore the Highlighting role, which has been completely eliminated for doc-website because the functionality is in the Website/templates/02-highlighting.raku.

I really want feedback on raku-pod-render. I think it can be refactored considerably in due course.

But to solve the task you have set, I do not think you need to go back to ProcessedPod, except to understand may be the structure of the toc data structure, maybe.

So why is Header complex?

1) In order to generate secondary files (eg. routine/say, which is complied from several source files), all headers have to be parsed before they are rendered. Once the infromation is collected, the header needs to be rendered. 2) So two plugins provide templates for headings: ogdenwebb and secondaries. secondaries is called after ogdenwebb, so its header template is the first in a linked list of templates of the same name. It then calls the prior method on the template structure, which contains the tempate for heading provided by ogdenwebb.

This is the template that I think you will also need to look at.

When ProcessedPod handles a Pod::Block::Heading (corresponding to =head1 (eq 1), it looks for the first template called heading provided to it. In addition, it registers the heading and gets it a unique id. The id is also provided to the template. If there is config data with the same name as the heading, then that data is also provided to the template.

In order to create a final rendered html file, the template source-wrap is called, which is where the toc structure is rendered according to the toc template.

So the heading template handles the anchor part, and the toc handles the part that goes in the sidebar.

[2colours]

Okay... so I made some progress which I will upload as a draft PR shortly.

I still think that this could look okay - for now, my main problem is the collision of the side bar and the upper menu bar. They are both fixed however the menu bar covers the side bar, meaning that the browser has a misconception about what is the visible top of the side bar, which causes problems at calling scrollIntoView.

Curious about opinions whether it's worth progressing with it - not because it's so hard, rather if the compromise seems sensible.

[finanalyst]

@2colours @coke The PR associated with this issue has been closed. Closing this issue as referring to older state.