Use render-link hook to resolve references in specs

Author: chalin

content/en/docs/specs/status.md

@@ -59,7 +59,7 @@ same as the **Protocol** status.
 - [Specification][tracing]
 - {{% spec_status "API" "otel/trace/api" "Status" %}}
 - {{% spec_status "SDK" "otel/trace/sdk" "Status" %}}
-- {{% spec_status "Protocol" "otlp" "/document-status/.*for.*trace" %}}
+- {{% spec_status "Protocol" "otlp" "/document-status.*for.*trace" %}}
 - Notes:
   - The tracing specification is now completely stable, and covered by long term
     support.
@@ -73,7 +73,7 @@ same as the **Protocol** status.
 - [Specification][metrics]
 - {{% spec_status "API" "otel/metrics/api" "Status" %}}
 - {{% spec_status "SDK" "otel/metrics/sdk" "Status" %}}
-- {{% spec_status "Protocol" "otlp" "/document-status/.*for.*metric" %}}
+- {{% spec_status "Protocol" "otlp" "/document-status.*for.*metric" %}}
 - Notes:
   - OpenTelemetry Metrics is currently under active development.
   - The data model is stable and released as part of the OTLP protocol.
@@ -98,7 +98,7 @@ same as the **Protocol** status.
 - [Specification][logging]
 - {{% spec_status "Bridge API" "otel/logs/api" "Status" %}}
 - {{% spec_status "SDK" "otel/logs/sdk" "Status" %}}
-- {{% spec_status "Protocol" "otlp" "/document-status/.*for.*log" %}}
+- {{% spec_status "Protocol" "otlp" "/document-status.*for.*log" %}}
 - Notes:
   - The [logs data model][] is released as part of the OpenTelemetry Protocol.
   - Log processing for many data formats has been added to the Collector, thanks
@@ -116,7 +116,7 @@ same as the **Protocol** status.
 ### Profiles
 
 - [Specification][profiles]
-- {{% spec_status "Protocol" "otlp" "/document-status/.*for.*profiles" %}}
+- {{% spec_status "Protocol" "otlp" "/document-status.*for.*profiles" %}}
 
 [baggage]: /docs/specs/otel/baggage/
 [event semantic conventions]: /docs/specs/semconv/general/events/

layouts/_default/_markup/render-link.html

@@ -1,4 +1,5 @@
-{{ $url := .Destination -}}
+{{ $url := .Destination -}} {{/* TODO: rename to $dest */ -}}
+{{ $u := urls.Parse $url -}}
 
 {{/*
 
@@ -10,9 +11,32 @@
   - $url is an absolute path -- that is, it starts with /
   - The $url target page exists in this locale
 
+  Reference to Hugo's default:
+  https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/_default/_markup/render-link.html
+
   */ -}}
 
-{{ if hasPrefix $url "/" -}}
+
+{{ if and
+    (strings.HasPrefix $.PageInner.RelPermalink "/docs/specs")
+    (not $u.IsAbs)
+    (not (strings.HasPrefix $url "#"))
+-}}
+  {{ $path := replaceRE `\bREADME\.md\b` "_index.md" $u.Path -}}
+  {{ $href := $url -}}
+  {{ with or
+    ($.PageInner.GetPage $path)
+    ($.PageInner.Resources.Get $path)
+    (resources.Get $path)
+  -}}
+    {{ $href = .RelPermalink -}}
+    {{ with $u.RawQuery -}}{{ $href = printf "%s?%s" $href . -}}{{ end -}}
+    {{ with $u.Fragment -}}{{ $href = printf "%s#%s" $href . -}}{{ end -}}
+  {{ else -}}
+    {{ warnf "File %s: cannot resolve spec link reference '%s'" .Page.File.Filename $url -}}
+  {{ end -}}
+  {{ $url = $href -}}
+{{ else if hasPrefix $url "/" -}}
   {{/* Hard-coded default lang since it's what's most efficient and won't change :) */ -}}
   {{ $defaultLang := "en" -}}
   {{ $lang := .Page.Language.Lang -}}
@@ -22,7 +46,6 @@
       {{ warnf "File %s: drop unnecessary '%s' prefix from %s"
               .Page.File.Filename $langPathPrefix $url -}}
     {{ else -}}
