feat: add optional hint/admonition icons (#383)

BREAKING CHANGE: The types of the `hint` short code have been renamed to `[note|tip|important|caution|warning]` the old types `[info|ok|warning|danger]` are still working, but should be considered as deprecated.

BREAKING CHANGE: The `hint` short code is using named arguments now. You have to change, e.g. `{{< hint warning >}}` to `{{< hint type=warning >}}`.

.drone.yml

@@ -26,7 +26,7 @@ steps:
       NPM_CONFIG_LOGLEVEL: error
 
   - name: testbuild
-    image: thegeeklab/hugo:0.93.2
+    image: thegeeklab/hugo:0.97.3
     commands:
       - mkdir -p exampleSite/themes/ && ln -s $(pwd)/ exampleSite/themes/hugo-geekdoc
       - hugo --panicOnWarning -s exampleSite/ -b http://localhost/
@@ -203,7 +203,7 @@ steps:
         - refs/pull/**
 
   - name: build
-    image: thegeeklab/hugo:0.93.2
+    image: thegeeklab/hugo:0.97.3
     commands:
       - hugo --panicOnWarning -s exampleSite/
 
@@ -284,6 +284,6 @@ depends_on:
 
 ---
 kind: signature
-hmac: bd8e739515bc29102da412272b61aa89cf18f9b4d1f62b502172131a51009c71
+hmac: b43a67b7ebd42ae6e180cd5aaa2ffa9740f7bf649fbf9cfa76c5ea84ae94d8bd
 
 ...

exampleSite/config/_default/config.yaml

@@ -37,3 +37,8 @@ outputs:
     - HTML
   term:
     - HTML
+
+security:
+  exec:
+    allow:
+      - "^asciidoctor$"

exampleSite/content/en/asciidoc/admonition-icons.adoc

@@ -0,0 +1,29 @@
++++
+title = "Admonition Icons"
++++
+
+:icons: font
+
+By default, the admonition is rendered with a plain text label. To enable font icons the document attribute `:icons: font` need to be set.
+
+== Example
+
+[NOTE]
+Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclimates investiture.
+Ornateness bland it ex enc, est yeti am bongo detract re.
+
+[TIP]
+Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclimates investiture.
+Ornateness bland it ex enc, est yeti am bongo detract re.
+
+[IMPORTANT]
+Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclimates investiture.
+Ornateness bland it ex enc, est yeti am bongo detract re.
+
+[CAUTION]
+Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclimates investiture.
+Ornateness bland it ex enc, est yeti am bongo detract re.
+
+[WARNING]
+Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclimates investiture.
+Ornateness bland it ex enc, est yeti am bongo detract re.

exampleSite/content/en/asciidoc/admonitions.adoc

@@ -0,0 +1,72 @@
++++
+title = "Admonitions"
++++
+
+:toc:
+:toclevels: 2
+
+{{< toc >}}
+
+== Admonition types
+
+There are certain statements you may want to draw attention to by taking them out of the content's flow and labeling them with a priority. These are called admonitions.
+
+```tpl
+[NOTE|TIP|IMPORTANT|CAUTION|WARNING]
+Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclimates investiture.
+Ornateness bland it ex enc, est yeti am bongo detract re.
+```
+
+=== Example
+
+[NOTE]
+Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclimates investiture.
+Ornateness bland it ex enc, est yeti am bongo detract re.
+
+[TIP]
+Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclimates investiture.
+Ornateness bland it ex enc, est yeti am bongo detract re.
+
+[IMPORTANT]
+Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclimates investiture.
+Ornateness bland it ex enc, est yeti am bongo detract re.
+
+[CAUTION]
+Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclimates investiture.
+Ornateness bland it ex enc, est yeti am bongo detract re.
+
+[WARNING]
+Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclimates investiture.
+Ornateness bland it ex enc, est yeti am bongo detract re.
+
+
+== Admonition icons
+
+Icons can be added by setting a unicode glyph or a character reference to the `tip-caption` attribute:
+
+```text
+:tip-caption: 💡
+
+[TIP]
+It's possible to use Unicode glyphs as admonition icons.
+```
+
+```text
+:tip-caption: pass:[&#128293;]
+
+[TIP]
+It's possible to use Unicode glyphs as admonition icons.
+```
+
+=== Example
+
+:tip-caption: 💡
+
+[TIP]
+It's possible to use Unicode glyphs as admonition icons.
+
+
+:tip-caption: pass:[&#128293;]
+
+[TIP]
+It's possible to use Unicode glyphs as admonition icons.

exampleSite/content/en/shortcodes/hints.md

@@ -3,11 +3,20 @@ title: Hints
 ---
 
 Hint shortcode can be used as hint/alerts/notification block.
-There are four colors to choose: `info`, `ok`, `warning` and `danger`.
+
+Attributes:
+
+| Name             | Usage                                                                             | default               |
+| ---------------- | --------------------------------------------------------------------------------- | --------------------- |
+| type             | color types to choose from                                                        | note                  |
+| icon (optional)  | custom icon to use                                                                | undefined (type name) |
+| title (optional) | custom icon to use, need to be an icon from an [SVG sprite](/features/icon-sets/) | undefined (type name) |
+
+Syntax:
 
 <!-- prettier-ignore-start -->
 ```tpl
-{{</* hint [info|ok|warning|danger] */>}}
+{{</* hint type=[note|tip|important|caution|warning] (icon=gdoc_github) (title=GitHub) */>}}
 **Markdown content**\
 Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclimates investiture.
  Ornateness bland it ex enc, est yeti am bongo detract re.
