Display external URL within Docsy

[Symbolics]

The new manual external links #511 look great on the preview, but are somewhat under-documented. For example I'm looking for something similar to the 'Hugo like link via URL parameter', but nowhere can I find documentation nor an example.

Perhaps an example for each of the options could be documented?

• external link
• Internal link
• internal without relref
• Hugo like link via url parameter

This should make it clearer how to use this feature.

[narrenfrei]

The four link types in the preview were intended for me as a test during development. I wanted to try out exactly how the existing front matter parameter url in Hugo (https://gohugo.io/content-management/front-matter/#predefined) works.

Since the url parameter is actually a feature of Hugo, I thought it's not so important to add this option in the documentation. In addition, the url paremeter does not lead to a link to a desired (external) resource in the menu, but only changes the URL of a page.

[Symbolics]

Perhaps I've encountered a bug.

What actually happens:

If I put manualLink: <url> in the front matter, the target page open up and replaces the docsy page.

If I place the Hugo URL parameter in the front matter I get:

Error: Error building site: "S:\src\documentation\content\en\docs\Reference\select.md:1:1": URLs with protocol (http*) not supported: ..."

The docs I used for the Hugo URL parameter say:

url
the full path to the content from the web root. It makes no assumptions about the path of the content file. It also ignores any language prefixes of the multilingual feature.

that mention of web root makes me suspect that this won't work with external links.

What I would like to happen:
Specify an external link and have it open inside the docsy main documentation pane. The use case for this is externally generated API documentation. It is single-page format with no styling, panes or sections.

The Hugo docs don't seem to provide this information in a way that's easily found. Perhaps a link to this section of the Hugo manual will help people find the information?

[narrenfrei]

OK, what you try ("Specify an external link and have it open inside the docsy main documentation pane.") is something completely different, than my externalLink option or Hugo's url option are made for.

How is this API description generated? Do you have a swagger or OpenAPI file? If yes, you could use it directly in Docsy. If not, you could try to make a shortcode with an iframe (like shown here https://gohugo.io/content-management/shortcodes/#example-youtube-output - as alternative method for embedding YouTube Videos).

[Symbolics]

It's not swagger/OpenAPI, as it's not a REST based interface. I'll look at the short-code, thanks. I was hopeful this was possible because the "Hugo like link via url parameter" in the example opens in the Docsy pane, although it open an internal link.

[Symbolics]

It looks like the iframe stuff is going to take longer than I have, so perhaps I'll ask a slightly different question:

Is there a way to 'pull in' a file from a git repo? There was recent discussion on Hugo modules and git 'submodules' and it got me thinking there might be a better way to do this. The use case is this:

• An umbrella project has the Docsy website.
• Subordinate projects each have their API's auto-generated as a single page and live in their respective docs/ directory in their own repo.
• I'd like a way to display these pages in a Reference section of the Docsy site.

I was hoping that the external links would do this, but since they don't I'm asking if there's any clever way to get these pages out of the repo and into Docsy? I know we could manually pull them in and place them in static/, but depending on a manual process is a recipe for things going stale and folks to start complaining, so it needs to be automatic.

Any ideas?

[Symbolics]

There's another use case I have encountered: external documentation. I originally was looking into some (rather ugly) ways of syncing content across repos, none of which look very appealing. The new use case is similar: third party documentation that I'd like to appear within a docsy site so that developers have a single place to view docs.

@narrenfrei , how much effort do you think the iframe/shortcode idea is? At least one other stackoverflow user seems to have the same requirement, though there was no accepted answer. Another on the hugo learn site.

I'd give this a go myself, but I doubt I'm the best person for the job; I had to look up what an iframe is to write this message.

[narrenfrei]

@Symbolics I'll take look.

[narrenfrei]

Here is my 1st suggestion for such a shortcode: #544
You can have a look on the resulted page here: https://deploy-preview-544--docsydocs.netlify.app/docs/dev-test-content/

[Symbolics]

This looks great! I just saw the pull request. Are there docs for its usage?

[narrenfrei]

This looks great! I just saw the pull request. Are there docs for its usage?

Not at the moment. But when the PR is ready, I'll also write a manual.

[narrenfrei]

This looks great! I just saw the pull request. Are there docs for its usage?

A first version of the manual is online:
https://deploy-preview-544--docsydocs.netlify.app/docs/adding-content/shortcodes/#iframe

[LisaFC]

@Symbolics, does the new feature (thanks @narrenfrei!) fix your issue?