-      {{ $u := urls.Parse $url -}}
       {{ $localizedPagePath := add $langPathPrefix (strings.TrimPrefix "/" $url) -}}
       {{/*
         Look for the page (referenced by $url) in this page's locale's site.

scripts/content-modules/adjust-pages.pl

@@ -26,7 +26,6 @@
 my $otlpSpecVers = $versions{'otlp:'};
 my $semconvVers = $versions{'semconv:'};
 my %patchMsgCount;
-my $openRelref = '{{% relref';
 
 sub printTitleAndFrontMatter() {
   print "---\n";
@@ -119,7 +118,7 @@ ($$)
 
   ## Semconv
 
-  if ($ARGV =~ /\/semconv/) {
+  if ($ARGV =~ /^tmp\/semconv/) {
     my $otel_spec_event_deprecation = '(opentelemetry-specification/blob/main/specification/logs)/event-(api|sdk).md';
     if (/$otel_spec_event_deprecation/) {
       # Cf. https://github.com/open-telemetry/opentelemetry-specification/pull/4359
@@ -131,13 +130,6 @@ ($$)
     s|(\]:\s*)/docs/|$1$specBasePath/semconv/|;
 
     s|\((/model/.*?)\)|($semconvSpecRepoUrl/tree/v$semconvVers/$1)|g;
-
-    # TODO: drop after fix of https://github.com/open-telemetry/semantic-conventions/pull/1316
-    s|#instrument-advice\b|#instrument-advisory-parameters|g;
-
-    # TODO: drop after fix of https://github.com/open-telemetry/semantic-conventions/issues/1313
-    s|(/database/database-spans\.md)#batch-operations|$1|g;
-    s|(/messaging/messaging-spans\.md)#common-messaging-operations|$1|g;
   }
 
 
@@ -153,7 +145,6 @@ ($$)
 
   s|\(https://github.com/open-telemetry/opentelemetry-specification\)|($specBasePath/otel/)|;
   s|(\]\()/specification/|$1$specBasePath/otel/)|;
-  s|\.\./semantic_conventions/README.md|$semConvRef| if $ARGV =~ /overview/;
   s|\.\./specification/(.*?\))|../otel/$1|g if $ARGV =~ /otel\/specification/;
 
   # Match markdown inline links or link definitions to OTel spec pages: "[...](URL)" or "[...]: URL"
@@ -172,93 +163,15 @@ ($$)
   s|(\]\()([^)]+\.png\))|$1../$2|g if $ARGV =~ /\btmp\/semconv\/docs\/general\/attributes/;
   s|(\]\()([^)]+\.png\))|$1../$2|g if $ARGV =~ /\btmp\/semconv\/docs\/http\/http-spans/;
 
-  # Handle links containing `README.md`
-
   # Rewrite paths that are outside of the spec folders as external links:
-
   s|\.\.\/README.md|$otelSpecRepoUrl/|g if $ARGV =~ /specification._index/;
-  s|\.\.\/README.md|..| if $ARGV =~ /specification\/library-guidelines.md/;
+  s|\.\.\/README.md|/docs/specs/otel/| if $ARGV =~ /specification\/library-guidelines.md/;
 
   s|(\.\.\/)+(experimental\/[^)]+)|$otelSpecRepoUrl/tree/v$otelSpecVers/$2|g;
   s|(\.\.\/)+(supplementary-guidelines\/compatibility\/[^)]+)|$otelSpecRepoUrl/tree/v$otelSpecVers/$2|g;
 
   s|\.\./((?:examples/)?README\.md)|$otlpSpecRepoUrl/tree/v$otlpSpecVers/$1|g if $ARGV =~ /^tmp\/otlp/;
 
-  # Replace `README.md` by `_index.md` in markdown links:
-  s{
-      # An inline markdown link, just before the URL: `](` like in `[docs](/docs)`
-      (
-        \]\(
-      )
-
-      # Match any local path. In the `[^...]` exclude group we have:
-      # - `:` so as to exclude external links, which use `:` after a protocol specifier
-      # - `)` prevents us from gobbling up past the end of the inline link
-
-      ([^:\)]*)
-      README\.md
-      ([^)]*)  # Any anchor specifier
-      (\))     # The end of the inline link
-  }{$1$openRelref "$2_index.md$3" \%\}\}$4}gx;
-
-  # Replace `README.md` by `_index.md` in markdown link definitions:
-  s{
-      # A markdown link definition, just before the URL: `]:`, like in `[docs]: /docs`
-      (
-        \]:\s*
-      )
-
-      # Match any local path. In the `[^...]` exclude group we have:
-      # - `:` so as to exclude external links, which use `:` after a protocol specifier
-      # - A space should prevent us from gobbling up beyond the end of a link def
-
-      ([^: ]*)
-      README\.md
-      ([^)]*) # Any anchor specifier
-      (\n)$   # End of the link definition
-  }{$1$openRelref "$2_index.md$3" \%\}\}$4}gx;
-
-  # Rewrite inline links
-  if ($ARGV =~ /\btmp\/opamp/) {
-    s|\]\(([^:\)]*?)\.md((#.*?)?)\)|]($1/$2)|g;
-  } else {
-    # Generally rewrite markdown links as {{% relref "..." %}} expressions,
-    # since that gets Hugo to resolve the links. We can't use the raw path since
-    # some need a `../` prefix to resolve. We let Hugo handle that.
-    s{
-        # Match markdown link `](` just before the URL
-        (\]\()
-
-        # Match the link path:
-        (
-          # Match paths upto but excluding `.md`. The character exclusions are as follows:
-          #
-          # - `:` ensures the URL is a path, not an external link, which has a protocol followe by `:`
-          # - `)` so we don't overrun the end of the markdown link, which ends with `)`
-          # - `{` or `}` so that the path doesn't contain Hugo {{...}}
-
-          [^:\)\{\}]*?
-
-          \.md
-
-          # Match optional anchor of the form `#some-id`
-          (?:
-            \#.*?
-          )?
-        )
-        # Closing parenthesis of markdown link
-        \)
-    }{$1$openRelref "$2" \%\}\}\)}gx;
-  }
-
-  # Rewrite link defs to local pages such as the following:
-  #
-  # [specification]: overview.md
-  # [faas]: some-path/faas-spans.md (FaaS trace conventions)
-  #
-  # The subregex `[:\s]+` excludes external URLs (because they contain a colon after the protocol)
-  s|^(\[[^\]]+\]:\s*)([^:\s]+)(\s*(\(.*\))?)$|$1\{{% relref "$2" %}}$3|g;
-
   # Make website-local page references local:
   s|https://opentelemetry.io/|/|g;