adobe / hugo-spectrum

Hugo theme using Adobe coral-spectrum

Adobe Coral Spectrum hugo theme

Hugo theme using Adobe coral-spectrum Web Components following Spectrum design patterns.

Usage

See exampleSite for a sample docs website.

A live demo is available at: https://opensource.adobe.com/hugo-spectrum/

Maintainers Notice

Test exampleSite using local theme

Run the site using the local theme, i.e. --theme hugo-spectrum which is mapped to local theme folder and not github remote module.

./docs-local.sh

Update coral-spectrum version

This theme is using adobe/coral-spectrum Web Components.

To upgrade coral-spectrum follow these steps:

set -e
#get the package tarball url
wget `npm view @adobe/coral-spectrum dist.tarball`
tar xzvf coral-spectrum-*.tgz
cp package/dist/css/coral.min.css static/css/coral.min.css
cp package/dist/js/coral.min.js* static/js/
cp package/dist/resources/spectrum-* static/resources/
rm -rf coral-spectrum-*.tgz package

# commit to git
git add .
git commit

See also https://github.com/adobe/coral-spectrum/#using-coral-spectrum for full details.

Update mermaid version

This theme has support for Mermaid diagrams. To upgrade mermaid follow these steps:

set -e
#get the package tarball url
wget `npm view mermaid dist.tarball`
tar xzvf mermaid-*.tgz
cp package/dist/mermaid.min.js* static/js/
rm -rf mermaid-*.tgz package

# commit to git
git add .
git commit

Update markdeep version

This theme has support for Markdeep diagrams. To upgrade markdeep follow these steps:

set -e
#get js
wget https://casual-effects.com/markdeep/latest/markdeep.min.js -O static/js/markdeep.min.js

# commit to git
git add .
git commit

Update stork version

This theme has support for Stork search. To upgrade Stork follow these steps:

set -e

# update version and run
./download-stork.sh 

# commit to git
git add .
git commit

Update KaTeX version

This theme has support for MathJax math typesetting. To upgrade MathJax follow these steps:

set -e
#get the package tarball url
wget `npm view mathjax dist.tarball`
tar xzvf mathjax-*.tgz
cp package/es5/tex-svg-full.js static/js/mathjax-tex-svg-full.js
rm -rf mathjax-*.tgz package

# commit to git
git add .
git commit

Update exampleSite demo site

Run publish-to-gh-pages.sh

Acknowledgments

Docsy inspired layout for this theme. Overleaf examples for LaTeX

Theme built with:

• Spectrum CSS open-source implementation of Spectrum, Adobe’s design system.
• Coral Spectrum JavaScript library of Web Components following Spectrum design patterns.
• Markdeep diagrams
• Mermaid a Javascript based diagramming and charting tool
• Fusejs a lightweight fuzzy-search in JavaScript
• Swagger UI UI for visualizing APIs written in OpenAPI Specification
• klakegg/hugo minimal Docker images for Hugo with batteries included
• Stork Impossibly fast web search, made for static sites
• mark.js JavaScript keyword highlighter
• MathJax Beautiful and accessible math in all browsers
• Zalando Tech Radar JS library for generating tech radar visualisation.

Contributing

Contributions are welcomed! Read the Contributing Guide for more information.

Licensing

This project is licensed under the Apache V2 License. See LICENSE for more information.

hugo-spectrum's Issues

Mobile friendly version of the theme

Expected Behaviour

The site using this theme should render on mobile.
Currently the theme partially supports mobile devices.

table scroll bar only at the bottom of the table

🙋 Feature Request

I am attempting to add a fairly large table using the coral table class to a page. If it fully displays, it has 18 columns. However, unless my browser window is really wide, it gets truncated on the right side, and a scroll bar appears at the bottom. Since the bottom of the table might be out of sight, I would like some more options for how to display.

🤔 Expected Behavior

I'd like one of several other behaviors to be possible, ideally where I can pick which works best for my site after looking at each.

1. an option to make the table fixed width, and scale the text down in size to fit.
2. display the horizontal scroll bar at both top and bottom of the table, not just the bottom
3. display a floating scroll bar

😯 Current Behavior

the scroll bar is only at the very bottom of the table, and may be out of sight. I have to scroll to the bottom to realize there is more data to the right, especially if it happens to truncate between columns such that there is no visual indication that I should scroll. ### Reproduce Scenario (including but not limited to)

Steps to Reproduce

I added the following short code to a hugo site after enabling the theme:

