martignoni/hugo-notice

A Hugo theme component to display nice notices

hugo-notice

About

A Hugo theme component providing a shortcode: notice to display nice notices, and supporting dark mode.

Several sets of icons are provided too: make your choice second your taste!

Four notice types are provided: warning, info, note and tip.

This component comes with localization in 18 languages: English, French, German, Italian, Portuguese, Spanish, Chinese, Russian, Turkish, Arabic, Polish, Finnish, Korean, Vietnamese, Swahili, Japanese, Chinese (Taiwan) and Swedish.

Other languages welcome! Send your pull request.

Installation

As a Hugo module

1. Initialize your existing site as hugo module

   hugo mod init github.com/USERNAME/REPO

2. Add the hugo-notice as a hugo module to be able to get upstream changes later

   hugo mod get github.com/martignoni/hugo-notice

3. In your site's or theme's configuration file hugo.yaml or hugo.toml, add a new module section and define both hugo-notice and your currently used theme as modules to be imported.

   Example, with hugo.yaml:

   module:
     imports:
       - path: github.com/martignoni/hugo-notice
       - path: my-theme

   or, with hugo.toml,

   [module]
     [[module.imports]]
       path = "github.com/martignoni/hugo-notice"
     [[module.imports]]
       path = "my-theme"

As a Git submodule

1. Add the hugo-notice as a submodule to be able to get upstream changes later git submodule add https://github.com/martignoni/hugo-notice.git themes/hugo-notice

2. Add hugo-notice as the left-most element of the theme list variable in your site's or theme's configuration file hugo.yaml or hugo.toml.

   Example, with hugo.yaml:

   theme: ["hugo-notice", "my-theme"]

   or, with hugo.toml,

   theme = ["hugo-notice", "my-theme"]

Usage

In your site, use the shortcode, this way:

{{< notice warning >}}
This is a warning notice. Be warned!
{{< /notice >}}

or

{{< notice tip >}}
This is a very good tip.
{{< /notice >}}

Enabling dark mode

We recommend that you use the standard prefers-color-scheme CSS media feature to detect if a user has requested light or dark color themes. In this case, dark mode will work automatically. The prefers-color-scheme media feature is fully supported by all modern browsers.

Another way to make it work is to inject (e.g. via Javascript) the class dark into the body element of your pages when dark mode is needed.

Changing icon set

Just copy the icons from one of the subfolders of folder icons/ into folder icons/.

Any solid SVG icons can be used. If you want to contribute your open licensed icons, your pull request is welcome.

Acknowledgements

Copyright © 2019 onwards, Nicolas Martignoni [email protected].

Localization

Thanks to

• Geraldo Ribeiro for the Portuguese localization.
• thatrocketx for the Italian localization.
• casaqori for the Spanish localization.
• 理头张 for the Chinese localization.
• Алексей Корнеев for the Russian localization.
• Ahmad Al Maaz for the Turkish and Arabic localizations.
• Rafal S. for the Polish localization.
• Oskari J. Manninen for the Finnish localization.
• Haseop Lee for the Korean localization.
• Bùi Nguyễn Hoàng Thọ for the Vietnamese localization.
• callaloo for the Swahili localization.
• kevinzch for the Japanese and Chinese (Taiwan) localizations.
• mcfrojd for the Swedish localization.

Development

Thanks to

• Gary Tai for raising a nasty spacing bug.
• Dephilia for suggesting and implementing dark mode.
• RoneoOrg for implementing default notice type.
• Andreas Deininger for installation as a Hugo module How To.
• rea1shane for suggesting and implementing a few useful features.

hugo-notice's Issues

Missing icon on title line

Hi this is awesome but it seems like the CSS for the Icon is missing. Any hints how to get it working?

Unexpected rendering

I added the hugo-notice component to my website, but the visualization look unexpected with a very wide frame

You can see the result here:

• https://www.stefanoteodorani.it/sandbox0/

Non-preset noticeType has wrong color in dark mode

Light mode:

Dark mode:

Souece code:

