search

unicef / inventory

UNICEF Open Source Inventory. A UNICEF Global Innovation knowledge base of best practices and resources for working and leading Open.
https://unicef.github.io/inventory/
Creative Commons Attribution Share Alike 4.0 International
35 stars 28 forks source link

[HUGO] Enhance visibility/distinctness of AsciiDoc callout support #63

Closed jwflory closed 3 years ago

jwflory commented 3 years ago

Summary

Callouts are a defined part of the asciidoctor tool in our pipeline, but the theme does not show callouts in the HTML page

Background

Is your feature request related to a problem? Please describe:

I want to use AsciiDoc callouts to annotate a blockquote or block of text.

Describe the solution you'd like:

The theme renders AsciiDoc callouts in the HTML page.

Describe alternatives you've considered:

You can manually do this without using callouts, but it is not standardized and sort order can change. It is easy for this to become messy and inaccurate in the long-term.

Details

This may require changes to our theme, or it may require engaging upstream Hugo community.

Option 1: Check support in the theme

We use the asciidoctor binary installed as a Ruby gem in our CI pipeline. What this means is, the asciidoctor tool should recognize AsciiDoc callouts, given the official AsciiDoctor docmumentation. There is a chance that Hugo also recognizes the output of asciidoctor but the theme does not implement the right CSS classes for it to render.

If this is the case, the theme needs changes to support AsciiDoc callouts so they appear as intended.

Option 2: Open an upstream issue

It is also possible that the hugo binary and its asciidocExt plugin don't know how to handle callouts.

If this is the case, we need to open a new issue upstream on https://github.com/gohugoio/hugo/issues/ to explore adding this functionality in a future Hugo release.

Outcome

A handy feature of AsciiDoc markup is available and rendered beautifully on the Inventory

jwflory commented 3 years ago

Turns out, this does work as expected. When I tested this locally, my changes were stashed and I wasn't testing with callouts. 🤡 So, closing this as wontfix.

See an example of it here: https://unicef.github.io/inventory/meta/create-new-mission/#front-matter