relref: fix inconsistent behavior

[McShelby]

Discussed in #150

^{Originally posted by The-going November 9, 2021}

• A permanent link to the chapter cannot be obtained for all pages. Links are handled correctly for the title pages or `_index.md ' files and if such a page does not exist, an error message or a warning appears in the log, depending on the global settings. This is the correct operation of the code.
• For the rest of the pages. If the page exists, then we have a link to this page, and not to the chapter that is on this page. If the page does not exist, then we get a link to the current page, i.e. to itself. And no messages in the log or changes in the appearance of the link. This is unacceptable behavior.

This will not be good at all if the content of a multilingual site is organized in one directory, i.e. /_index.en.md ,_index.fr.md ,about.en.md ,about.fr.md

There is another problem of bad links, but it relates to the short code 'mermaid'. If you do something like:

{{< mermaid align="left" >}}
flowchart LR;
    S("testing") --> X["Test-1"]
    style S fill:#99ccff;
    click S "{{% relref "/core/_index.md#about-testing" %}}"
    click X "{{% relref "/core/testing.md#test-1" %}}"
{{< /mermaid >}}

For site: http://localhost:1313/website/
The link will look like: http://localhost:1313/core/testing/#test-1
And there should be: http://localhost:1313/website/core/testing/#test-1
For this construction, everything is fine in the text of the page: ["Test-1"]({{% relref "/core/testing.md#test-1" %}})

[The-going]

The short code for debugging the issue under discussion is here.

[The-going]

The debugging code allowed me to write the following short code to replace relref

<!-- Caller's current path and laguage ID for debugging -->
{{- $curpathf := $.Page.File -}}
{{- $lng := (.Site.Language.Lang) -}}
<!-- First we need to initialize the necessary variables -->
{{- $spls := (split (.Get 0) "#") -}}
{{- $filepath := index $spls 0 -}}
{{- $pagepath := replaceRE "/(_index([.].*[^.])?)?[.]md" "/" $filepath -}}
{{- $anchor := index $spls 1 -}}
{{- if index $spls 0 -}}
	{{- with .Site.GetPage (trim $pagepath "/") -}}
		<!-- Get the Anchor if it exists in page -->
		{{- if index $spls 1 -}}
			{{- if in (.Content) $anchor -}}
				{{- .RelPermalink -}}{{- printf "#%s" $anchor -}}
			{{- else -}}
				{{ warnf "[%s]: The anchor [#%s] for page [%s] was not received. Calling from: %s file" $lng $anchor $pagepath $curpathf }}
				{{- .RelPermalink -}}
			{{- end -}}
		{{- else -}}
			{{- .RelPermalink -}}
		{{- end -}}
	{{- else -}}
		{{ warnf "[%s]: Don't .GetPage with [%s] argument. Calling from: %s file" $lng $pagepath $curpathf }}
		{{ printf "**Bad link**" }}
	{{- end -}}
{{- else -}}
	{{- with .Site.GetPage (.Page) -}}
		{{- if in (.Content) $anchor -}}
			{{- .RelPermalink -}}{{- printf "#%s" $anchor -}}
		{{- else -}}
			{{ warnf "[%s]: For page itself anchor [#%s] was not received. Calling from: %s file" $lng $anchor $curpathf }}
			{{- .RelPermalink -}}
		{{- end -}}
	{{- else -}}
		{{ warnf "[%s]: Don't .GetPage with [%s] argument. Calling from: %s file" $lng (.Page) $curpathf }}
	{{- end -}}
{{- end -}}

But this code is causing hugo problems due to the inability to complete the rendering cycle.

[The-going]

This version of the relref code works correctly and outputs full informative warnings. It does not check the existence of an anchor on the page, but prints it if it exists in the argument string.

<!-- Caller's current path and laguage ID for debugging -->
{{- $curpathf := $.Page.File -}}
{{- $lng := (.Site.Language.Lang) -}}
<!-- First we need to initialize the necessary variables -->
{{- $spls := (split (.Get 0) "#") -}}
{{- $filepath := index $spls 0 -}}
{{- $pagepath := replaceRE "/(_index([.].*[^.])?)?[.]md" "/" $filepath -}}
{{- $anchor := index $spls 1 -}}
<!-- Get the page if the path to it exists -->
{{- if index $spls 0 -}}
	{{- with .Site.GetPage (trim $pagepath "/") -}}
		<!-- Print the Anchor if it exists -->
		{{- if index $spls 1 -}}
			{{- .RelPermalink -}}{{- printf "#%s" $anchor -}}
		{{- else -}}
			{{- .RelPermalink -}}
		{{- end -}}
	{{- else -}}
		{{ warnf "[%s]: Don't .GetPage with [%s] argument.\t Calling from: %s" $lng $pagepath $curpathf }}
		{{ printf "**Bad link**" }}
	{{- end -}}
{{- else -}}
<!-- Get the page from which the call was made if the path does not exist. -->
	{{- with .Page -}}
		{{- if index $spls 1 -}}
		<!-- Print the Anchor if it exists -->
			{{- .RelPermalink -}}{{- printf "#%s" $anchor -}}
		{{- else -}}
			{{ warnf "[%s]: For page itself anchor [#%s] was not received.\t Calling from: %s" $lng $anchor $curpathf }}
			{{- .RelPermalink -}}
		{{- end -}}
	{{- else -}}
		{{ warnf "[%s]: Itsef Don't .GetPage with [%s] argument.\t Calling from: %s" $lng (.Page) $curpathf }}
	{{- end -}}
{{- end -}}

It is necessary for someone other than me to test this code and possibly make changes to the text of the output warnings.

[McShelby]

I had "fun" the whole evening with this to understand the current behaviour. Short: It's brain-melting.

The _index.md part seems to be reason why this shortcode was written in the first place. Or the shortcode was missing from ancient Hugo versions when the theme was initially written (commit history does not give further clues).

Since I work with Hugo, it has a built-in shortcode for ref/relref. So best seems to remove our implementation from the theme and rely on standard behaviour.

This introduces some breaking changes for some users as they have to scan their code for (ref\s+"[^"]*)_index\.md" and replace it by $1"

Could you test this with your current installation and see if this works for you?

I tested this in our installations and besides from the regex I didn't need to make any further changes.

[The-going]

The _index.md part seems to be reason why this shortcode was written in the first place. Or the shortcode was missing from ancient Hugo versions when the theme was initially written (commit history does not give further clues).

Since I work with Hugo, it has a built-in shortcode for ref/relref. So best seems to remove our implementation from the theme and rely on standard behaviour.

The built-in functions ref\relref handle file names well such as name.md , name.en.md , _index.md.
But not _index.en.md. Or am I wrong? Okay, we need to check.

This introduces some breaking changes for some users as they have to scan their code for (ref\s+"[^"]*)_index\.md" and replace it by $1"

Here you mean calling a short code in the source file *.md.
And what does the full line where the call takes place look like? On my website it is:
[testing]({{< relref "core/testing.md" >}})

[McShelby]

The _index.md part seems to be reason why this shortcode was written in the first place. Or the shortcode was missing from ancient Hugo versions when the theme was initially written (commit history does not give further clues).
Since I work with Hugo, it has a built-in shortcode for ref/relref. So best seems to remove our implementation from the theme and rely on standard behaviour.

The built-in functions ref\relref handle file names well such as name.md , name.en.md , _index.md. But not _index.en.md. Or am I wrong? Okay, we need to check.

"Yes, we can!" {{ relref . (dict "path" "name" "lang" "en") }} from the Hugo docs.

Your naming scheme is one of at least two. There are installations where files are contained in language subfolders like en/name.md and de/name.md. That's the reason why the official implementation requires further parameter in this case.

So that's also something for the migration notes.

This introduces some breaking changes for some users as they have to scan their code for (ref\s+"[^"]*)_index\.md" and replace it by $1"

Here you mean calling a short code in the source file *.md. And what does the full line where the call takes place look like? On my website it is: [testing]({{< relref "core/testing.md" >}})

You never should assume the filename, as there are different naming schemes. So [testing]({{< relref "core/testing" >}}) should be enough.

After executing the first regex to get rid of explicitly named _index.md calls, you also need to search for (ref\s+"[^"]*)\.md" and replace it by $1" in your case.

[McShelby]

Interesting reads about the built-in shortcode and its history:

• https://github.com/gohugoio/hugo/releases/tag/v0.45
• Make ref and relref point to the "page I mean" gohugoio/hugo#4312
• https://github.com/gohugoio/hugo/releases/tag/v0.13

[The-going]

I apologize. I was distracted from our conversation by an urgent task.

[McShelby]

Never mind! We are all here voluntarily. I am thankful for every one who's participating.

[McShelby]

Was the deletion of ref/relref from the theme successful for you?