Add external links to sidebar

[huehnerlady]

Hi,

I would like to add some external links to the sidebar of a section on my docsy page.

In this screenshot for Example the Example Page should be external.
I could not find any way in the documentation to do so. Is there a way? If not are there plans to introduce that?

[LisaFC]

It's a tricky one because the sidebar tree partial actually iterates through your page files recursively, printing out sidebar items as it goes, so getting it to add something in in the middle would not be trivial - unless it was at the end of the menu. Or you could replace the generated sidebar entirely with a non-autogenerated TOC? Then you could put whatever you like in it though you lose the benefit of the menu automatically updating when you add pages. Let me have a think if there are any other options (or if anyone else has suggestions).

(it's very easy to add things to the top nav because it's a straightforward menu with all the items added explicitly, either in metadata or config: https://www.docsy.dev/docs/adding-content/navigation/#top-level-menu)

[huehnerlady]

@LisaFC many thanks for your quick response 🙂

I was thinking it to be similar to the navbar. I can add items in the menu.[lang].toml as well as the items in the tree being then ordered by [menu.main.weight] (as you also mentioned in your answer)

So I would guess something like that would be what I am looking for and in addition it would be a similar mechanism to the top navbar, so not something completely unique :)

Of course I appreciate that it could be different with the sidebar, I am not aware of the deeper implementation of the theme

[LisaFC]

Yeah, the sidebar's slightly different in that it iterates through all your pages (including subsections) and adds them to the sidebar even if you haven't explicitly added them to a menu - if there's a page file, it just gets pulled in and ordered by weight. Here's the code:
https://github.com/google/docsy/blob/master/layouts/partials/sidebar-tree.html#L43

You could possibly reimplement it using Hugo menus but then I think you'd have to add menu metadata (or config) for every page you wanted to include in order to "build" the menu.

[huehnerlady]

That is unfortunate. I think for now we will wrap the external page we want to reference to into a page on the website then 🙂

[laszewsk]

I have the same desire. If you find or have a solution let me know.

We thought even we are in the need of a second TOC on the left-hand side. E.g. one that is autogenerated, but the other one is hardcoded.

[narrenfrei]

I struggled also into that problem, when I started with Docsy. My simply solution was to make a blank site holding only the link to the target.

But now I'd have another idea: Maybe we could modify the sidebar-tree partial, to overwrite the normal target of a sidebar link by a variable in the front matter of a file?

[laszewsk]

If we were to do a custom sidebar we also need to worry about the levels in case they do not reflect the typical hierarchy. So I think if we were to have a meta data entry it should look something like

---

sidebar:
    section 1
         section 2
              title
---

Does anyone have an example on how to "hardcode" the side menu? O know it defeats a bit the purpose of docsy, but it would go a long way for the meanwhile till we have a more comprehensive solution.

[narrenfrei]

Here you can find my 1st simple approach for adding external links into sidebar menu tree by adding a md file on desired position in content folder structure holding the URL for external link in the front matter parameter externalLink:
narrenfrei@8306e71

I'll send a pull request, when I have tested and optimized it, if you like my approach.

[LisaFC]

Oh that's nice @narrenfrei, and it means you don't have to worry about manually constructing the entire rest of the menu tree - just pop in a stand-in page with your link URL and weight.

@laszewsk you could trivially hardcode a side menu by just creating your own sidebar-tree.html and replacing the nested lists in it with your own menu in HTML - you wouldn't have a Hugo menu you could refer to from anything else, but you might not want/need to.... Alternatively, yes, you'd need to add metadata to your pages as described in Hugo Menus, using the parent field to nest menus:
https://gohugo.io/content-management/menus

...and then render it in your sidebar-tree.html
https://gohugo.io/templates/menu-templates/

[narrenfrei]

I've posted a small update to my approach:
15fe5b8

Add possibility to specify the external link in sidebar menu tree and also to use HUGO relref function.
Used front matter parameters:
externalLink
externalLinkRelref ... alternative to externalLink for using HUGO relref function
externalLinkTitle
externalLinkTarget

[narrenfrei]

Shall I also write a how-to on https://www.docsy.dev/docs/adding-content/navigation/ ?

[huehnerlady]

Shall I also write a how-to on https://www.docsy.dev/docs/adding-content/navigation/ ?

from a consumer point of view, I did look there first, so I would see it there :)

[narrenfrei]

My approach have passed my tests quiet well, but I took also a deeper look on the generated markup for the sidebar tree menu and I've found some issues: #450

@LisaFC Should I make the pull request for this issue before we solved the problem mentioned above?

[LisaFC]

Yes, please do write a how to as part of your PR!

As I said in the other issue, the syntactic weirdness in the menu is not something that's urgently in need of fixing (and fixing it might break things), and it looks like your "add external links" functionality can work within the existing code.