@@ -17,26 +26,44 @@ Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclima
 
 ## Example
 
-{{< hint info >}}
+{{< hint type=note >}}
 **Markdown content**\
 Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclimates investiture.
 Ornateness bland it ex enc, est yeti am bongo detract re.
 {{< /hint >}}
 
-{{< hint ok >}}
+{{< hint type=tip >}}
 **Markdown content**\
 Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclimates investiture.
 Ornateness bland it ex enc, est yeti am bongo detract re.
 {{< /hint >}}
 
-{{< hint warning >}}
+{{< hint type=important >}}
 **Markdown content**\
 Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclimates investiture.
 Ornateness bland it ex enc, est yeti am bongo detract re.
 {{< /hint >}}
 
-{{< hint danger >}}
+{{< hint type=caution >}}
 **Markdown content**\
 Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclimates investiture.
 Ornateness bland it ex enc, est yeti am bongo detract re.
 {{< /hint >}}
+
+{{< hint type=warning >}}
+**Markdown content**\
+Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclimates investiture.
+Ornateness bland it ex enc, est yeti am bongo detract re.
+{{< /hint >}}
+
+Example with a custom icon and title:
+
+<!-- prettier-ignore-start -->
+<!-- spellchecker-disable -->
+{{< hint type=note icon=gdoc_github title=GitHub >}}
+**Markdown content**\
+Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclimates investiture.
+Ornateness bland it ex enc, est yeti am bongo detract re.
+{{< /hint >}}
+<!-- spellchecker-enable -->
+<!-- prettier-ignore-end -->

exampleSite/static/custom.css

@@ -14,7 +14,7 @@
   height: 4rem;
 }
 