{{< notice Others >}}
Non-default type.
{{< /notice >}}

FEATURE: Support for dark mode

Could you please add support for dark mode colour schemes for notice boxes?

Some questions

Hi @martignoni . Thank you so much for solving my problem with this repository! Now I'd like to create a PR to make this project better, but there are a few questions I need to ask you about:

1. Why is the notice.html minified, won't Hugo minify it automatically?

And some non-PR related questions:

1. What is "Workaround markdownify inconsistency for single/multiple paragraphs"?
2. How to make the shortcode work only on paragraphs, not in e.x. code blocks?

Question about your shortcode

Hi @martignoni

I came across your repo while converting a VuePress 2 website to Hugo.

I'd love to understand those lines 👍

<!-- line 1 -->
{{- $raw := (markdownify .Inner | chomp) -}}

<!-- line 2 -->
{{- $block := findRE "(?is)^<(?:address|article|aside|blockquote|canvas|dd|div|dl|dt|fieldset|figcaption|figure|footer|form|h(?:1|2|3|4|5|6)|header|hgroup|hr|li|main|nav|noscript|ol|output|p|pre|section|table|tfoot|ul|video)\\b" $raw 1 -}}

<!-- line 3 -->
{{- if or $block (not $raw) }}{{ $raw }}{{ else }}<p>{{ $raw }}</p>{{ end -}}

Would you have a minute per line to describe what it does?

Thanks a million.

Padding in first notice box

Repo: https://github.com/gary-tai/contour

There is top padding in the first notice box, but not the subsequent notices.
I have implemented the following:

• copied en.yaml to /themes/contour/i18n
• copied notice.html to /themes/contour/layouts/shortcodes
• added shortcode to md page

Test with page:
http://localhost:1313/docs/main/start-contributing/

Possibility for footnotes

Hi,
thank you for this shortcode.
I was wondering, if it is possible to add footnotes? Currently they are not rendered.

Thank you and cheers.

Minification should be handled at build time

Shortcode is minified, but minification should be handled by the user at build time.

Large blank space before the first notice when viewing with macOS Safari

(After trying a different CMS, I have moved back to Hugo, the Hugo Zen theme, and the Hugo-notice theme component.)

The Hugo Notices really look great, but when viewing a post in macOS Safari, I have noticed that there are a number of blank lines present before the first notice. For example (from Configure Apache and PHP-FPM on macOS):

This only happens for the first notice in a post and it only happens in macOS Safari. I don't see the issue in Google Chrome. There are several more "Notes" in this post, and they all look fine (not a bunch of blank lines before the Note).

I understand that the first "notice" loads some CSS code, so I was wondering if that's related. Is this just a bug in Safari, and are there any known workarounds?

Thanks,
George

Implement support of `data-theme` attribute

Use [data-theme="..."]{...}:

Websites, that allow the user to toggle the theme using data-theme (in combination with prefers-color-scheme CSS media feature), won't be able to change the notice's theme, and the notice will look out of place.

Syntax:

/* Light Theme */
[data-theme="light"]{
    /* Color Variables */
}

/* Dark Theme */
[data-theme="dark"]{
    /* Color Variables */
}

Background shading expands past the end of the notice text

I wanted to start by saying that this short code is awesome, but I am seeing one minor issue. Not sure how to best describe this issue, but here's an image of what I am seeing:

This is a single column display where the text is limited to about "70 characters". The note text and even the bright blue bar fit within that limit. But the light blue background expands to the boarder of the browser window. How can this be changed so that the bright blue bar and light blue background are aligned?

I am using the Hugo Zen theme.

Thanks much.

Add support for dark mode

I would like to use this module with a theme which natively supports dark mode (namely Stack). Unfortunately, as I can see, it doesn't change the colours when the dark mode is enabled.

This is how it looks like with the base theme in dark mode:

It's not terrible, but it would be nice if the colour scheme changed. Do you think it's easy to implement, or should I request it in the theme itself?

Provide multiple icon sets

Because not everybody has the same taste.