Icon permalinks

[mdo]

Creates pages for each icon so we can easily add meta tags, categories, etc.

Fixes #44, fixes #85.

---

Todos

• Add download button
• Add copy buttons to code snippets
• Make links more obvious on homepage
• Tag pages and linked tags
• Category pages and/or category sort on homepage
• Breadcrumb linked

[mdo]

Was going to tackle some JS here for copy to clipboard, but it's becoming more and more work. Dropping that for now and focusing instead on shipping some iterative improvements.

[mdo]

@XhmikosR Would love your eyes on this, in particular on how I'm using pages to create the permalinks (not sure if posts make more sense?) and how the new icons layout is shaping up.

[XhmikosR]

I think this works, but it's far from optimal and I'd like to ask @regisphilibert to have a look when he has some time so that we do this properly in this repo which is smaller :)

So, basically we should find a way to automate the icons content pages based on the icons folder, since we already traverse the folder.

[mdo]

Yeah, manually creating them is a little tough—or at least time consuming. 😅 Thought about doing a data file for it as a "single file source of truth", but wasn't sure how to create the permalink pages based on that. Basing on the icons folder could be cool, too, but I'm obviously not familiar enough with Hugo for that. My hunch before was to make a shell script that would read the list of files and create the {icon-name}.md files, and prep them with a template of front matter.

I'm also okay shipping not optimal for another alpha release or two and iterating over time :).

[mdo]

Separated out the renames and moves into #142, merged that, and just rebased here. This is now all about the icon permalink pages and Hugo updates.

[regisphilibert]

Hi there, I could take a look tomorrow and give you feedbacks if any.

[regisphilibert]

So I can see you have

1. content files to store data for icons
2. icon files in the root directory

For now, the relationship between content file and icon file is based on their matching filename (icon-something.md = icon-something.svg), This involves matching filenames and generating URLs using humanize and printf. There is a solution so that your icons are .Resource object with the many advantage it holds (Page Resources)

Pros

This avoids relying too much on humanize, readDir etc to manually build data.

Cons

Below Hugo 0.65, there is no way to not have the svg files published by Hugo (uploaded to the server even though we only print their content).

Content Structure change

Content Structure A: Each icon is a Page Bundle with an Icon Resource (file)

Each icon page could be a Page Bundle, a directory which could shelter its own resources, one being the icon

icon/alarm-fill.md would become two files:

• content/alarm-fill/index.md (the content file)
• content/alarm-fill/icon.svg (the icon file)

Content structure B: Only the icons section becomes a Page Bundle with every icons in it.

This solution does not require too much change in your content structure. Only to move all the icon svg files underneath content/icons/ alongside the existing content files. The only downside, is that, just like today, you need to make sure icon filename and content filename matches.

Templates

Regardless of the Content Structure option chosen, your template would simply grab the icon resource with .Resources.GetMatch. The advantage is that you get a resource object with different methods including .RelPermalink and .Content to easily print the content of an SVG.

For the Content Structure B your template for the icons partial would look something like that:

{{ range where site.RegularPages "Type" "icons" }}
{{/* .Parent is the section, the Bundle where all the svg files live as Resources 
We use `.File.TranslationBaseName` (without extension) which should match the svg filename
*/}}
{{ $iconFile := .Parent.Resources.GetMatch (printf "%s.svg" .File.TranslationBaseName) }}
{{ $iconPage := . }}
  {{ with $iconFile }}
  <li class="col mb-4">
    <a class="d-block text-dark" href="{{ $iconPage.RelPermalink }}">
      <div class="p-3 py-4 mb-2 bg-light text-center rounded">
        {{ $iconFile.Content }}
      </div>
      <div class="name text-muted text-decoration-none text-center pt-1">
        {{ $iconPage.Title }}
      </div>
    </a>
  </li>
  {{ end }}
{{ end }}

icons/single.html would use similar logic. I would recommand moving the "Icon Finding" logic inside a returning partial so that code is reused and potentially cached.

Inside template:

{{ $iconPage := . }}
{{ $icon := partial "func/GetIconFromPage" . }}

Iside partial layouts/partials/func/GetIconFromPage

{{ $iconFile := false }}
{{ with .Parent.Resources.GetMatch (printf "%s.svg" .File.TranslationBaseName) }}
{{ $iconFile = . }}
{{ end }}
{{ return $iconFile }}

Reco. reading:

• Page Resource Doc
• Page Resources Post
• Returning Partials Post
• Caching Partials Post

[tmorehouse]

Would it be possible, at build time, to generate a JSON file with the icons names as keys, and meta data (categories, tags) as properties under the keys?

e.g.

{
  "alarm": {
    "categories": [ /* array of strings */ ],
    "tags": [ /* array of strings */ ]
  },
  "alarm-fill": {
    "categories": [ /* array of strings */ ],
    "tags": [ /* array of strings */ ]
  },
  // ...
}

It might be handy for handling the icon search, and for 3rd party libraries importing the SVGs.

[regisphilibert]

Would it be possible, at build time, to generate a JSON file with the icons names as keys

Yes it would. I could help once you're ready.

[XhmikosR]

First of all I'd like to thank you @regisphilibert for your time. I really appreciate your feedback!

Below Hugo 0.65, there is no way to not have the svg files published by Hugo (uploaded to the server even though we only print their content).

We try to always use the latest version so that's not an issue :)

Content structure B: Only the icons section becomes a Page Bundle with every icons in it.

I think this is the easiest solution and maybe with mounts we can do this without even moving the files?

As a first step, I'd like to first fix the layouts. Currently each content file specifies the layout, but we should leverage the layouts hierarchy for this. Do note that the plan is to add category and tag pages later based on the frontmatter values.

I think we could probably merge this patch and if you have time you could submit a PR later? This way we would unblock releasing alpha3.

PS. I haven't forgotten about your reply in the bootstrap Hugo issue. I'm cleaning up my inbox and I will get back to you soon :)
PPS. Thanks again for any help!

[regisphilibert]

I think we could probably merge this patch and if you have time you could submit a PR later? This way we would unblock releasing alpha3.

Works for me!