-.icon-grid__line .icon {
+.icon-grid__line .gdoc-icon {
   font-size: 3em;
 }
 

layouts/partials/menu-bundle.html

@@ -39,7 +39,7 @@
           />
           <label
             {{ if $doCollapse }}
-              for="{{ printf "navtree-%s" $id }}" class="flex justify-between"
+              for="{{ printf "navtree-%s" $id }}" class="flex justify-between align-center"
             {{ end }}
           >
             <span class="flex">

layouts/partials/menu-filetree.html

@@ -40,7 +40,6 @@
 
       {{ range $rangeBy }}
         {{ if not .Params.GeekdocHidden }}
-
           {{ $numberOfPages := (add (len .Pages) (len .Sections)) }}
           {{ $isParent := and (ne $numberOfPages 0) (not .Params.GeekdocFlatSection) }}
           {{ $isCurrent := eq $current . }}
@@ -61,7 +60,7 @@
             />
             <label
               {{ if $doCollapse }}
-                for="{{ printf "navtree-%s" $id }}" class="flex justify-between"
+                for="{{ printf "navtree-%s" $id }}" class="flex justify-between align-center"
               {{ end }}
             >
               {{ if or .Content .Params.GeekdocFlatSection }}

layouts/partials/search.html

@@ -1,5 +1,5 @@
 {{ if default true .Site.Params.GeekdocSearch }}
-  <div class="gdoc-search">
+  <div class="gdoc-search flex align-center">
     <svg class="gdoc-icon gdoc_search"><use xlink:href="#gdoc_search"></use></svg>
     <input
       type="text"

layouts/shortcodes/hint.html

@@ -1,3 +1,16 @@
-<blockquote class="gdoc-hint {{ .Get 0 }}">
+{{ $type := default "note" (.Get "type") }}
-  {{ .Inner | $.Page.RenderString }}
+{{ $icon := .Get "icon" }}
+{{ $title := default ($type | title) (.Get "title") }}
+
+
+<blockquote class="gdoc-hint {{ $type | lower }}">
+  <div class="gdoc-hint__title flex align-center">
+    {{ with $icon }}
+      <svg class="gdoc-icon {{ . }}"><use xlink:href="#{{ . }}"></use></svg>
+      <span>{{ $title }}</span>
+    {{ else }}
+      <i class="fa {{ $type | lower }}" title="{{ $title }}"></i>
+    {{ end }}
+  </div>
+  <div class="gdoc-hint__text">{{ .Inner | $.Page.RenderString }}</div>
 </blockquote>

src/icons/check_circle_outline.svg

@@ -0,0 +1,5 @@
+<!-- Generated by IcoMoon.io -->
+<svg version="1.1" xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 28 28">
+<title>check_circle_outline</title>
+<path d="M14 25.239q4.601 0 7.92-3.319t3.319-7.92-3.319-7.92-7.92-3.319-7.92 3.319-3.319 7.92 3.319 7.92 7.92 3.319zM14 0q5.784 0 9.892 4.108t4.108 9.892-4.108 9.892-9.892 4.108-9.892-4.108-4.108-9.892 4.108-9.892 9.892-4.108zM20.441 7.822l1.972 1.972-11.239 11.239-6.967-7.033 1.972-1.972 4.995 4.995z"></path>
+</svg>

src/icons/dangerous.svg

@@ -0,0 +1,5 @@
+<!-- Generated by IcoMoon.io -->
+<svg version="1.1" xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 28 28">
+<title>dangerous</title>
+<path d="M21.802 19.833l-5.833-5.833 5.833-5.833-1.969-1.969-5.833 5.833-5.833-5.833-1.969 1.969 5.833 5.833-5.833 5.833 1.969 1.969 5.833-5.833 5.833 5.833zM19.833 0l8.167 8.167v11.666l-8.167 8.167h-11.666l-8.167-8.167v-11.666l8.167-8.167h11.666z"></path>
+</svg>

src/icons/error_outline.svg

@@ -0,0 +1,5 @@
+<!-- Generated by IcoMoon.io -->
+<svg version="1.1" xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 28 28">
+<title>error_outline</title>
+<path d="M14 25.239q4.601 0 7.92-3.319t3.319-7.92-3.319-7.92-7.92-3.319-7.92 3.319-3.319 7.92 3.319 7.92 7.92 3.319zM14 0q5.784 0 9.892 4.108t4.108 9.892-4.108 9.892-9.892 4.108-9.892-4.108-4.108-9.892 4.108-9.892 9.892-4.108zM12.62 6.967h2.761v8.413h-2.761v-8.413zM12.62 18.206h2.761v2.826h-2.761v-2.826z"></path>
+</svg>

src/icons/fire.svg

@@ -0,0 +1,5 @@
+<!-- Generated by IcoMoon.io -->
+<svg version="1.1" xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 28 28">
+<title>fire</title>
+<path d="M17.689 21.998q-0.32 0.32-0.8 0.576t-0.864 0.384q-1.152 0.384-2.272 0.032t-1.888-0.992q-0.128-0.128-0.096-0.256t0.16-0.192q1.216-0.384 1.92-1.216t0.96-1.792q0.192-0.896-0.064-1.728t-0.384-1.728q-0.128-0.704-0.096-1.376t0.288-1.312q0-0.128 0.128-0.128t0.192 0.064q0.384 0.832 0.992 1.472t1.28 1.216 1.216 1.248 0.672 1.568q0.064 0.384 0.064 0.704 0.064 0.96-0.32 1.92t-1.088 1.536zM21.529 11.054q-0.768-0.704-1.6-1.28t-1.6-1.344q-1.536-1.536-2.016-3.584t0.16-4.16q0.128-0.32-0.096-0.544t-0.544-0.096q-0.768 0.32-1.44 0.768t-1.312 0.896q-1.984 1.664-3.136 3.936t-1.312 4.864 0.8 5.088q0 0.128 0.032 0.256t0.032 0.256q0 0.576-0.512 0.832t-1.024-0.192q-0.128-0.192-0.192-0.32-1.024-1.28-1.376-2.912t-0.096-3.232q0.064-0.384-0.288-0.576t-0.608 0.128q-1.28 1.664-1.856 3.68t-0.448 4.064q0 0.576 0.096 1.184t0.288 1.184q0.448 1.536 1.216 2.816 1.216 2.048 3.264 3.424t4.416 1.696q2.496 0.32 5.024-0.256t4.448-2.304q1.408-1.344 2.208-3.104t0.864-3.68-0.704-3.712q-0.064-0.128-0.096-0.224t-0.096-0.224q-0.576-1.088-1.28-1.984-0.256-0.384-0.544-0.704t-0.672-0.64z"></path>
+</svg>

src/icons/info_outline.svg

@@ -0,0 +1,5 @@
+<!-- Generated by IcoMoon.io -->
+<svg version="1.1" xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 28 28">
+<title>info_outline</title>
+<path d="M12.62 9.793v-2.826h2.761v2.826h-2.761zM14 25.239q4.601 0 7.92-3.319t3.319-7.92-3.319-7.92-7.92-3.319-7.92 3.319-3.319 7.92 3.319 7.92 7.92 3.319zM14 0q5.784 0 9.892 4.108t4.108 9.892-4.108 9.892-9.892 4.108-9.892-4.108-4.108-9.892 4.108-9.892 9.892-4.108zM12.62 21.033v-8.413h2.761v8.413h-2.761z"></path>
+</svg>

src/sass/_asciidoc.scss

@@ -9,14 +9,14 @@
   }
 
   margin: $padding-16 0;
