Sharing Shortcodes #103

daniel-keller · 2021-04-26T15:23:49Z

daniel-keller
Apr 26, 2021

We've received several requests to shar the shortcodes we've created for our "Masterpieces from the Clowes Collection" catalog (in development) but I'm not sure of the best way to do this. From what I've found this isn't a common practice in the Hugo community (probably b/c of the challenges I'm going to discuss below).

Hugo requires your shortcode files to be in specific locations outside of your dependencies directory so installing the shortcodes as an npm package won't work out of the box. I can use npm's postinstall script to move the shortcode's html/css/js files to the appropriate file locations as defined by Quire's file structure but I risk overwriting files that already exist. I don't see embedding the css/js in the shortcode itself as an option since you lose the benefit of css/js preprocessing and transpiling.

Right now I'm leaning towards creating an npm package and just providing detailed instructions on where to copy the files and how to plug the js and css into the Quire defined application.js and _all.scss.

Anyone have ideas on the best way to package and share shortcodes?

emptyhut · 2021-04-26T19:29:32Z

emptyhut
Apr 26, 2021

Very new to building with Quire so I'm probably off-course.
Does it work to distribute the additional shortcodes as part of another theme? A 'default-plus'
That seems to be where most of the material is.

1 reply

1000camels Apr 27, 2021

Shortcodes can be created in a folder called Layouts in the top level of your project. I did this for a shortcode called colophon, which you can view here: https://github.com/DigitalUMAG/jen-bervin/tree/master/layouts. It was a copy of one of the others.
In this project, I actually switched to a partial instead, but the model holds. You can basically copy anything in themes/default/layouts to this top level folder and customise it.

You can also create your own theme. Just copy default and rename it. Then change the reference to it in config.yml.

geealbers · 2021-04-27T22:20:48Z

geealbers
Apr 27, 2021
Maintainer

@daniel-keller I’m really glad you brought this up! It’s something we’ve been thinking about ourselves but haven't yet resolved. And apologies for the length of my reply here, but the question really gave me the chance to think through this and document it all in more detail than I've done before. And my reply is more speculation than full-fledged answer but I'd love to get feedback from the community. I'm also hoping @mphstudios @workergnome and @hbalenda will have a chance to weigh in as well.

The idea of publishing it as an npm package is interesting, even with the challenges you point out. However, I’m afraid that approach might be out of scope for other community members who would be interested in sharing their own shortcodes or other custom work they’ve done in Quire. Ideally I'd like to come up with a consistent solution that we can promote across the board.

My thinking about it has been along the lines of what @emptyhut suggested in their comment (:clap:), adding things in as additional themes. This is what Hugo calls theme components, which need not be entire themes but can be as small as a single shortcode. @theNewDynamic (@budparr and @regisphilibert) have linked to some examples in their Awesome Hugo repo.

