menu: support for external links

[Nuc1eoN]

Hello, thank you for this fork!

I have a question, how do I create a (reference) link as an item in the left side menu?

I want that item to reflink to a different part of the documentation.

I have tried something like:

+++
menutitle = "Link to other page"
url = "/other-page/"
+++

But it seems that depending on hugo's mood it actually works, while other times "hijacks" the other pages route.

But probably I am not doing it the way it is supposed to? Is there even an easy or non-hacky way to do it?

If not then I would kindly request such feature to be in the theme :)

[McShelby]

Without seeing the full example my answer is based on assumptions:

Yout want to have a (probably nested) entry int the site's menu to a page that already exists in a different area of the menu?

That's not possible and I doubt that Hugo is capable of this.

The clostest you can get is, to create a shortcut link. This is always displayed as a flat list below the menu and needs to be defined for each language (if you have a multilang setup).

[Nuc1eoN]

Hi thank you for the response.

Yes I think you understood me correctly, I would like my documentation to behave like this example:

1 Overview
 - Basics
 - Advanced
 - More Advanced
 - Reference (should be just a reflink to actual reference guide ->)

2 Configuration
 - Paragraph 1
 - Paragraph 2
 - Paragraph 3

3 Reference Guide (-> link to this chapter)
 - [...]

So the "1 Overview -> Reference" should just be a reference to the actual chapter further below, because it thematically belongs to the Overview (or introduction), but is in itself a bigger topic that deserves it's own full chapter.

As I said this actually works half-way with the url= param, but unfortunately hugo randomly prioritizes which route is the correct one, each time it generates the pages.

That's not possible and I doubt that Hugo is capable of this.

Hm damn there is no way? I thought maybe an attribute could be added to the pages meta tags, that it is only a reflink with no content?

(Another creative way I came up with, is that the file I create in the folder which should only be a reflink, would be a symlink poiting to the actual file/folder on the file system. This works half way but it does not correct the route unfortunately. Just mentioning it here for the fun though^^)

The clostest you can get is, to create a shortcut link. This is always displayed as a flat list below the menu and needs to be defined for each language (if you have a multilang setup).

I know, I have looked at this, but this would mean the link is under the whole menu? That is unfortunately not what I am looking for, since it should be part of a nested menu.

Any other ideas or is this actually impossible with hugo? :/

[Nuc1eoN]

@McShelby Apparently I was not the first one to miss such fucntionality, see google/docsy#449

Following the docsy bugreport it seems it was actually implemented with google/docsy#511

I am not that deep into the code, but it seems this is what I am looking for?

[Nuc1eoN]

I saw you've changed the title. Just be exact, my original bug report was about support for reflinks, while the docsy issue I have linked in my previous post was mainly about external links.

But it seems that in the final PR they've added support for both, in which case it obviously fits the bill^^

[McShelby]

Yeah. I just quickly scanned over the changesets and think, if we add this featrue, we should add it this way to satisfy every use case.

[McShelby]

Just talking to myself as a reminder:

The basic idea here would be, to add menu entries to the parents frontmatter and later merge those into the list of pages. This could be done in page-meta.hugo and stored in a scratch to be later been used.

https://discourse.gohugo.io/t/adding-a-child-to-a-menu-item/42007
https://gohugo.io/templates/menu-templates/#menu-entries-from-the-pages-front-matter

See #652 containing links to the official Hugo docs and a reference to the Ananke theme.

[McShelby]

The Docsy way is reasonable. https://www.docsy.dev/docs/adding-content/navigation/#add-manual-links-to-section-menu

Have to think how arrow nav, print and the children shortcode should behave, but this will be part of a next feature release.

[McShelby]

Now available using menuPageRef or menuUrl front matter values.