From 5e105c9ff4789c5861dfa01a81e8268d4e7f5260 Mon Sep 17 00:00:00 2001 From: Robert Kaussow Date: Wed, 3 Mar 2021 21:07:59 +0100 Subject: [PATCH] feat: auto-load custom svg sprites from assets folder (#79) BREAKING CHANGE: Build-in icons are prefixed with `gdoc_` now. If you use build-in icons in e.g. menus you have to rename these references! --- .dictionary | 1 + .drone.yml | 4 +- .gitignore | 3 +- exampleSite/assets/sprites/regular.svg | 462 +++++++++++++++++++ exampleSite/content/shortcodes/icon.md | 15 + exampleSite/content/shortcodes/includes.md | 14 +- exampleSite/content/usage/icons.md | 52 +++ exampleSite/content/usage/menus.md | 2 +- exampleSite/data/menu/more.yaml | 6 +- exampleSite/layouts/shortcodes/sprites.html | 12 + exampleSite/static/custom.css | 19 + gulpfile.js | 21 +- layouts/404.html | 2 +- layouts/_default/_markup/render-heading.html | 2 +- layouts/partials/menu-bundle.html | 4 +- layouts/partials/menu-filetree.html | 4 +- layouts/partials/page-header.html | 4 +- layouts/partials/search.html | 2 +- layouts/partials/site-footer.html | 2 +- layouts/partials/site-header.html | 4 +- layouts/partials/svg-icon-symbols.html | 5 +- layouts/posts/list.html | 2 +- layouts/posts/single.html | 2 +- layouts/shortcodes/icon.html | 5 + package-lock.json | 48 ++ package.json | 1 + src/sass/_base.scss | 12 +- src/sass/_mobile.scss | 4 +- src/sass/_utils.scss | 13 + 29 files changed, 688 insertions(+), 39 deletions(-) create mode 100644 exampleSite/assets/sprites/regular.svg create mode 100644 exampleSite/content/shortcodes/icon.md create mode 100644 exampleSite/content/usage/icons.md create mode 100644 exampleSite/layouts/shortcodes/sprites.html create mode 100644 exampleSite/static/custom.css create mode 100644 layouts/shortcodes/icon.html diff --git a/.dictionary b/.dictionary index 3ca794d..606e2fe 100644 --- a/.dictionary +++ b/.dictionary @@ -14,3 +14,4 @@ GPL IcoMoon YAML ok +FontAwesome diff --git a/.drone.yml b/.drone.yml index b6df955..4ea2024 100644 --- a/.drone.yml +++ b/.drone.yml @@ -12,6 +12,7 @@ steps: commands: - npm install > /dev/null - npx gulp default + - npx gulp svg-sprite-list environment: FORCE_COLOR: true NPM_CONFIG_LOGLEVEL: error @@ -91,6 +92,7 @@ steps: commands: - npm install > /dev/null - npx gulp default + - npx gulp svg-sprite-list environment: FORCE_COLOR: true NPM_CONFIG_LOGLEVEL: error @@ -269,6 +271,6 @@ depends_on: --- kind: signature -hmac: 0b3fb338632d237c7279a218b7bd1b3793aeb15cd8382b8c804a5e2da9a30534 +hmac: 14dcf0dc7a6960b86289fd9b6a530c96ed121393661dec857f5fd64c39ded614 ... diff --git a/.gitignore b/.gitignore index 86db449..7f347e5 100644 --- a/.gitignore +++ b/.gitignore @@ -10,7 +10,7 @@ exampleSite/public/ CHANGELOG.md # auto-generated files -layouts/partials/icons-svg-symbols.html +assets/sprites/ assets/*.css static/*.css !static/custom.css @@ -19,6 +19,7 @@ static/favicon/ static/fonts/GeekdocIcons.* resources/ exampleSite/resources/ +exampleSite/data/sprites/ data/assets.json diff --git a/exampleSite/assets/sprites/regular.svg b/exampleSite/assets/sprites/regular.svg new file mode 100644 index 0000000..2edd1f7 --- /dev/null +++ b/exampleSite/assets/sprites/regular.svg @@ -0,0 +1,462 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/exampleSite/content/shortcodes/icon.md b/exampleSite/content/shortcodes/icon.md new file mode 100644 index 0000000..6db31b3 --- /dev/null +++ b/exampleSite/content/shortcodes/icon.md @@ -0,0 +1,15 @@ +Simple shortcode to include icons from SVG sprites outside of menus. + +```tpl +{{}} +``` + +**Example:** + +| Result | Usage | +| -------------------------- | -------------------------------- | +| {{< icon "thumbs-up" >}} | `{{}}` | +| {{< icon "thumbs-down" >}} | `{{}}` | +| {{< icon "laugh" >}} | `{{}}` | +| {{< icon "lemon" >}} | `{{}}` | +| {{< icon "moon" >}} | `{{}}` | diff --git a/exampleSite/content/shortcodes/includes.md b/exampleSite/content/shortcodes/includes.md index fb428b6..6628d3e 100644 --- a/exampleSite/content/shortcodes/includes.md +++ b/exampleSite/content/shortcodes/includes.md @@ -8,16 +8,16 @@ Include shortcode can include files of different types. By specifying a language Attributes: - -| Name | Usage | default | -|---|---|---| -| file | path to the included file relative to the hugo root | empty value | -| language* | language for [syntax highlighting](https://gohugo.io/content-management/syntax-highlighting/#list-of-chroma-highlighting-languages) | empty value | -| markdown | included file is markdown | false | -| options | highlighting [options](https://gohugo.io/content-management/syntax-highlighting/#highlight-shortcode) | linenos=table | +| Name | Usage | default | +| ---------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------- | +| file | path to the included file relative to the hugo root | empty value | +| language\* | language for [syntax highlighting](https://gohugo.io/content-management/syntax-highlighting/#list-of-chroma-highlighting-languages) | empty value | +| markdown | included file is markdown | false | +| options | highlighting [options](https://gohugo.io/content-management/syntax-highlighting/#highlight-shortcode) | linenos=table | \* if not set, the content will be rendered as plain HTML + ### Include \*.yml file with options ```tpl diff --git a/exampleSite/content/usage/icons.md b/exampleSite/content/usage/icons.md new file mode 100644 index 0000000..e8b2d09 --- /dev/null +++ b/exampleSite/content/usage/icons.md @@ -0,0 +1,52 @@ +--- +title: Icons +--- + + + +{{< toc >}} + + + +## Custom icons + +The only supported source for custom icons are SVG sprites. Some icon frameworks provides ready to use sprites e.g. FontAwesome. If the framework don't provide sprites, you can create your own from raw SVG icons. There are a lot of tools available to create sprites, please choose one that fits your need. One solution could be [svgsprit.es](https://svgsprit.es/). + +Regardless of which tool (or existing sprite) you choose, there are a few requirements that must be met: + +1. The sprite must be a valid **SVG** file. +2. You have to ensure to **hide the sprite**. Apply the predefined class `svg-sprite` or `hidden` to the root element of your sprite or add a small piece of inline CSS e.g. `style="display: none;"`. +3. Save the sprite to the folder `assets/sprites` right beside your `content` folder. + +The result of a valid minimal SVG sprite file could look like this: + +```XML + + + + + +``` + +**Example:** + +FontAwesome provides three pre-build sprites included in the regular Web download pack, `sprites/brands.svg`, `sprites/regular.svg` and `sprites/solid.svg`. Choose your sprite to use and copy it to your projects root directory into `assets/sprites`, right beside your `content` folder. The result should look like this: + +```Bash +my_projcet/ +├── assets +│   └── sprites +│   └── regular.svg +├── config.yaml +├── content +│   ├── _index.md +│   ├── ... +``` + +That's it! The theme will auto-load all available SVG sprites provided in the assets folder. To use the icons e.g. in the [bundle menu](/usage/menus/#bundle-menu), you need to lookup the id of the icon. An example would be `thumbs-up` {{< icon "thumbs-up" >}}. There is also a [shortcode](/shortcodes/icon/) available. + +## Build-in icons + +The theme bundles just a small set of hand crafted icons. + +{{< sprites >}} diff --git a/exampleSite/content/usage/menus.md b/exampleSite/content/usage/menus.md index 6e50ff4..5d54a5d 100644 --- a/exampleSite/content/usage/menus.md +++ b/exampleSite/content/usage/menus.md @@ -62,7 +62,7 @@ main: ref: "/level-2/level-2-2" ``` -As an advantage you can add icons to your menu entries e.g. `icon: "notification"`. +As an advantage you can add [icons](/usage/icons/) to your menu entries e.g. `icon: "notification"`. [![Example bundle menu](/media/bundle-menu.png)](/media/bundle-menu.png) diff --git a/exampleSite/data/menu/more.yaml b/exampleSite/data/menu/more.yaml index d06cadb..04d7c61 100644 --- a/exampleSite/data/menu/more.yaml +++ b/exampleSite/data/menu/more.yaml @@ -2,12 +2,12 @@ more: - name: News ref: "/posts" - icon: "notification" + icon: "gdoc_notification" - name: Releases ref: "https://github.com/thegeeklab/hugo-geekdoc/releases" external: true - icon: "download" + icon: "gdoc_download" - name: "View Source" ref: "https://github.com/thegeeklab/hugo-geekdoc" external: true - icon: "github" + icon: "gdoc_github" diff --git a/exampleSite/layouts/shortcodes/sprites.html b/exampleSite/layouts/shortcodes/sprites.html new file mode 100644 index 0000000..fd3a6e0 --- /dev/null +++ b/exampleSite/layouts/shortcodes/sprites.html @@ -0,0 +1,12 @@ +
+ {{ range .Site.Data.sprites.geekdoc }} +
+
+ +
+
+ #gdoc_{{ (replace . "_" "_") | safeHTML }} +
+
+ {{ end }} +
diff --git a/exampleSite/static/custom.css b/exampleSite/static/custom.css new file mode 100644 index 0000000..1cf3314 --- /dev/null +++ b/exampleSite/static/custom.css @@ -0,0 +1,19 @@ +.icon-grid { + width: 8rem; + height: 8rem; + margin: 0.2em; + text-align: center; + padding: 0.3em; +} + +.icon-grid__line { + height: 4rem; +} + +.icon-grid__line .icon { + font-size: 3em; +} + +.icon-grid__line--text { + font-size: 0.8em; +} diff --git a/gulpfile.js b/gulpfile.js index 2a5e74d..97f25ad 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -5,6 +5,7 @@ const cleanCSS = require("gulp-clean-css"); const autoprefixer = require("gulp-autoprefixer"); const iconfont = require("gulp-iconfont"); const clean = require("gulp-clean"); +const filelist = require("gulp-filelist"); const realFavicon = require("gulp-real-favicon"); const path = require("path"); @@ -113,6 +114,9 @@ gulp.task("favicon-check-update", function (done) { gulp.task("svg-sprite", function () { config = { shape: { + id: { + generator: "gdoc_%s", + }, dimension: { maxWidth: 28, maxHeight: 28, @@ -127,14 +131,14 @@ gulp.task("svg-sprite", function () { svg: { xmlDeclaration: false, rootAttributes: { - style: "position: absolute; width: 0; height: 0; overflow: hidden;", + class: "svg-sprite", }, }, mode: { inline: true, symbol: { - dest: "layouts/partials/", - sprite: "svg-icon-symbols.html", + dest: "assets/sprites/", + sprite: "geekdoc.svg", bust: false, }, }, @@ -146,6 +150,15 @@ gulp.task("svg-sprite", function () { .pipe(gulp.dest(".")); }); +gulp.task("svg-sprite-list", function () { + config = { removeExtensions: true, flatten: true }; + + return gulp + .src("src/icons/*.svg") + .pipe(filelist("exampleSite/data/sprites/geekdoc.json", config)) + .pipe(gulp.dest(".")); +}); + gulp.task("iconfont", function () { var lastUnicode = 0xea01; var files = fs.readdirSync("src/iconfont"); @@ -212,6 +225,8 @@ gulp.task("asset-rm", function () { gulp.task("asset", gulp.series("asset-rm", "asset-rev")); +gulp.task("svg", gulp.series("svg-sprite", "svg-sprite-list")); + gulp.task( "default", gulp.series("sass", "svg-sprite", "iconfont", "favicon-generate", "asset") diff --git a/layouts/404.html b/layouts/404.html index a0bf01c..33b88cf 100644 --- a/layouts/404.html +++ b/layouts/404.html @@ -14,7 +14,7 @@
- +
Lost?
diff --git a/layouts/_default/_markup/render-heading.html b/layouts/_default/_markup/render-heading.html index 15411a3..5f86ba8 100644 --- a/layouts/_default/_markup/render-heading.html +++ b/layouts/_default/_markup/render-heading.html @@ -5,7 +5,7 @@ {{ .Text | safeHTML }} - +
diff --git a/layouts/partials/menu-bundle.html b/layouts/partials/menu-bundle.html index 3062749..51c0807 100644 --- a/layouts/partials/menu-bundle.html +++ b/layouts/partials/menu-bundle.html @@ -36,8 +36,8 @@ {{ if $hasCollapse }} - - + + {{ end }} {{ else }} diff --git a/layouts/partials/menu-filetree.html b/layouts/partials/menu-filetree.html index 26eddb5..d78df85 100644 --- a/layouts/partials/menu-filetree.html +++ b/layouts/partials/menu-filetree.html @@ -32,8 +32,8 @@ {{ partial "title" . }} {{ end }} {{ if $hasCollapse }} - - + + {{ end }} diff --git a/layouts/partials/page-header.html b/layouts/partials/page-header.html index 7c3353a..c1a4798 100644 --- a/layouts/partials/page-header.html +++ b/layouts/partials/page-header.html @@ -26,7 +26,7 @@ {{ if (and (not $showBreadcrumb) (not $showEdit)) }} hidden {{ end }}" itemprop="breadcrumb"> {{if $showBreadcrumb }}
- +
    {{ $position := sub (len (split .RelPermalink "/")) 1 }} {{ $name := (partial "title" .) }} @@ -38,7 +38,7 @@ {{ if $showEdit }}
    - + Edit this page diff --git a/layouts/partials/search.html b/layouts/partials/search.html index 52627e1..aa28bb2 100644 --- a/layouts/partials/search.html +++ b/layouts/partials/search.html @@ -1,6 +1,6 @@ {{ if default true .Site.Params.GeekdocSearch }}
    - + diff --git a/layouts/partials/site-footer.html b/layouts/partials/site-footer.html index af2fd89..00f39f0 100644 --- a/layouts/partials/site-footer.html +++ b/layouts/partials/site-footer.html @@ -2,7 +2,7 @@
    Built with Hugo and - + {{ with .Site.Params.GeekdocLegalNotice }} diff --git a/layouts/partials/site-header.html b/layouts/partials/site-header.html index 13f572d..d139676 100644 --- a/layouts/partials/site-header.html +++ b/layouts/partials/site-header.html @@ -2,8 +2,8 @@
    {{ if .MenuEnabled }} {{ end }} diff --git a/layouts/partials/svg-icon-symbols.html b/layouts/partials/svg-icon-symbols.html index 05ff5b4..bca4793 100644 --- a/layouts/partials/svg-icon-symbols.html +++ b/layouts/partials/svg-icon-symbols.html @@ -1 +1,4 @@ - \ No newline at end of file +{{ range resources.Match "sprites/*.svg" }} +{{ printf "" . | safeHTML }} +{{ .Content | safeHTML }} +{{ end }} diff --git a/layouts/posts/list.html b/layouts/posts/list.html index cdbe39d..0198293 100644 --- a/layouts/posts/list.html +++ b/layouts/posts/list.html @@ -4,7 +4,7 @@

    {{ .Title }}

    - +