I believe @Jeff-Garland intends to create a thread to launch the review of the new website, but since I have time today to evaluate it, I’ll post my questions/comments here.
My understanding is that there are two approaches being proposed:
I’m going to focus on the contributor workflow and the tools used. The tech stack does not affect which pages we want on the website so I won’t evaluate that aspect.
It would be useful if the instructions explained how to install yarn on various platforms. (e.g. on MacOS use brew install yarn)
I followed the instructions for creating a new blog site, but it didn’t show up on my yarn run call. I killed it and, upon restart, I got a long error message that had buried within it this string: “: Error: Blog author with key “David Sankel” not found in the authors map file.”.
I figured I must need to have an entry in the authors.yml file. Adding an entry there was fairly painful. I needed to figure out what the avatars.githubusercontent.com link would be and decide on a “title”. None of this was mentioned in the instructions.
I tried to start again and got another failure. I realized that I needed to use the “key” of my author entry in the blog post so then fixed that. Finally it started and my blog post came up.
When I made changes to the blog post, the HTML view updated automatically. It was a bit confusing that the top level # didn’t show up in the blog post at all and the title was controlled by the metadata. It would be nice if the title was pulled from the body of the post.
I added some images into my post and I had to lookup how to do that with markdown. It was easy enough and since each blog post gets a directory, placement of the images was straightforward.
When I made my commit, it wanted to add some changes to the yarn.lock file. I didn’t know what this was about, so I just omitted those changes in my PR.
There weren’t any site-specific instructions in the README, but I was able to find local development towards the bottom. Similar to my comment on @RaduNichita’s README, it would be useful to have the dependency installation spelled out for common platforms (brew install hugo, brew install go).
The commands to start the server were more complicated than with @RaduNichita’s and it didn’t start a web browser for me. A small thing.
I followed the existing blog entry to add a new one. I like the name of the main file being index.md rather than blog.md. This seems more conventional.
After creating the .md file and writing to it, it immediately started showing on the Blog site. That was nice.
An issue I noticed right off the back is that in the Blog listing page, instead of showing the image my post began with, it put the “alt” text. This wasn’t right at all and I’m not sure how to fix it.
According to Gemini, docusaurus focuses on documentation websites and hugo is more general purpose. React’s integration with docusaurus, which we aren’t using IIUC, is one if its main selling points.
Thanks @dsankel for the comprehensive feedback. I’ve modified the README according to your suggestions.
Regarding choosing Docusaurus over other frameworks,
I went for docusaurus since I saw that it is more documentation focused rather than general purpose. Docusaurus uses react under the hood, we still benefit from it using the mdx format (for example Talks | The Beman Project is a mdx file, since it is not possible to embed videos in standard markdown flavour).
Thank you @dsankel for the detailed feedback and findings! I have added setup scripts for mac and ubuntu based on your suggestions. And the image caption shown bug in the blog list I fixed it and added style to show on bottom of image with background.
My opinions and experiences to choosing Hugo over others,
Community-driven and most starred
Speed of the page creation. Hugo is really fast to create static pages, and it provides seamless live preview side by side while writing a page.
Customization points are wide and advanced to fit almost all use cases.
Shortcodes support to extend markdown syntax (embedding some external content like videos gist social-media etc.): Shortcodes | Hugo
I want to provide some concluding thoughts for my review. First, thanks to both @RaduNichita and @mguludag for building out these websites. I think both explorations are of high quality and substantially better than what we currently have.
When it comes to usability, @mguludag’s approach, where blog posts are not tied to a separate authors’ file, simplifies things for contributors. While @RaduNichita’s has the edge in README.md documentation, the simplified blog post approach won out for me.
As far as framework risk goes, Hugo is roughly twice as popular as Docusaurus and doesn’t have the drawback of being owned by a single company. The fact that there was a big drop in commits mid 2022 for docusaurus concerns me. So, while they are in a similar tier, I think Hugo wins out.
In conclusion, I think both approaches would work well, but I recommend proceeding with @mguludag’s approach.
So I have been doing a little research that isn’t so much hands on, but more down the direction the full potential of what’s possible with static generation sites. That is moving the goalposts perhaps. Part of this is that both of these options for the basic things don’t really separate substantially like you found @dsankel. Note that I’m not terribly concerned with the ‘single company’ element as the project is fully open source.
So additional things we can imagine doing with the site:
The second item is the more important thing I believe. Libraries need to maintain docs and it’d be great if we could have an integrated doc set – or at least consistency in docs that the website could point to.
This second item is what has me thinking docusaurus has an edge – have a look at them eating their own dog food. Don’t miss on the right that with a trivial dropdown earlier versions of docs are maintained. Of course it’s generating sites with react.js instead of more static html like Hugo – so it has some advantages.
For versioned code documentation, if we use doxy style docs in code, we can be able to parse it and generate the md pages from it when we create a tag for library and ci creates a PR to website repo for this versioned documentation. (e.g. create tag 0.3 for beman-libxyz → ci parse and create md files under content/docs/beman-libxyz/0.3/ → then ci create PR for it)