Create the Python Docs Editorial Board static site using Hugo

[Mariatta]

Features:

• search box
• Archives
• RSS feed at /index.xml

[netlify]

✅ Deploy Preview for pythoneditorialboard ready!

Name	Link
🔨 Latest commit	b4cd784
🔍 Latest deploy log	https://app.netlify.com/sites/pythoneditorialboard/deploys/66c9002835d6ed0008a8ecc2
😎 Deploy Preview	https://deploy-preview-13--pythoneditorialboard.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[nedbat]

This is great! The theme is a bit subtle. In light mode, I can't tell what words are links. Dark mode has a bit more contrast, but still seems to be hiding the links a bit. Are there other easy options?

[Mariatta]

Hmm I can try adjusting the CSS. Do you want colors to be different, or would adding underlines work?

Usually I don't like customizing theme because I don't want to maintain it, and also I only have newbie-level CSS knowledge. But if others can help adjust and maintain the CSS then I'm ok with customization.

I tried looking at some other minimalistic and lightweight Hugo themes, but many are outdated/maintained, like their demo site doesn't even work. This theme still seemed to be well maintained.

Another theme I can try to work with is: https://docs.vantage-design.com/ace/ . Would this be of interest?

[AA-Turner]

Out of curiosity, would a Sphinx project be considered here? Though less 'landing page' like, it does have advantages in that it allows cross-linking to other Python docs sites and vice versa.

I'm a little biased perhaps, but themes like Furo have well tested designs that we use for example in the docs-community site, whereas I don't see Hugo used as often.

A

[Mariatta]

To me, Sphinx is too heavy-weight for this purpose. I like using Sphinx for documentation because of the cross-linking feature and auto API documentation, but even I, as an experienced Python user, struggled with it when trying to use it for things like personal blog/website. I found having to spend more time configuring and setting it up, disabling certain features, adjusting template, instead of writing content. Maybe some themes have made it easier, but it still a developer-focused framework.

Whereas Hugo is built for website/landing page/blogging, which is the main purpose for this site. I don't know any Golang, but I could set it up and start writing content quickly, so I chose to optimize for this.

The main consumable content on this site is the markdown files under contents directory, which can already be accessed via GitHub repository. The static site is just a front to serve the markdown in different formats. If we realize that we need features from Sphinx later on, it should not be difficult to convert into Sphinx, and this can definitely be re-evaluated later on.

We haven't use Hugo static site before within the CPython core team, so perhaps you can consider this as a small trial for a small site that has a small audience to begin with.

I hope we don't need to keep arguing about which tools we use here, because in my mind, both tools are good, both have its own pro and cons, both produces a static site. I think the output static site is more important than the tool being used to build it.

[hugovk]

Do you want colors to be different, or would adding underlines work?

Underlines in main body text are a big plus for accessibility. WCAG guidelines say colour alone shouldn't be used for these prose links.

This doesn't necessarily apply to th ig lime navigation, header and footer links, like the grid of links to the minutes from the homepage.

For more info, see references in python/python-docs-theme#160 and python/python-docs-theme#169.

[gvanrossum]

Big yes for underlines from a geezer with declining eyesight.

[Mariatta]

I added a custom css to underline links, please check the output: https://deploy-preview-13--pythoneditorialboard.netlify.app/

I also updated the readme with instructions on how to write up new content/updates.

Sample screenshots:

Landing Page

/updates/ page

/archives/ page

/search/ page

[nedbat]

Looks great, thanks!

[AA-Turner]

I hope we don't need to keep arguing about which tools we use here, because in my mind, both tools are good, both have its own pro and cons, both produces a static site. I think the output static site is more important than the tool being used to build it.

No argument intended, and as you note form follows function. If nothing else, I consider this useful feedback!

A

[hugovk]

Underlines look good, thanks!

[willingc]

Thanks @Mariatta. Let's give this a try. We can always adapt to another framework if the need arises. Results on lighthouse look good (SEO could be inched up in the future). 💐

[willingc]

@Mariatta 🚢