Add pages that provide a rendered version of the SPIFFE standards

content/.gitignore

@@ -14,3 +14,11 @@ docs/latest/microservices/envoy-x509/README.md
 docs/latest/microservices/envoy-jwt/README.md
 docs/latest/microservices/envoy-opa/README.md
 docs/latest/microservices/envoy-jwt-opa/README.md
+docs/latest/spiffe-specs/JWT-SVID.md
+docs/latest/spiffe-specs/SPIFFE-ID.md
+docs/latest/spiffe-specs/SPIFFE.md
+docs/latest/spiffe-specs/SPIFFE_Federation.md
+docs/latest/spiffe-specs/SPIFFE_Trust_Domain_and_Bundle.md
+docs/latest/spiffe-specs/SPIFFE_Workload_API.md
+docs/latest/spiffe-specs/SPIFFE_Workload_Endpoint.md
+docs/latest/spiffe-specs/X509-SVID.md

content/docs/latest/spiffe-specs/_index.md

@@ -0,0 +1,11 @@
+---
+title: The SPIFFE Standard
+short: Standards
+kind: spiffe-specs
+---
+
+**SPIFFE**, the Secure Production Identity Framework for Everyone, is a set of open-source standards for securely identifying software systems in dynamic and heterogeneous environments.
+
+This section contains rendered versions of the documents that make up the standards. The canonical source for these standards is [https://github.com/spiffe/spiffe/tree/main/standards](https://github.com/spiffe/spiffe/tree/main/standards).
+
+{{< sectiontoc "spiffe-specs" >}}

external.yaml

@@ -184,3 +184,65 @@ microservices/envoy-jwt-opa:
                 description: Secure Communication Using Envoy with JWT-SVIDs and Open Policy Agent Authorization
                 weight: 400
             beacon: "{{< scarf/pixels/high-interest >}}"
+
+spiffe-specs:
+    source: https://github.com/spiffe/spiffe
+    branch: main
+    pullFiles:
+        - standards/JWT-SVID.md
+        - standards/SPIFFE-ID.md
+        - standards/SPIFFE.md
+        - standards/SPIFFE_Federation.md
+        - standards/SPIFFE_Trust_Domain_and_Bundle.md
+        - standards/SPIFFE_Workload_API.md
+        - standards/SPIFFE_Workload_Endpoint.md
+        - standards/X509-SVID.md
+    transform:
+        SPIFFE.md:
+            frontMatter:
+                title: Secure Production Identity Framework for Everyone
+                short: SPIFFE
+                kind: spiffe-specs
+                weight: 100
+        JWT-SVID.md:
+            frontMatter:
+                title: JWT-SVID
+                short: JWT-SVID
+                kind: spiffe-specs
+                weight: 300
+        X509-SVID.md:
+            frontMatter:
+                title: X509-SVID
+                short: X509-SVID
+                kind: spiffe-specs
+                weight: 300
+        SPIFFE-ID.md:
+            frontMatter:
+                title: SPIFFE Identity and Verifiable Identity Document
+                short: SPIFFE ID and Verifiable Identity Document
+                kind: spiffe-specs
+                weight: 200
+        SPIFFE_Federation.md:
+            frontMatter:
+                title: SPIFFE Federation
+                short: SPIFFE Federation
+                kind: spiffe-specs
+                weight: 500
+        SPIFFE_Trust_Domain_and_Bundle.md:
+            frontMatter:
+                title: SPIFFE Trust Domain and Bundle
+                short: SPIFFE Trust Domain and Bundle
+                kind: spiffe-specs
+                weight: 200
+        SPIFFE_Workload_API.md:
+            frontMatter:
+                title: SPIFFE Workload API
+                short: SPIFFE Workload API
+                kind: spiffe-specs
+                weight: 400
+        SPIFFE_Workload_Endpoint.md:
+            frontMatter:
+                title: SPIFFE Workload Endpoint
+                short: SPIFFE Workload Endpoint
+                kind: spiffe-specs
+                weight: 400

layouts/partials/docs/article.html

@@ -15,6 +15,14 @@
 
     <section class="section">
       <div class="content">
+        {{ if and (eq .Params.kind "spiffe-specs") .Params.externalSource }}
+        <div class="message is-info">
+          <div class="message-body">
+            This document is part of the SPIFFE standard. The canonical version can be found at
+            <a href="{{ .Params.externalSource }}" target="_blank" rel="noopener">{{ .Params.externalSource }}</a>
+          </div>
+        </div>
+        {{ end }}
         {{ .Content }}
       </div>
     </section>

layouts/partials/docs/sidenav-section.html

@@ -20,7 +20,7 @@
 </div>
 {{- end -}}
 
-{{- range ($scratch.Get "sectionsForVersion") -}}
+{{- range sort ($scratch.Get "sectionsForVersion") ".Params.weight" -}}
     {{- partial "docs/sidenav-link.html" (dict "ctx" . "pageUrl" $pageUrl "version" $version) -}}
 {{- end -}}
 

layouts/partials/docs/sidenav.html

@@ -2,6 +2,7 @@
 {{ $allDocs    := site.Pages  }}
 
 {{ $spiffeAbout        := where $allDocs ".Params.kind" "eq" "spiffe-about" }}
+{{ $spiffeSpecs        := where $allDocs ".Params.kind" "eq" "spiffe-specs" }}
 
 {{ $spireAbout         := where $allDocs ".Params.kind" "eq" "spire-about" }}
 
@@ -47,6 +48,7 @@
   SPIFFE
 </span>
 {{ partial "docs/sidenav-section.html" ( dict "ctx" . "section" $spiffeAbout "pageUrl" $pageUrl "version" $version ) }}
+{{ partial "docs/sidenav-section.html" ( dict "ctx" . "section" $spiffeSpecs "pageUrl" $pageUrl "version" $version ) }}
 
 <span class="docs-nav-section">
   SPIRE

pull_external.py

@@ -120,17 +120,21 @@ def _get_file_content(filename: str, remove_heading=False) -> Tuple[str, str]:
     with open(filename, "r") as f:
         raw = f.readlines()
         if not remove_heading:
-            return "".join(raw)
+            return "".join(raw), None
 
-        heading = None
+        # Find and remove only the first heading line (the title)
         for i in range(len(raw)):
             if raw[i].startswith("#"):
                 heading = RE_EXTRACT_TITLE.match(raw[i]).group("title")
                 heading = '"' + heading.replace('"', '\\"') + '"'
-                continue
+                # Return everything after this first heading line
+                return "".join(raw[i + 1:]).lstrip('\n'), heading
+            # Skip blank lines at the start
+            if raw[i].strip() != "":
+                # Non-blank, non-heading line - no title to strip
+                return "".join(raw), None
 
-            if not raw[i].startswith("#") and not raw[i].strip() == "":
-                return "".join(raw[i:]), heading
+        return "".join(raw), None
 
 
 def _generate_yaml_front_matter(front_matter: Dict = {}) -> List[str]:
@@ -274,6 +278,14 @@ def _copy_file(
             front_matter = {**front_matter, **transform_file.get("frontMatter", {})}
             beacon = transform_file.get("beacon", None)
 
+        # Add external source URL for linking back to canonical source
+        branch = _get_branch_by_repo_url(source, source_branch)
+        external_source_url = "{}/blob/{}/{}".format(source, branch, rel_path_to_source_file)
+        if front_matter:
+            front_matter["externalSource"] = external_source_url
+        else:
+            front_matter = {"externalSource": external_source_url}
+
         if front_matter:
             target_file.writelines(_generate_yaml_front_matter(front_matter))