[CI] Improve spec adjust-pages

scripts/content-modules/adjust-pages.pl

@@ -26,6 +26,7 @@
 my $otlpSpecVers = $versions{'otlp:'};
 my $semconvVers = $versions{'semconv:'};
 my %patchMsgCount;
+my $openRelref = '{{% relref';
 
 sub printTitleAndFrontMatter() {
   print "---\n";
@@ -152,26 +153,83 @@ ($$)
   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/;
 
-  s|\.\.\/README.md\b|$otelSpecRepoUrl/|g if $ARGV =~ /specification._index/;
-  s|\.\.\/README.md\b|..| if $ARGV =~ /specification.library-guidelines.md/;
+  # Handle links containing `README.md`
 
-  s|\.\./(opentelemetry/proto/?.*)|$otlpSpecRepoUrl/tree/v$otlpSpecVers/$1|g if $ARGV =~ /\btmp\/otlp/;
-  s|\.\./README.md\b|$otlpSpecRepoUrl/|g if $ARGV =~ /\btmp\/otlp/;
-  s|\.\./examples/README.md\b|$otlpSpecRepoUrl/tree/v$otlpSpecVers/examples/|g if $ARGV =~ /\btmp\/otlp/;
+  # Rewrite paths that are outside of the spec folders as external links:
 
-  s|\bREADME.md\b|_index.md|g if $ARGV !~ /otel\/specification\/protocol\/_index.md/
-    # TODO drop once semconv PR is merged and module is updated in this repo
-    && $ARGV !~ /semconv\/docs\/non-normative\/code-generation.md/;
+  s|\.\.\/README.md|$otelSpecRepoUrl/|g if $ARGV =~ /specification._index/;
+  s|\.\.\/README.md|..| if $ARGV =~ /specification\/library-guidelines.md/;
 
-  # Rewrite paths that are outside of the main spec folder as external links
   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 {
-    s|\]\(([^:\)]*?\.md(#.*?)?)\)|]({{% relref "$1" %}})|g;
+    # 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:
@@ -185,6 +243,9 @@ ($$)
   # Make website-local page references local:
   s|https://opentelemetry.io/|/|g;
 
+  ## OTLP proto files: link into the repo:
+  s|\.\./(opentelemetry/proto/?.*)|$otlpSpecRepoUrl/tree/v$otlpSpecVers/$1|g if $ARGV =~ /\btmp\/otlp/;
+
   ## OpAMP
 
   s|\]\((proto/opamp.proto)\)|]($opAmpSpecRepoUrl/blob/main/$1)|;