officium:EvonyTKRTips luke$ cat layouts/shortcodes/sp-table.html 
{{- with .Get "class" -}} {{- $newclass := . -}}{{- end -}}
{{- with .Get "csv" -}} {{- $csv_name := . -}} 
{{- printf "<!-- filename is %s -->\n" $csv_name | safeHTML -}}
{{- $rows := resources.Get $csv_name | transform.Unmarshal -}}
{{- $r1 := first 1 $rows -}}
{{- $r2 := first 1 (after 1 $rows) -}}
{{- $data := newScratch -}}
{{- $typeIsBool := false -}}
{{- $typeIsNumber := false -}}

{{- $data.Set "htmlTable" "<!-- start of Coral Table -->\n" -}}
{{- $data.Add "htmlTable" "  <table is=\"coral-table\">\n" -}}
  {{- range $r1 -}}
    {{- $data.Add "htmlTable" "  <colgroup >\n" -}}
    {{- range $r2 -}}
      {{- range $i, $v := . -}}
			  {{- printf "<!-- found column with content: %s -->\n" $v | safeHTML -}}
				{{- if findRE "[^.0-9]" $v -}}
				  {{- if or (eq $v "true") (eq $v "false") -}}
					  {{- printf "<!-- matched as bool -->\n" | safeHTML -}}
			      {{- $data.Add "htmlTable" "    <col is=\"coral-table-column\" sortable=\"\" " -}}
            {{- $data.Add "htmlTable" "sortabletype=\"alphanumeric\" " -}}
			      {{- $data.Add "htmlTable" ">\n" -}}
            {{- $data.SetInMap "r" (string $i) "bool" -}}
					{{- else -}}
            {{- $data.SetInMap "r" (string $i) "string" -}}
			      {{- $data.Add "htmlTable" "    <col is=\"coral-table-column\" sortable=\"\" " -}}
			      {{- $data.Add "htmlTable" ">\n" -}}
					{{- end -}}
				{{- else -}}
				  {{- printf "<!-- matched as number -->\n" | safeHTML -}}
			    {{- $data.Add "htmlTable" "    <col is=\"coral-table-column\" sortable=\"\" " -}}
          {{- $data.Add "htmlTable" "sortabletype=\"number\" " -}}
				  {{- $data.Add "htmlTable" ">\n" -}}
          {{- $data.SetInMap "r" (string $i) "number" -}}
				{{- end -}}
			{{ end }}
		{{ end }}
  {{- $data.Add "htmlTable" "  </colgroup >\n" -}}
  {{ end }}
  {{- $data.Add "htmlTable" "  <thead is=\"coral-table-head\">\n" -}}
		{{- $data.Add "htmlTable" "  <tr is=\"coral-table-row\">\n" -}}
		{{- range first 1 $rows -}}
      {{- range . -}}
     	  {{- $data.Add "htmlTable" "    <th is=\"coral-table-headercell\">\n" -}}
          {{- $data.Add "htmlTable" (. | markdownify )  -}}
        {{- $data.Add "htmlTable" "\n    </th>\n" -}}
			{{- end -}}
		{{- end -}}
		{{- $data.Add "htmlTable" "  </tr>\n" -}}
	{{- $data.Add "htmlTable" "  </thead>\n" -}}
  {{- $data.Add "htmlTable" "  <tbody is=\"coral-table-body\" divider=\"column\">\n" -}}
		{{- range after 1 $rows -}}
		  {{- $data.Add "htmlTable" "  <tr is=\"coral-table-row\">\n" -}}
				{{- range $i, $c := . -}}
  				{{- if eq (index ($data.Get "r") (string $i)) "number" -}} 
	  				{{- $data.Add "htmlTable" (printf "   <td is=\"coral-table-cell\" value=\"%s\" " $c) -}}
					{{ else }}
            {{- $data.Add "htmlTable" "   <td is=\"coral-table-cell\" " -}}
					{{ end }}
					{{- if (eq $i  0) -}}
						{{- $data.Add "htmlTable" "role=\"rowheader\" " -}}
					{{- end -}}
					{{- $data.Add "htmlTable" ">\n" -}}
						{{- $data.Add "htmlTable" ( markdownify $c ) -}}
			    {{- $data.Add "htmlTable" "\n   </td>\n" -}}
				{{- end -}}
  		{{- $data.Add "htmlTable" "  </tr>\n" -}}
		{{- end -}}
  {{- $data.Add "htmlTable" "  </tbody>\n" -}}
{{- $data.Add "htmlTable" "  </table>\n" -}}
{{- $data.Get "htmlTable" | safeHTML -}}
{{- else -}} 
	{{- errorf "missing value for param 'csv': %s" .Position -}}
{{- end -}}
officium:EvonyTKRTips luke$ 

