Schemas at /schemas in YAML, and /schemas/list in HTML

.htmltest.yml

@@ -5,6 +5,7 @@ IgnoreAltMissing: true
 IgnoreCanonicalBrokenLinks: false
 CheckMailto: false
 IgnoreInternalURLs: # list of paths
+  - /schemas/latest
 IgnoreURLs: # list of regexs of paths or URLs to be ignored
   - ^/docs/instrumentation/\w+/(api|examples)/$
   - ^/docs/instrumentation/net/(metrics-api|traces-api)/

assets/scss/_schema.scss

@@ -0,0 +1,22 @@
+.ot-schema-list,
+.ot-schemas-404 {
+  // Hide the sidebar. Add the sidebar's number of col to `main`
+  main {
+    @extend .col-md-10;
+  }
+
+  .td-sidebar {
+    display: none;
+  }
+
+  main td code {
+    background-color: inherit;
+  }
+
+  // Fixes https://github.com/open-telemetry/opentelemetry.io/issues/1102
+  // TODO: upstream
+  .td-sidebar-toc {
+    margin-top: 4rem;
+    top: 0;
+  }
+}

assets/scss/_styles_project.scss

@@ -4,6 +4,7 @@
 @import 'registry';
 @import 'tabs';
 @import 'external_link';
+@import 'schema';
 
 .td-home {
   .otel-logo {

content/en/schemas/_index.md

@@ -0,0 +1,25 @@
+---
+title: 404 - Schema not found
+linkTitle: Schemas
+type: docs
+no_list: true
+body_class: ot-schemas-404
+outputs: [HTML, YAML]
+#
+# Note:
+#   The paths to the `list` and `latest` are absolute below since we
+#   don't know from which URL this 404 page will be served.
+#
+---
+
+The page or schema you requested doesn't exist. Maybe you're looking for one of
+these:
+
+- [List of schemas](/schemas/list/) hosted on this site, also available in
+  [YAML format](/schemas/index.yaml)
+- [Latest](/schemas/latest) schema
+- More information about [Telemetry Schemas] in general, or [OpenTelemetry
+  Schema] in particular.
+
+[OpenTelemetry Schema]: /docs/specs/otel/schemas/#opentelemetry-schema
+[Telemetry Schemas]: /docs/specs/otel/schemas/

content/en/schemas/list.md

@@ -0,0 +1,21 @@
+---
+title: OpenTelemetry Schemas
+linkTitle: List
+type: docs
+body_class: ot-schema-list
+---
+
+{{% alert title="<i class=\"fa-solid fa-triangle-exclamation\"></i> Warning" color="warning" %}}
+
+This page, its content, and formatting are **non-normative** and **subject to
+change**. In particular it is not meant for automated processing.
+
+{{% /alert %}}
+
+The OpenTelemetry schemas hosted on this site are listed below. To learn more
+about schemas, see [Telemetry Schemas][]. The list is also available in
+[YAML format](/schemas/index.yaml).
+
+{{% schemas %}}
+
+[Telemetry Schemas]: /docs/specs/otel/schemas/

hugo.yaml

@@ -32,15 +32,18 @@ markup:
     # noClasses: false
     style: tango
 
-# Netlify _redirects file
 mediaTypes:
-  text/netlify: {}
+  text/netlify: {} # Netlify _redirects file
+  text/yaml: {}
 
 outputFormats:
   REDIRECTS:
     mediaType: text/netlify
     baseName: _redirects
     notAlternative: true
+  YAML: # Yaml for Schemas index page
+    mediaType: text/yaml
+    baseName: index.yaml
 
 outputs:
   home: [HTML, REDIRECTS, RSS]

layouts/index.redirects

@@ -47,7 +47,10 @@
 {{ $schemaFiles := partial "schema-file-list" . -}}
 {{ $latestSchemaFile := index $schemaFiles 0 -}}
 
+/schemas         /schemas/index.yaml
 /schemas/latest  /schemas/{{ $latestSchemaFile.Name }}
+/schemas/list    /schemas/list/ 200 # Explicit rule to avoid the next catch all
+/schemas/*       /schemas/?     404 # Report 404 for anything else that's missing
 
 {{/*
   Social-media image redirects. As mentioned in

layouts/schemas/section.yaml

@@ -0,0 +1,10 @@
+{{ $schemaFiles := partial "schema-file-list" . -}}
+{{ $latestSchemaFile := index $schemaFiles 0 -}}
+# OpenTelemetry Schemas
+#
+# https://github.com/open-telemetry/semantic-conventions/tree/v{{ $latestSchemaFile.Name }}/schemas
+#
+{{ $schemaFiles := partial "schema-file-list.html" . -}}
+{{- range $schemaFiles -}}
+- {{ .Name }}
+{{ end -}}

layouts/shortcodes/schemas.md

@@ -0,0 +1,10 @@
+{{- $schemaFiles := partial "schema-file-list.html" . -}}
+
+| Version |
+|---------|
+{{ range $i, $schema := $schemaFiles -}}
+| [`{{ $schema.Name }}`](/schemas/{{ $schema.Name }})
+{{- if eq $i 0 -}}
+  ([latest](/schemas/latest))
+{{- end -}} |
+{{ end -}}

netlify.toml

@@ -15,7 +15,29 @@ from = "https://blog.opentelemetry.io/*"
 to = "https://opentelemetry.io/blog/:splat"
 force = true
 
+# Schemas
+
+[[headers]]
+  for = "/schemas/"
+  [headers.values]
+    content-type = "text/yaml"
+
+# Ensure that there is a header entry for each major version of the published
+# schemas. (If this becomes too bothersome to update, we can automate the
+# creation of these schema header entries in a `_headers` file using Hugo
+# templating constructs.)
+
+[[headers]]
+  for = "/schemas/1.*"
+  [headers.values]
+    content-type = "application/yaml"
+
+[[headers]]
+  for = "/schemas/2.*"
+  [headers.values]
+    content-type = "application/yaml"
+
 [[headers]]
-  for = "/schemas/:version"
+  for = "/schemas/3.*"
   [headers.values]
     content-type = "application/yaml"