Upgrade docsy to 0.11.0 and hugo to 0.139.0

[zecakeh]

Here are the visual changes I noticed in the rendered spec:

• Links are underlined, which is a good practice for accessibility
• The background color of the inline code is lighter

Example, in the Transaction identifiers section:

Before:

After:

Another change I noticed in the generated HTML but that is not visible is that some uses of shortcodes generate empty paragraphs now (<p></p>). Since it doesn't change the rendering, I guess that browsers are smart enough to ignore them.

Pull Request Checklist

• Pull request includes a changelog file
• Pull request includes a sign off
• Pull request is classified as 'other changes'

Preview: https://pr1996--matrix-spec-previews.netlify.app

[zecakeh]

I found a change that breaks the spec on the proposals page:

The links seem to be escaped instead of rendered.

Edit: it seems like it was already broken in #1984.

[MTRNord]

About the empty p tags: that may or may not (I am only marginaly into those Tools) be annoying to screenreaders https://stackoverflow.com/a/68292918

I guess a quick check with the Linux or Apple tooling might clear that up?

Though I am not sure if the spec Page is screen Reader friendly anyway or if it is a goal :)

[zecakeh]

I found a change that breaks the spec on the proposals page:

<image>

The links seem to be escaped instead of rendered.

I fixed it in #1997.

[zecakeh]

I looked into the empty paragraphs and it doesn't seem like we are doing anything wrong. The only thing that seems to fix it is to use all the cs-module shortcodes on a single line, which feels wrong.

So I opened a discussion on Hugo's forum.

[zecakeh]

The problem of empty paragraphs has been fixed upstream so they won't be generated with the next version of Hugo.

[zecakeh]

I also updated the partials that are modified versions of Docsy's to match the latest version.

[Johennes]

Could you also update the version reference in the README? It currently claims that 117 still works which is untrue even before this PR.

https://github.com/matrix-org/matrix-spec/blob/main/README.md?plain=1#L64

[zecakeh]

Could you also update the version reference in the README? It currently claims that 117 still works which is untrue even before this PR.

https://github.com/matrix-org/matrix-spec/blob/main/README.md?plain=1#L64

This is done. It seems that the website now builds fine starting with hugo 0.123.1.

I also updated Hugo to the just released 0.139.0, which gets rid of the empty paragraphs.

[richvdh]

please can you explain why all this is changing? The commit comment says "Update footer partial" which doesn't give many clues

[zecakeh]

There is a comment above the first param.links.bottom and other comments above that explain the locations of the different types of links.

Basically the footer partial of Docsy has been split into 3 partials, one for each column (left, right, center). By default in Docsy the "user" links are shown in the left column and the "developer" links are shown in the right column. Until now we changed the whole partial to show "developer" links in the center, instead of on the right. Now, to minimize the changes compared to the upstream partials, I created a new type of links, "bottom", so we can show them in the center by changing only the center partial.

[richvdh]

Ok, I get it now, thanks. It would have been nice if that explanation had made it into a commit comment or something, to help with review/future reference.