I used that on an 18 column csv file. Other than the first column, and the header, which ends up fixed at about 6 characters wide, which contains a name, each column contains either a leter grade (A+, A, B+, B...), a number grade (100%, 90% ...), or a rank from 1 to n (max 3 digits). so the header is determining the width of the columns.
"yellows rank" "yellows grade" "yellows score" gets wrapped at the space and ends up with a 7 character wide column for 2-4 character wide data.

Platform and Version

officium:EvonyTKRTips luke$ npx hugo version
hugo v0.111.3-5d4eb5154e1fed125ca8e9b5a0315c4180dab192+extended darwin/arm64 BuildDate=2023-03-12T11:40:50Z VendorInfo=gohugoio
officium:EvonyTKRTips luke$

with a fresh git clone of the theme.

Sample Code that illustrates the problem

See above.

Logs taken while reproducing problem

Does this theme or Coral Spectrum or Spectrum Web Components support modern footers?

Great work on this theme! Does this theme have any shortcuts or does the underlying Coral Spectrum design system have any web components that would definitively describe, through the design system, what a page footer should look and how it should act? Creating it using custom styles and such are possible but I was curious if there was an opinionated view from

For example, Footer templates shows many common styles that one would see on modern websites and if there was a way to supply the links and automatically get layouts though hugo-spectrum theme that would be ideal. If it's not in the theme but there are either <coral-*> other web components that we could use to create our own shortcuts or Hugo partials that would be great, too.

We're looking forward to some guidance.

Thanks!

index page has overlapping content when site menus references long pages

Expected Behaviour

Page displays legibly

Actual Behaviour

text overlaps and renders illegibly

Reproduce Scenario (including but not limited to)

Steps to Reproduce

set up a .Site.Menus.main that references pages that have several long paragraphs of text on them. See that the text in the pages overlap.

Platform and Version

officium:EvonyTKRTips luke$ npx hugo version
hugo v0.111.3-5d4eb5154e1fed125ca8e9b5a0315c4180dab192+extended darwin/arm64 BuildDate=2023-03-12T11:40:50Z VendorInfo=gohugoio
officium:EvonyTKRTips luke$

Sample Code that illustrates the problem

this is entirely dependent on what the

    {{ range .Site.Menus.main }}

in

hugo-spectrum/layouts/index.html 

finds.

Logs taken while reproducing problem

Version theme module

Expected Behaviour

Theme is recommended to be included as hugo module.
For downstream users we should version the theme module so they can reference a stable version.

Actual Behaviour

Currently - latest tip of the master is used.

Top Nav Menu showing wrong item selected

Expected Behaviour

The correct item will be selected

Actual Behaviour

the first item is always selected

Reproduce Scenario (including but not limited to)

set up a site using this theme with the file
config/_default/menus/menus.en.tolm
and content

[[main]]
  name = "Generals"
  url = "/generals"
  weight = 10

[[main]]
  name = "Monsters"
  url = "/monsters"
  weight = 20

[[main]]
  name = "SvS"
  url = "/svs"
  weight = 30

[[main]]
  name = "Reference"
  url = "/reference"
  weight = 100

Steps to Reproduce

1. navigate to any section
2. observe that Generals is selected
3. navigate to any other section
4. observe that Generals is still selected

Platform and Version

Sample Code that illustrates the problem

the problem is in navbar.html

{{ range .Site.Menus.main }}

{{ $active := or ($p.IsMenuCurrent "main" .) ($p.HasMenuCurrent "main" .) }}
{{ with .Page }}
{{ $active = or $active ( $.IsDescendant .)  }}

the first or will always be true if I define a main menu at all. Once that is true, the second or will be testing

true or $.IsDecendant

which of course is always true as well.

I'm still trying to think up the proper set of tests.

Auto publish sample site on master commit

Update partials/navbar.html to use variable for header icon

This is a great theme and I'm enjoying using it. One thing that seems to be hard-coded is the icon in the header and I was curious if it possible to change the following:

<a is="coral-shell-homeanchor" icon="AdobeLogo" href="{{ .Site.Home.RelPermalink }}">{{ .Site.Title }}</a>

to

<a is="coral-shell-homeanchor" icon="{{ .Site.HeaderIcon }}" href="{{ .Site.Home.RelPermalink }}">{{ .Site.Title }}</a>

The actual variable {{ .Site.HeaderIcon }} could be whatever makes sense to the developers. Any chance we could add some configurability to the navigation bar? Thanks!

Add a github action to publish the exampleSite to gh-pages branch

Expected Behaviour

When changes are performed to either the theme or the exampleSite content we should automatically publish demo site to gh-pages