Where I run into trouble with these is from what I’m seeing, any CSS and JS involved has been inserted in the HTML file of the shortcode or partial itself, either inline or called as an external file with a <link> or <script> tag. I’d much rather have CSS and JS files kept separately and then called from the page <head> for CSS or from the end of the page with the rest of Quire’s scripts. But as it stands, that would mean making modifications to files within Quire’s default theme, similar to what you’re suggesting for application.js and _all.scss. Generally we’re always looking for solutions that don’t involve modifying those default files. We break that rule with the SCSS files and variables in the default Quire theme (and we're rethinking this too), but otherwise when I'm working on a project I try to leave those alone and only ever make custom modifications as overrides within the layouts directory as @1000camels suggested in his comment (:clap:). Architecting for theme components would allow us to easily share the best of those customizations from project to project.

Here’s my current idea:

Let’s say we want to add a theme component called custom-shortcode into our project. We’d copy those files into our themes directory (either directly by downloading and copying the files in, or potentially as a git submodule, or a hugo module, as some of the above example Hugo theme components seem to do), and then add it to our config.yml:

theme:
  - custom-shortcode
  - default

Let’s say the files looks something like this:

themes
├── custom-shortcode
│   ├── layouts
│   │   ├── partials
│   │   ├── shortcodes
│   │   └── etc.
│   └── static
│       ├── css
│       │   └── custom-shortcode.css
│       └── js 
│           └── custom-shortcode.js
└──default
    ├── layouts
    │   ├── partials
    │   ├── shortcodes
    │   └── etc.
    └── static
        ├── css
        │   └── default.css
        └── js 
            └── default.js

Here we’re establishing a very simple structure and filenaming convention, namely that the CSS and JS files of a theme component live in the static directory in css and js directories respectively, and are named after the component itself. In this way we could potentially add the CSS and JS files into the Quire project programatically with a change to Quire’s core head.html and scripts.html partials. For the CSS for example, what I would like to use is something like:

{{ range .Site.Themes -}}
  {{- $cssPath := printf "%s/%s%s" "css" . ".css" -}}
  {{- $hugoPath := printf "%s/%s/%s/%s" "themes" . "static" $cssPath -}}
  {{- if fileExists $hugoPath -}}
  <link rel="stylesheet" href="{{ $cssPath | relURL }}">
  {{ end -}}
{{ end }}

This would loop through the list of themes in config.yml and for each, assume the CSS file path based on the conventions described above, double-check to see if that path resolves to a file that actually exists (so not every Quire theme component would need to have that file), and if it does exist, add the <link> tag pointing to it. We’d then do the same thing for the JS files.

<link rel="stylesheet" href="/css/custom-shortcode.css">
<link rel="stylesheet" href="/css/default.css">

The one additional thing we’d have to do is re-write this a little to reverse the order the links are added (I just didn’t do it here for clarity’s sake). In Hugo theme components, files in the top-most listed component will override others below it. Similarly, we’d want the CSS from that component to override any that was in other components below it, and so that CSS file should actually need to be linked to last.

HOWEVER, the big problem here is that .Site.Themes is not a valid Hugo variable! And in fact, as far as I can find, there is no way to retrieve the list of themes in config.yml from within a Hugo template.

The best alternative I’ve come up with is to use Hugo’s readDir to just look right into the themes directory itself and then run the same logic:

{{ range (readDir "themes") -}}
  {{- $cssPath := printf "%s/%s%s" "css" .Name ".css" -}}
  {{- $hugoPath := printf "%s/%s/%s/%s" "themes" .Name "static" $cssPath -}}
  {{- if fileExists $hugoPath -}}
  <link rel="stylesheet" href="{{ $cssPath | relURL }}">
  {{ end -}}
{{ end }}

This works EXCEPT that the links to the CSS files will be arbitrarily added in the order that they occur in the directory (alphabetically), and so we run into the problem of CSS from a theme component like custom-shortcode being overridden by CSS in another component like quire-custom-shortcode-too even if that's not the intention, and not the order they’re run by Hugo based on the config.yml list.

And this is where I’ve gotten stuck. Maybe there's something in Hugo that I'm missing. Or, one idea is to establish our own custom parameter but then we still have to list the same things under themes and that duplication is obviously not ideal.

params:
  quireComponents:
    - custom-shortcode
    - default

I'm not sure. Maybe the first question though is if this idea of theme components is the best solution to the question of how community members package and share custom Quire work?

0 replies

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Sharing Shortcodes #103

{{title}}

{{editor}}'s edit

{{editor}}'s edit

Replies: 2 comments 1 reply

{{title}}

{{title}}

{{title}}

Select a reply

Sharing Shortcodes #103

daniel-keller Apr 26, 2021

Replies: 2 comments · 1 reply

emptyhut Apr 26, 2021

1000camels Apr 27, 2021

geealbers Apr 27, 2021 Maintainer

daniel-keller
Apr 26, 2021

Replies: 2 comments 1 reply

emptyhut
Apr 26, 2021

geealbers
Apr 27, 2021
Maintainer