[WIP] [#169] Upgrade Docsy and fix formatting

[glarizza]

NOTE: DO NOT MERGE YET; VERSION PINS AND THE GITHUB ACTION HAVEN'T BEEN COMPLETELY UPDATED.

PROBLEM:

The site has been using an older version of Hugo and Docsy. When we tried to add the new Holos page and rendered the site using the newest versions of Hugo/Docsy, lots of formatting and page elements broke.

SOLUTION:

• Update site configuration to specify the new versions of Docsy/Hugo.
• Follow the site conversion/migration guide to use Docsy as a Go module.
• Convert all image symlinks to native files, as Hugo no longer resolves the symlinks.
• Update formatting in the about page to use row/column shortcodes.
• Specify the row type on the main homepage so the feature blocks align as columns.

OUTCOME:

Executing hugo serve locally produces a website with formatting that matches our existing site.

[natemccurdy]

There is something up with the formatting and CSS on the new version of the site. The fonts and spacing are different on most of the text.

For example, here's the new landing page:

And here's the original:

Any idea why that might be?

[glarizza]

Any idea why that might be?

Oh good catch, lemme dig into that tomorrow. There were enough things that DID change that make me suspect we're missing some formatting settings.

[glarizza]

Hmm, for some reason it's rejecting the Google Font family we're setting in the custom CSS file for JUST the blocks/cover shortcode's title section.

We're doing exactly what the docs say to do: https://www.docsy.dev/docs/adding-content/lookandfeel/#fonts

I'm wondering if there's something about blocks/cover that's overriding that setting. I'm gonna have to dig in some more.

[glarizza]

I hit a timebox on the font problem, here's what I've learned:

1. It looks like it IS using the Roboto font, it's just a different size/weight.
2. I don't see any direct ways to influence that specifically for the title in the blocks/cover shortcode.
3. We ARE setting the font and family information via custom css the same way as we were previously, and the way that is recommended:

$google_font_name: "Roboto";
$google_font_family: "Roboto:300,300i,400,400i,700,700i";

4. I've tried specifying different values for the font weights in google_font_family, but nothing changes the title.

At this point I suspect a bug (either previously that was "fixed", or currently), and/or that we need to write custom CSS to get the title to look the way it was previously. I'm going to work on other things, and come back to this later. I don't think the change in formatting in the title is THAT bad, but I'll leave it up to both of y'all to weigh in on that.

[glarizza]

I wanted to mention that, as Nate said, there are font differences in other elements on some of the pages. The text in the buttons on the main landing page is a good place to look. I had to add a space between the text and the arrow icon so that they aren't so scrunched together. I'm noticing elements like that which seem to be coming from the version updates. I've had to go back and add attributes to existing elements (like adding type="row" to blocks/section elements to get it to correctly format content within the CSS grid) to fix formatting issues. For now this seems to be confined to the pages that aren't formatted as documentation (the main landing page and the about page).

[glarizza]

Here's what I learned yesterday:

I spent a bunch of time trying to figure out a way to store the site background image in a central location, and then have it automatically discovered on every page that needs it (which is only the main landing page, the contact page, and the about page). Previously we used symlinks, but that method broke seemingly because the folder layout within the source repo is different from what actually gets compiled and served. I then tried moving the background image to assets/images/background.jpg and then referencing that file from each page's markdown, but ran into problems getting the CSS background-image code to actually work. After hitting a timebox I decided to just duplicate the file in the two locations we need it. That's what they do in the docsy example site, so I figured it's good enough for us.

I also hit a timebox trying to get the title text to look like the way it does with the older version of docsy/hugo (see comments above). I don't know CSS well enough to be able to target that specific element (the title text) on the landing page, and to pass in the configuration needed to shrink down the font. I can revisit this later, or if one of y'all have any ideas I'm all ears.

Other issues that I've noticed:

• There are <b></b> html tags being appended to the authors names of every blog post, which is weird because those posts are written in markdown (see below).
• Blog posts authored by Jeff don't show his name in the "Authors" tag...it's just an empty element. This is working fine on blog posts I've authored (see below).

I'm not sure if these problems only show up when serving locally, or whether they will be resolved when we deploy. We also don't have a "staging" location to deploy the site to verify how the page will look deployed, which is something we should configure. The rest of the site seems to look the way it was previously.

I spent too much time on this yesterday and need to get back to HashiCorp work, so I'm putting this aside for now.

[natemccurdy]

@glarizza I'll try to pick up where you left off later today.

[glarizza]

Closing in favor of #9