-  padding: $padding-8 $padding-16 $padding-8 ($padding-16 - $padding-4); //to keep total left space 16dp
+  padding: 0;
 
   border-left: $border-4 solid var(--accent-color);
   border-radius: $border-radius;
 
   table {
-    padding: 0 !important;
     margin: 0 !important;
+    padding: 0 !important;
 
     tr {
       border: 0 !important;
@@ -24,9 +24,39 @@
 
     td {
       &:first-child {
+        background-color: scale-color($gray-600, $alpha: -95%);
         font-weight: bold;
+
+        &.icon {
+          .title {
+            display: flex;
+            align-items: center;
           }
-      display: table-row;
+
+          i.fa::after {
+            content: attr(title);
+            font-style: normal;
+            padding-left: $padding-24;
+          }
+
+          i.fa {
+            color: $black;
+            background-size: auto 90%;
+            background-repeat: no-repeat;
+            filter: invert(30%);
+            margin-left: -5px;
+          }
+
+          @each $name, $icon in $hint-icons {
+            i.fa.icon-#{$name} {
+              background-image: url(img/geekdoc-stack.svg##{$icon});
+            }
+          }
+        }
+      }
+
+      display: flex;
+      padding: $padding-4 $padding-16 !important;
     }
   }
 }

src/sass/_base.scss

