Best approach for longdesc pages (508, WCAG)

support
1

I did a quick search in the forums, but no love. So the question:

What’s the general approach for adding long-desc pages to support images (e.g. plain-text descriptions of charts)? Essentially, they are stand-alone html pages that support a Hugo leaf page. They need to be navigable via a URL, and will never (in my use case) be sucked up into a section page.

Ideally, they seem like part of a leaf bundle, e.g.

    -chartPageBundle/ 
         -index.html
         -img1.png
         -img1-longdesc.html
         -img2.png
         -img2-longdesc.html

But it is not a leaf bundle; the longdesc pages will not be accessed as page resources; they must remain navigable. Is it better to made the image-containing page a branch bundle?

 -chartPageBundle/
      -_index.html
      -img1.png
      -img2.png
      -img1-longdesc/
             -index.html
      -img2-longdesc/
             -index.html

Currently, I’m creating three separate bundles in order to keep the templating simple:

 -chartPageBundle/
      -index.html
      -img1.png
      -img2.png
 -chartPageBundle-img1-longdesc/
       -index.html
 -chartPageBundle-img2-longdesc/
       -index.html

or alternatively:

  -chartPageBundle/
       -index.html
       -img1.png
       -img2.png
  -chartPageBundle-img1-longdesc.html
  -chartPageBundle-img2-longdesc.html

Has anyone ran into this (or something similar) and come up w/a better solution. (Yes, I know I could use figure + figcaption, but when describing a chart or screenshot in detail, this is not the sort of thing that fits nicely into a caption block, as it may span mult paragraphs, include tables, etc.)

2

Yes, you will have to treat the page as a branch bundle if you want children pages navigable.

They don’t need to be. You don’t have to consume the child pages into your section page, that’s really up to how you organise your layouts.

I would personally probably organise it differently. Have each chart as its own bundle, keep the image with the description. Then pull each chart-bundle image into your main chart-page content through shortcodes.

└── chartpage
    ├── _index.md
    ├── chart1
    │   ├── index.md
    │   └── chart.jpg
    └── chart2
        ├── index.md
        └── chart.jpg

which should generate

└── chartpage
    ├── index.html
    ├── chart1
    │   ├── index.html
    │   └── chart.jpg
    └── chart2
        ├── index.html
        └── chart.jpg
1 Like
3

Thanks for your thoughts. I, too, feel like this encapsulates the “page” assets better. I think the only thing that has prevented me from going this direction is the duplication of the templates. This approach would require an additional template file for the bundle (list-single.html?), which is essentially identical to the existing single.html.

4

The branch bundle (ie chartpage) page will by default use the list.html layout. It does not necessarily mean that you need to duplicate the template for the children pages. If your chartpage and chart1 pages have the same layouts, you can just specify the layout to use in their front matter.

So if you use list.html layout, in your chartpage front matter:

cascade:
  layout: "list"

This will set the children pages (chart1, chart2 etc) to use the list layout as well. Alternatively, set it individually on each child page (without the cascade key).

(cascade docs)

5

And just when I thought I had read through the docs enough times, I find something new. I think I knew about cascade, but didn’t realize it could be used to cascade “core” values down to children. I just assumed of was for .Page.param-esque values.

And re-reading the docs, variables set in cascade are made available in .Params. Your solution here implies something different. Or does the cascade “intelligently” decided whether the value should be placed in .Params based on the variable name?

6

The example used happens to be a custom front matter value, so it is accessed through .Params.

The release notes actually include a few more examples of cascade-able values. So, yes, it does merge Hugo-defined variables as well.

1 Like