diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/hugo-build-exampleSite.yml similarity index 97% rename from .github/workflows/gh-pages.yml rename to .github/workflows/hugo-build-exampleSite.yml index f3c41579..3b25641b 100644 --- a/.github/workflows/gh-pages.yml +++ b/.github/workflows/hugo-build-exampleSite.yml @@ -1,4 +1,4 @@ -name: github pages +name: hugo build on: push: diff --git a/NEWS.md b/NEWS.md index a9017be6..f4b87bdc 100644 --- a/NEWS.md +++ b/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: diff --git a/README.md b/README.md index 916601ad..ef82d29d 100644 --- a/README.md +++ b/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 | `
`, ``, ``, `` |
-| 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, `` |
-| 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   | Dark           | Background          | Page background                      |
+| 01   | │              | Alt. background     | Content background                   |
+| 02   | │              | In-text backgrounds | `
`, ``, ``, `` |
+| 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, ``              |
+| 0B   | Green          | Primary accent      | Logo                                 |
+| 0C   | Cyan           | Active links        | `a:active`, `a:hover`                |
+| 0D   | Blue           | Links               | `a:link`, `a:visited`                |
+| 0E   | Magenta        |                     |                                      |
+| 0F   | Brown          |                     |                                      |
 
 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
+Yellow text
+Text highlighted in green
+```
+
+## Favicon
+
+risotto will automatically use favicons placed in the `static/` directory.
+The following files will be detected and included in your site's `` 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/).
diff --git a/exampleSite/config.toml b/exampleSite/config.toml
index be7f40cc..72c001dc 100644
--- a/exampleSite/config.toml
+++ b/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:
diff --git a/exampleSite/content/post/_index.md b/exampleSite/content/post/_index.md
index 8a084d90..e7eb988a 100644
--- a/exampleSite/content/post/_index.md
+++ b/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"]
 +++
diff --git a/exampleSite/content/post/markdown-syntax.md b/exampleSite/content/post/markdown-syntax.md
index 06990d70..dcbab1b1 100644
--- a/exampleSite/content/post/markdown-syntax.md
+++ b/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.
diff --git a/exampleSite/static/.gitignore b/exampleSite/static/.gitignore
deleted file mode 100644
index e69de29b..00000000
diff --git a/exampleSite/static/README b/exampleSite/static/README
new file mode 100644
index 00000000..9c565ef0
--- /dev/null
+++ b/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/)
diff --git a/exampleSite/static/android-chrome-192x192.png b/exampleSite/static/android-chrome-192x192.png
new file mode 100644
index 00000000..dc22f05a
Binary files /dev/null and b/exampleSite/static/android-chrome-192x192.png differ
diff --git a/exampleSite/static/android-chrome-512x512.png b/exampleSite/static/android-chrome-512x512.png
new file mode 100644
index 00000000..fa80ccd8
Binary files /dev/null and b/exampleSite/static/android-chrome-512x512.png differ
diff --git a/exampleSite/static/apple-touch-icon.png b/exampleSite/static/apple-touch-icon.png
new file mode 100644
index 00000000..c5668a34
Binary files /dev/null and b/exampleSite/static/apple-touch-icon.png differ
diff --git a/exampleSite/static/favicon-16x16.png b/exampleSite/static/favicon-16x16.png
new file mode 100644
index 00000000..2ec54d8d
Binary files /dev/null and b/exampleSite/static/favicon-16x16.png differ
diff --git a/exampleSite/static/favicon-32x32.png b/exampleSite/static/favicon-32x32.png
new file mode 100644
index 00000000..047ad4ac
Binary files /dev/null and b/exampleSite/static/favicon-32x32.png differ
diff --git a/exampleSite/static/favicon.ico b/exampleSite/static/favicon.ico
new file mode 100644
index 00000000..7ccf4bb2
Binary files /dev/null and b/exampleSite/static/favicon.ico differ
diff --git a/exampleSite/static/site.webmanifest b/exampleSite/static/site.webmanifest
new file mode 100644
index 00000000..45dc8a20
--- /dev/null
+++ b/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"}
\ No newline at end of file
diff --git a/images/screenshot.png b/images/screenshot.png
index 475685fc..557d55be 100644
Binary files a/images/screenshot.png and b/images/screenshot.png differ
diff --git a/images/tn.png b/images/tn.png
index 2d0e3301..4a21a868 100644
Binary files a/images/tn.png and b/images/tn.png differ
diff --git a/layouts/_default/list.html b/layouts/_default/list.html
index 37742ef4..6966c318 100644
--- a/layouts/_default/list.html
+++ b/layouts/_default/list.html
@@ -10,3 +10,7 @@ 
{{ .Title | markdownify }}

     
 
 {{ end }}
+
+{{define "aside" }}
+    {{ if .Params.description }}
{{ .Params.description }}
{{ end }}
+{{ end }}
diff --git a/layouts/_default/single.html b/layouts/_default/single.html
index 77abf32b..23274edc 100644
--- a/layouts/_default/single.html
+++ b/layouts/_default/single.html
@@ -2,10 +2,6 @@
     

         
{{ .Title | markdownify }}

     

-    {{ if .Params.toc }}
-    
-    {{ end }}
     

         {{ .Content }}
     

diff --git a/layouts/partials/about.html b/layouts/partials/about.html
index 6c6e1bce..aa1dce3a 100644
--- a/layouts/partials/about.html
+++ b/layouts/partials/about.html
@@ -1,6 +1,7 @@
 {{ with .Site.Params.about }}
 

-    {{ with .logo }}{{ end }}
+    {{ with .logo }} {{ end }}
+    {{ with .logo_image }}{{ end }}
 
{{ .title }}

 {{ with .description }}
{{ . | markdownify }}
{{ end }}
 

diff --git a/layouts/partials/head.html b/layouts/partials/head.html
index 45673a50..be872d32 100644
--- a/layouts/partials/head.html
+++ b/layouts/partials/head.html
@@ -6,12 +6,19 @@
 {{ if .Site.Params.noindex }} {{ end }}
 
 
-
+
 
 
-
+
 
 
 
 
 
+
+
+{{ if os.FileExists "static/favicon.ico" }}{{ end }}
+{{ if os.FileExists "static/favicon-32x32.png" }}{{ end }}
+{{ if os.FileExists "static/favicon-16x16.png" }}{{ end }}
+{{ if os.FileExists "static/apple-touch-icon.png" }}{{ end }}
+{{ if os.FileExists "static/site.webmanifest" }}{{ end }}
diff --git a/layouts/partials/header.html b/layouts/partials/header.html
index 45c46ce6..a8893d4b 100644
--- a/layouts/partials/header.html
+++ b/layouts/partials/header.html
@@ -1,6 +1,6 @@