Merge branch 'joeroe:main' into main

.github/workflows/gh-pages.yml → .github/workflows/hugo-build-exampleSite.yml

@@ -1,4 +1,4 @@
-name: github pages
+name: hugo build
 
 on:
   push:

NEWS.md

@@ -1,5 +1,25 @@
 # risotto (development version)
 
+* **Breaking change:** The config parameter `logo` now expects a character, e.g. an emoji or Unicode symbol.
+  * For the old behaviour, use `logo_image`
+* Fixed invalid HTML in header nav
+
+# risotto 0.4.0
+
+* Added descriptions to sidebar of list pages, where defined in the frontmatter of `_index.md` (#55)
+* Made sidebar sticky, avoiding overflow for long tables of contents (#51)
+* Added convenience classes for colours, e.g. `.base00` and `.bg-base00`.
+* Fixed overflow of code blocks with line numbers (#41)
+* Fixed invalid HTML in page header (#64)
+* Updated FontAwesome to 6.5.1 (#63)
+  * Please note that future versions will probably not include FontAwesome by default
+* Updated Academicons to 1.9.4 (#63)
+  * Please note that future versions will probably not include Academicons by default
+
+# risotto 0.3.0
+
+* Added support for favicons (#57)
+
 # risotto 0.2.0
 
 * **Breaking change** – new framework for colour palettes:

README.md

@@ -1,23 +1,35 @@
-# risotto
+# 🍚 risotto
 
 risotto is a minimalist, responsive [hugo](https://gohugo.io) theme inspired by terminal ricing aesthetics.
 
+[![Hugo Themes](https://img.shields.io/badge/Hugo_Themes-risotto-blue?logo=hugo)](https://themes.gohugo.io/themes/risotto/)
+[![Version](https://img.shields.io/badge/semver-v0.4.0-blue)](https://semver.org)
+![hugo build status](https://github.com/joeroe/risotto/actions/workflows/hugo-build-exampleSite.yml/badge.svg)
+[![W3C Validation](https://img.shields.io/w3c-validation/html?targetUrl=https%3A%2F%2Frisotto.joeroe.io)](https://validator.nu/?doc=https%3A%2F%2Frisotto.joeroe.io)
+![Code size](https://img.shields.io/github/languages/code-size/joeroe/risotto)
+
 ![Screenshot of the risotto theme](https://raw.githubusercontent.com/joeroe/risotto/master/images/screenshot.png)
 
-## Install
+## Features
 
-The easiest way to install the theme is to clone this repository into your site's `themes` directory:
+* Plain, semantic HTML with no Javascript
+* Plain CSS – no frameworks, no preprocessors, just simple and easy-to-customise stylesheets
+* Uses [CSS Grid](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_grid_layout) for native responsive behaviour without arbitrary breakpoints
+* Comes with [16 built-in colour schemes](#colour-schemes) based on popular terminal themes plus the ability to use custom themes using the [base16 system](https://github.com/monicfenga/base16-styles)
 
-```shell
-git clone https://github.com/joeroe/risotto themes/risotto
-```
+## Install
 
-If your site is already a git repository, you can add the theme as a submodule instead:
+The easiest way to install the theme is to [download the latest release](https://github.com/joeroe/risotto/releases/tag/release) and extract it to your project's `themes/` directory.
+You can also clone this repository into your site's `themes` directory and checkout the latest release:
 
 ```shell
-git submodule add https://github.com/joeroe/risotto.git themes/risotto
+git clone https://github.com/joeroe/risotto themes/risotto && cd themes/risotto
+git checkout $(git tag -l | grep '^v[0-9.]*$' | sort -V | tail -n 1)
 ```
 
+Note that this will not work if your site is itself a git repository.
+In that case, you can add the theme as a [git submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules), but this is not recommended due to the difficulty of tracking a specific release.
+
 ## Update
 
 If you installed the theme using `git clone`, pull the repository to get the latest version:
@@ -27,19 +39,15 @@ cd themes/risotto
 git pull
 ```
 
-Or, if you added it as a git submodule:
-
-```shell
-git submodule update --remote
-```
+Otherwise, simply [download the latest release](https://github.com/joeroe/risotto/releases/tag/release) and extract it to your project's `themes/` directory, replacing the old version.
 
 ## Configure
 
-To use the theme, add `theme = risotto` to your site's `config.toml` or `config.yaml`.
+To use the theme, add `theme = 'risotto'` to your site's `config.toml`, or `theme: risotto` to your `config.yaml`.
 
 See `exampleSite/config.toml` for the theme-specific parameters you need to add to your site's `config.toml` or `config.yaml` to configure the theme.
 
-### Colour palettes
+### Colour schemes
 
 risotto uses the [base16 framework](https://github.com/chriskempson/base16) to define colour schemes that can be used with the `theme.palette` parameter.
 A selection of 16 palettes (10 dark, 6 light) are bundled with the theme: `apprentice`, `base16-dark`, `base16-light`, `dracula`, `gruvbox-dark`, `gruvbox-light`, `material`, `papercolor-dark`, `papercolor-light`, `solarized-dark`, `solarized-light`, `tender`, `tokyo-night-dark`, `tokyo-night-light`, `windows-95` and `windows-95-light`.
@@ -51,24 +59,50 @@ The easiest way to use other base16 styles is to place .css file from https://gi
 
 Or to define a wholly custom theme, you will need to define the following CSS variables for the following base16 colours (see [base16-dark.css](blob/main/static/css/palettes/base16-dark.css) for an example):
 
-| Base | Default colour | Used for | Examples |
-| ---- | -------------- | -------- | -------- |
-| 00   | Dark           | Background | Page background          |
-| 01   | │              | Alt. background | Content background          |
-| 02   | │              | In-text backgrounds | `<pre>`, `<code>`, `<kbd>`, `<samp>` |
-| 03   | │              | Muted text | `:before` & `:marker` symbols |
-| 04   | │              | Alt. foreground | Aside text          |
-| 05   | │              | Foreground         | Content text         |
-| 06   | │              |          |          |
-| 07   | Light          |          |          |
-| 08   | Red            |          |          |
-| 09   | Orange         |          |          |
-| 0A   | Yellow         | Highlights | Selected text, `<mark>` |
-| 0B   | Green          | Primary accent | Logo          |
-| 0C   | Cyan           | Active links | `a:active`, `a:hover`         |
-| 0D   | Blue           | Links    | `a:link`, `a:visited`         |
-| 0E   | Magenta        |          |          |
-| 0F   | Brown          |          |          |
+| Base | Default colour                             | Used for            | Examples                             |
+| ---- | ------------------------------------------ | ------------------- | ------------------------------------ |
+| 00   | <span class="base00">Dark</span>           | Background          | Page background                      |
+| 01   | <span class="base01">│</span>              | Alt. background     | Content background                   |
+| 02   | <span class="base02">│</span>              | In-text backgrounds | `<pre>`, `<code>`, `<kbd>`, `<samp>` |
+| 03   | <span class="base03">│</span>              | Muted text          | `:before` & `:marker` symbols        |
+| 04   | <span class="base04">│</span>              | Alt. foreground     | Aside text                           |
+| 05   | <span class="base05">│</span>              | Foreground          | Content text                         |
+| 06   | <span class="base06">│</span>              |                     |                                      |
+| 07   | <span class="base07">Light</span>          |                     |                                      |
+| 08   | <span class="base08">Red</span>            |                     |                                      |
+| 09   | <span class="base09">Orange</span>         |                     |                                      |
+| 0A   | <span class="base0A">Yellow</span>         | Highlights          | Selected text, `<mark>`              |
+| 0B   | <span class="base0B">Green</span>          | Primary accent      | Logo                                 |
+| 0C   | <span class="base0C">Cyan</span>           | Active links        | `a:active`, `a:hover`                |
+| 0D   | <span class="base0D">Blue</span>           | Links               | `a:link`, `a:visited`                |
+| 0E   | <span class="base0E">Magenta</span>        |                     |                                      |
+| 0F   | <span class="base0F">Brown</span>          |                     |                                      |
 
 For light mode palettes, the sequence of 00–07 should be reversed (light to dark, not dark to light).
 Note that not all colours are currently used in the theme.
+
+You you use these colours directly in content using the convenience classes `.baseXX` and `.bg-baseXX`.
+For example:
+
+```html
+<span class="base0A">Yellow text</span>
+<mark class="base0D">Text highlighted in green</mark>
+```
+
+## Favicon
+
+risotto will automatically use favicons placed in the `static/` directory.
+The following files will be detected and included in your site's `<head>` section:
+
+* `favicon.ico`
+* `favicon-16x16.png`
+* `favicon-32x32.png`
+* `apple-touch-icon.png`
+* `site.webmanifest`
+
+You can generate these from an image or emoji using [favicon.io](https://favicon.io/) or a similar service.
+They must be placed directly under your site's `static/` directory, i.e. not in in a subdirectory or `themes/risotto/static/`.
+
+## Acknowledgements
+
+The 'cooked rice' emoji used as a favicon for the example site was created by the [Twemoji project](https://twemoji.twitter.com/) and is licensed under [CC-BY 4.0](https://creativecommons.org/licenses/by/4.0/).

exampleSite/config.toml

@@ -2,7 +2,7 @@ baseURL = "https://risotto.joeroe.io"
 theme = "risotto"
 title = "risotto demo"
 author = "Joe Roe"
-copyright = "© 2021–2022 [Joe Roe](https://joeroe.io) & [risotto contributors](https://github.com/joeroe/risotto/graphs/contributors)."
+copyright = "© [Joe Roe](https://joeroe.io) & [risotto contributors](https://github.com/joeroe/risotto/graphs/contributors)."
 paginate = 3
 languageCode = "en"
 DefaultContentLanguage = "en"
@@ -24,7 +24,10 @@ palette = "base16-dark"
 [params.about]
 title = "risotto"
 description = "A [hugo](https://gohugo.io) theme inspired by terminal ricing."
-logo = "images/rice.svg"
+# unicode/emoji logo:
+logo = "🍚"
+# or use an image:
+#logo_image = "images/rice.svg"
 
 # Sidebar: social links
 # Available icon sets:

exampleSite/content/post/_index.md

@@ -2,5 +2,6 @@
 aliases = ["posts", "articles", "blog", "showcase", "docs"]
 title = "Posts"
 author = "Hugo Authors"
+description = "Example posts demonstrating hugo's markup features"
 tags = ["index"]
 +++

exampleSite/content/post/markdown-syntax.md

@@ -14,6 +14,7 @@ categories = [
 ]
 series = ["Themes Guide"]
 aliases = ["migrate-from-jekyl"]
+toc = true
 +++
 
 This article offers a sample of basic Markdown syntax that can be used in Hugo content files, also it shows whether basic HTML elements are decorated with CSS in a Hugo theme.

exampleSite/static/README

@@ -0,0 +1,6 @@
+The favicons in this directory were generated using the following graphics from Twitter Twemoji:
+
+- Graphics Title: 1f35a.svg
+- Graphics Author: Copyright 2020 Twitter, Inc and other contributors (https://github.com/twitter/twemoji)
+- Graphics Source: https://github.com/twitter/twemoji/blob/master/assets/svg/1f35a.svg
+- Graphics License: CC-BY 4.0 (https://creativecommons.org/licenses/by/4.0/)

exampleSite/static/site.webmanifest

@@ -0,0 +1 @@
+{"name":"","short_name":"","icons":[{"src":"/android-chrome-192x192.png","sizes":"192x192","type":"image/png"},{"src":"/android-chrome-512x512.png","sizes":"512x512","type":"image/png"}],"theme_color":"#ffffff","background_color":"#ffffff","display":"standalone"}

layouts/_default/list.html

@@ -10,3 +10,7 @@ <h1 id="{{ .Title | urlize }}">{{ .Title | markdownify }}</h1>
     </ul>
 
 {{ end }}
+
+{{define "aside" }}
+    {{ if .Params.description }}<p>{{ .Params.description }}</p>{{ end }}
+{{ end }}

layouts/_default/single.html

@@ -2,10 +2,6 @@
     <header class="content__header">
         <h1>{{ .Title | markdownify }}</h1>
     </header>
-    {{ if .Params.toc }}
-    <aside>
-    </aside>
-    {{ end }}
     <div class="content__body">
         {{ .Content }}
     </div>

layouts/partials/about.html

@@ -1,6 +1,7 @@
 {{ with .Site.Params.about }}
 <div class="aside__about">
-    {{ with .logo }}<img class="about__logo" src="{{ . | absURL }}" alt="Logo">{{ end }}
+    {{ with .logo }}<span class="about__logo" role="img">{{ . }}</span>&nbsp;{{ end }}
+    {{ with .logo_image }}<img class="about__logo" src="{{ . | absURL }}" alt="Logo">{{ end }}
 <h1 class="about__title">{{ .title }}</h1>
 {{ with .description }}<p class="about__description">{{ . | markdownify }}</p>{{ end }}
 </div>

layouts/partials/head.html

@@ -6,12 +6,19 @@
 {{ if .Site.Params.noindex }}<meta name="robots" content="noindex" /> {{ end }}
 
 <!-- FontAwesome <https://fontawesome.com/> -->
-<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.1.2/css/all.min.css" integrity="sha512-1sCRPdkRXhBV2PBLUdRb4tMg1w2YPf37qatUFeS7zlBy7jJI8Lf4VHwWfZZfpXtYSLy85pkm9GaYVYMfw5BC1A==" crossorigin="anonymous" />
+<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.1/css/all.min.css" integrity="sha512-DTOQO9RWCH3ppGqcWaEA1BIZOC6xxalwEsw9c2QQeAIftl+Vegovlnee1c9QX4TctnWMn13TZye+giMm8e2LwA==" crossorigin="anonymous" referrerpolicy="no-referrer" />
 
 <!-- Academicons <https://jpswalsh.github.io/academicons/> -->
-<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/academicons/1.9.1/css/academicons.min.css" integrity="sha512-b1ASx0WHgVFL5ZQhTgiPWX+68KjS38Jk87jg7pe+qC7q9YkEtFq0z7xCglv7qGIs/68d3mAp+StfC8WKC5SSAg==" crossorigin="anonymous" />
+<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/academicons/1.9.4/css/academicons.min.css" integrity="sha512-IW0nhlW5MgNydsXJO40En2EoCkTTjZhI3yuODrZIc8cQ4h1XcF53PsqDHa09NqnkXuIe0Oiyyj171BqZFwISBw==" crossorigin="anonymous" referrerpolicy="no-referrer" />
 
 <!-- risotto theme -->
 <link rel="stylesheet" href="{{ printf "css/palettes/%s.css" (.Site.Params.theme.palette | default "base16-dark") | absURL }}">
 <link rel="stylesheet" href="{{ "css/risotto.css" | absURL }}">
 <link rel="stylesheet" href="{{ "css/custom.css" | absURL }}">
+
+<!-- favicon -->
+{{ if os.FileExists "static/favicon.ico" }}<link rel="icon" href="{{ "favicon.ico" | absURL }}">{{ end }}
+{{ if os.FileExists "static/favicon-32x32.png" }}<link rel="icon" type="image/png" sizes="32x32" href="{{ "favicon-32x32.png" | absURL }}">{{ end }}
+{{ if os.FileExists "static/favicon-16x16.png" }}<link rel="icon" type="image/png" sizes="16x16" href="{{ "favicon-16x16.png" | absURL }}">{{ end }}
+{{ if os.FileExists "static/apple-touch-icon.png" }}<link rel="apple-touch-icon" href="{{ "apple-touch-icon.png" | absURL }}">{{ end }}
+{{ if os.FileExists "static/site.webmanifest" }}<link rel="manifest" href="{{ "site.webmanifest" | absURL }}">{{ end }}

layouts/partials/header.html

@@ -1,6 +1,6 @@
 <nav class="page__nav main-nav">
     <ul>
-    <h1 class="page__logo"><a href="{{ .Site.BaseURL }}" class="page__logo-inner">{{ .Site.Title }}</a></h1>
+      <li class="nomarker"><h1 class="page__logo"><a href="{{ .Site.BaseURL }}" class="page__logo-inner">{{ .Site.Title }}</a></h1></li>
     {{ $currentPage := . }}
     {{ range .Site.Menus.main }}
     <li class="main-nav__item"><a class="nav-main-item{{ if or ($currentPage.IsMenuCurrent "main" .) ($currentPage.HasMenuCurrent "main" .) (eq ($currentPage.Permalink) (.URL | absLangURL)) }} active{{end}}" href="{{ .URL | absLangURL }}" title="{{ .Title }}">{{ .Name }}</a></li>

layouts/post/list.html

@@ -20,3 +20,7 @@ <h1><a href="{{ .Permalink }}">{{ .Title | markdownify }}</a></h1>
     </article>
     {{ end }}
 {{ end }}
+
+{{define "aside" }}
+    {{ if .Params.description }}<p>{{ .Params.description }}</p>{{ end }}
+{{ end }}

static/css/header.css

@@ -3,14 +3,13 @@
     display: flex;
     flex-flow: row wrap;
     justify-content: flex-start;
+    align-items: center;
     margin: 0;
-    padding: 0 0 0.25rem 0;
-    gap: 0rem 1.5rem;
+    padding: 0;
+    gap: 0.5rem 2rem;
 }
 
 .main-nav li {
-    padding-top: 0.25rem;
-    margin-left: 1rem;
     text-transform: lowercase;
 }
 

static/css/typography.css

@@ -101,6 +101,10 @@ ol li::marker {
     color: var(--muted);
 }
 
+li.nomarker {
+    display: block;
+}
+
 dt {
   margin: 0;
   font-weight: bold;
@@ -154,6 +158,12 @@ pre {
     margin: 0 0 1.5rem 0;
 }
 
+/* Fix overflow when config markup.highlight.lineNos is true */
+/* See https://github.com/joeroe/risotto/issues/41 */
+.highlight div {
+	overflow-x: auto;
+}
+
 /* Emphasis */
 b,
 strong {
@@ -213,3 +223,37 @@ img {
     height: auto;
 }
 
+/* Colour classes */
+.base00 { color: var(--base00); }
+.base01 { color: var(--base01); }
+.base02 { color: var(--base02); }
+.base03 { color: var(--base03); }
+.base04 { color: var(--base04); }
+.base05 { color: var(--base05); }
+.base06 { color: var(--base06); }
+.base07 { color: var(--base07); }
+.base08 { color: var(--base08); }
+.base09 { color: var(--base09); }
+.base0A { color: var(--base0A); }
+.base0B { color: var(--base0B); }
+.base0C { color: var(--base0C); }
+.base0D { color: var(--base0D); }
+.base0E { color: var(--base0E); }
+.base0F { color: var(--base0F); }
+
+.bg-base00 { background-color: var(--base00); }
+.bg-base01 { background-color: var(--base01); }
+.bg-base02 { background-color: var(--base02); }
+.bg-base03 { background-color: var(--base03); }
+.bg-base04 { background-color: var(--base04); }
+.bg-base05 { background-color: var(--base05); }
+.bg-base06 { background-color: var(--base06); }
+.bg-base07 { background-color: var(--base07); }
+.bg-base08 { background-color: var(--base08); }
+.bg-base09 { background-color: var(--base09); }
+.bg-base0A { background-color: var(--base0A); }
+.bg-base0B { background-color: var(--base0B); }
+.bg-base0C { background-color: var(--base0C); }
+.bg-base0D { background-color: var(--base0D); }
+.bg-base0E { background-color: var(--base0E); }
+.bg-base0F { background-color: var(--base0F); }

theme.toml

@@ -8,7 +8,6 @@ demosite = "https://risotto.joeroe.io"
 
 tags = ["responsive", "minimal", "dark mode"]
 features = []
-min_version = "0.41.0"
 
 [author]
   name = "Joe Roe"