Merge pull request #14 from SPANDigital/PRSDM-6839

feat: PRSM-6839 add snippet output format for standalone/embeddable articles
SPANDigital · Jan 21, 2025 · bb03fdb · bb03fdb
2 parents c741364 + 3e50d86
commit bb03fdb
Show file tree

Hide file tree

Showing 8 changed files with 105 additions and 1 deletion.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1 +1,3 @@
-COMING SOON . . . 
+## 2025-01-21
+### Feature
+- Add Snippet output for standalone articles in isolated contexts. @DustinFischer https://spandigital.atlassian.net/browse/PRSDM-7122
diff --git a/README.md b/README.md
@@ -1,3 +1,30 @@
 # presidium-layouts-base
 Base Hugo layouts for Presidium
 
+## Custom Output Formats
+
+### Snippets
+
+The `Snippet` output format is a alternative HTML output format to the standard output  (`index.html`) for _pages_ and _sections_. It's intended for generating standalone articles that can be used in third-party/isolated contexts (such as in an `iframe`).
+
+Features of a snippet:
+ - Generates content from the `content/` directory.
+ - Uses the same stylesheets as the standard output.
+ - Excludes inter-host navigation contexts that are in the standard output, such as the toolbar and left sidebar.
+ - Includes breadcrumbs to ancestor snippets for limited navigation within the docset.
+
+**Usage**  
+
+Snippet outputs must be configured per docset repository in `config.yml`.
+
+```yaml
+# <my-docset>/config.yml
+...
+outputs:
+  page:
+    - html      # -> index.html
+    - snippet   # -> snippet.html
+  section:
+    - html      # -> index.html
+    - snippet   # -> snippet.html
+```
diff --git a/config.yml b/config.yml
@@ -19,6 +19,11 @@ outputformats:
   Compendium:
     baseName: compendium
     mediaType: application/json
+  Snippet:
+    basename: snippet
+    mediaType: text/html
+    isHtml: true
+    permalinkable: true
 outputs:
   home:
     - Navigation

diff --git a/layouts/_default/baseof.html b/layouts/_default/baseof.html
@@ -26,15 +26,18 @@
     {{ end }}
 
     {{ if $.Site.Params.lazyLoad }}
+    {{ block "scripts" . }}
       {{ $url := urls.Parse .Site.BaseURL }}
       {{ $url = path.Clean $url.Path }}
       {{ $navUrl := path.Join $url "/navigation.js"  }}
       <script src="{{$navUrl}}"></script>
     {{ end }}
+    {{ end }}
 </head>
 
 <body id="presidium" {{ partial "page/attributes" . }}>
     {{ if $.Site.Params.enterprise_enabled }}
+    {{ block "toolbar" . }}
       <div class="toolbar-wrapper">
         <button class="toggle">
           <span class="sr-only">Toggle navigation</span>
@@ -50,6 +53,7 @@
         ></div>
       </div>
     {{ end }}
+    {{ end }}
 
     <div class="content-wrapper">
       {{ block "left-sidebar" . }}
@@ -67,6 +71,7 @@
 
       <div id="presidium-container" class="container-fluid">
           <div class="row">
+            {{ block "breadcrumbs" .}}{{ end }}
               <div id="presidium-content">
                   {{ block "header" . }}{{ end }}
                   <section data-section="{{ strings.TrimPrefix "/" .Path }}">

diff --git a/layouts/_default/list.snippet.html b/layouts/_default/list.snippet.html
@@ -0,0 +1,25 @@
+{{ define "scripts" }}
+    {{ partial "common/dummy" . }}
+{{ end }}
+
+{{ define "toolbar" }}
+    {{ partial "common/dummy" . }}
+{{ end }}
+
+{{ define "left-sidebar" }}
+    {{ partial "common/dummy" . }}
+{{ end }}
+
+{{ define "breadcrumbs" }}
+    {{ .Scratch.Set "output-format" "snippet" }}
+    {{ partial "page/breadcrumbs" . }}
+{{ end }}
+
+{{ define "header" }}
+    {{ .Scratch.Set "scope" "list" }}
+    {{ partial "page/header" . }}
+{{ end }}
+
+{{ define "content" }}
+    {{ partial "page/list" . }}
+{{ end }}
diff --git a/layouts/_default/single.snippet.html b/layouts/_default/single.snippet.html
@@ -0,0 +1,25 @@
+{{ define "scripts" }}
+    {{ partial "common/dummy" . }}
+{{ end }}
+
+{{ define "toolbar" }}
+    {{ partial "common/dummy" . }}
+{{ end }}
+
+{{ define "left-sidebar" }}
+    {{ partial "common/dummy" . }}
+{{ end }}
+
+{{ define "breadcrumbs" }}
+    {{ .Scratch.Set "output-format" "snippet" }}
+    {{ partial "page/breadcrumbs" . }}
+{{ end }}
+
+{{ define "header" }}
+    {{ .Scratch.Set "scope" "single" }}
+    {{ partial "page/header" . }}
+{{ end }}
+
+{{ define "content" }}
+    {{ partial "article/root" . }}
+{{ end }}
diff --git a/layouts/partials/common/dummy.html b/layouts/partials/common/dummy.html
@@ -0,0 +1 @@
+{{/* a dummy template to force block overrides with no content */}}
diff --git a/layouts/partials/page/breadcrumbs.html b/layouts/partials/page/breadcrumbs.html
@@ -0,0 +1,14 @@
+{{- $outputFormat := $.Scratch.Get "output-format" -}}
+<div aria-label="breadcrumb" class="breadcrumb">
+    <li><a href="{{.Site.BaseURL}}"{{if $outputFormat}} target="_blank" rel="noopener"{{end}}>{{ .Site.Title }}</a></li>
+    {{- range $index, $ancestor := .Ancestors.Reverse -}}
+    {{ if $outputFormat -}}
+    {{ with $ancestor.OutputFormats.Get $outputFormat -}}
+    <li><a href="{{ $ancestor.RelPermalink }}">{{ $ancestor.LinkTitle }}</a></li>
+    {{- end }}
+    {{- end }}
+    {{ else }}
+    <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+    {{ end -}}
+    <li class="active">{{ .LinkTitle }}</li>
+</div>
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		{{/* a dummy template to force block overrides with no content */}}