@@ -163,8 +163,8 @@ img {
 
 svg.gdoc-icon {
   display: inline-block;
-  width: 1.3em;
+  width: $font-size-20;
-  height: 1.3em;
+  height: $font-size-20;
   vertical-align: middle;
   stroke-width: 0;
   stroke: currentColor;
@@ -289,7 +289,8 @@ svg.gdoc-icon {
       cursor: pointer;
 
       svg.gdoc-icon.toggle {
-        font-size: $font-size-12;
+        width: $font-size-16;
+        height: $font-size-16;
       }
     }
 
@@ -354,7 +355,7 @@ svg.gdoc-icon {
 }
 
 .gdoc-page {
-  min-width: calc($body-min-width - $padding-16 * 2);
+  min-width: calc($body-min-width - $padding-32);
   flex-grow: 1;
   padding: $padding-16 0;
 
@@ -369,7 +370,7 @@ svg.gdoc-icon {
 
   &__header,
   &__footer {
-    margin-bottom: $padding-16 * 1.2;
+    margin-bottom: $padding-24;
 
     svg.gdoc-icon {
       color: var(--control-icons);
@@ -490,7 +491,7 @@ svg.gdoc-icon {
     }
 
     svg.gdoc-icon {
-      font-size: 1.2em;
+      font-size: $font-size-20;
     }
 
     .gdoc-button {
@@ -573,8 +574,7 @@ svg.gdoc-icon {
 
   svg.gdoc-icon {
     position: absolute;
-    top: 0.625em;
+    left: $padding-8;
-    left: $padding-16 * 0.5;
     color: var(--control-icons);
     width: $font-size-16;
     height: $font-size-16;
@@ -680,7 +680,7 @@ svg.gdoc-icon {
 }
 
 .gdoc-error {
-  padding: $padding-16 * 6 $padding-16;
+  padding: $padding-96 $padding-16;
   margin: 0 auto;
   max-width: 45em;
 
@@ -696,7 +696,7 @@ svg.gdoc-icon {
   }
 
   &__message {
-    padding-left: $padding-16 * 4;
+    padding-left: $padding-64;
   }
 
   &__line {

src/sass/_color_mode.scss

@@ -41,9 +41,16 @@
   }
 
   .gdoc-markdown {
-    .gdoc-hint {
+    .gdoc-hint,
+    .admonitionblock,
+    .gdoc-post__codecopy--success {
       filter: none;
     }
+
+    .gdoc-hint__title,
+    .admonitionblock table td:first-child {
+      background-color: scale-color($gray-600, $alpha: -95%);
+    }
   }
 }
 
@@ -91,8 +98,14 @@
 
   .gdoc-markdown {
     .gdoc-hint,
+    .admonitionblock,
     .gdoc-post__codecopy--success {
       filter: saturate(2.5) brightness(0.85);
     }
+
+    .gdoc-hint__title,
+    .admonitionblock table td:first-child {
+      background-color: scale-color($gray-600, $alpha: -85%);
+    }
   }
 }

src/sass/_defaults.scss

@@ -3,7 +3,10 @@ $padding-2: 0.125rem !default;
 $padding-4: 0.25rem !default;
 $padding-8: 0.5rem !default;
 $padding-16: 1rem !default;
+$padding-24: 1.5rem !default;
 $padding-32: 2rem !default;
+$padding-64: 4rem !default;
+$padding-96: 6rem !default;
 
 $font-size-base: 16px !default;
 $font-size-12: 0.75rem !default;
@@ -74,8 +77,20 @@ $hint-colors: (
   note: rgba(0, 145, 234, 1),
   ok: rgba(0, 200, 83, 1),
   tip: rgba(0, 200, 83, 1),
-  warning: rgba(255, 171, 0, 1),
+  important: rgba(255, 171, 0, 1),
   caution: rgba(115, 0, 211, 1),
   danger: rgba(213, 0, 0, 1),
-  important: rgba(213, 0, 0, 1)
+  warning: rgba(213, 0, 0, 1)
+) !default;
+
+// Panel colors
+$hint-icons: (
+  info: "gdoc_info_outline",
+  note: "gdoc_info_outline",
+  ok: "gdoc_check_circle_outline",
+  tip: "gdoc_check_circle_outline",
+  important: "gdoc_error_outline",
+  caution: "gdoc_dangerous",
+  danger: "gdoc_fire",
+  warning: "gdoc_fire"
 ) !default;

src/sass/_markdown.scss

@@ -166,7 +166,7 @@
 
   ul,
   ol {
-    padding-left: $padding-16 * 2;
+    padding-left: $padding-32;
   }
 
   dl {
@@ -176,7 +176,7 @@
     }
 
     dd {
-      margin-left: $padding-16 * 2;
+      margin-left: $padding-32;
     }
   }
 

src/sass/_mobile.scss

@@ -36,7 +36,7 @@
   }
 
   .gdoc-error {
-    padding: $padding-16 * 6 $padding-16;
+    padding: $padding-96 $padding-16;
 
     svg.gdoc-icon {
       width: $font-size-96;

src/sass/_shortcodes.scss

@@ -131,9 +131,47 @@
       border-left-color: $color;
       background-color: scale-color($color, $lightness: 95%, $saturation: -30%);
       color: $body-font-color;
+      padding: 0;
     }
   }
 
+  &__title {
+    padding: $padding-4 $padding-16;
+    background-color: scale-color($gray-600, $alpha: -95%);
+    font-weight: bold;
+    color: scale-color($body-font-color, $alpha: -15%);
+
+    i.fa::after {
+      content: attr(title);
+      font-style: normal;
+      padding-left: $padding-24;
+    }
+
+    i.fa {
+      color: $black;
+      background-size: auto 90%;
+      background-repeat: no-repeat;
+      filter: invert(30%);
+      margin-left: -5px;
+    }
+
+    @each $name, $icon in $hint-icons {
+      i.fa.#{$name} {
+        background-image: url(img/geekdoc-stack.svg##{$icon});
+      }
+    }
+
+    .gdoc-icon {
+      width: $font-size-24;
+      height: $font-size-24;
+      margin-left: -5px;
+    }
+  }
+
+  &__text {
+    padding: $padding-4 $padding-16;
+  }
+
   .gdoc-page__anchor {
     display: none;
   }

svgsprite.config.json

@@ -25,6 +25,11 @@
       "dest": "build/sprites/",
       "sprite": "geekdoc.svg",
       "bust": false
+    },
+    "stack": {
+      "dest": "build/img/",
+      "sprite": "geekdoc-stack.svg",
+      "bust": false
     }
   }
 }

webpack.config.js

@@ -47,6 +47,10 @@ var config = {
           from: "sprites/*.svg",
           to: path.resolve(__dirname, "assets"),
           context: path.resolve(__dirname, "build")
+        },
+        {
+          from: "img/*.svg",
+          context: path.resolve(__dirname, "build")
         }
       ]
     }),