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)
This is interesting for sure and I agree should be considered. Of course, my first question is why would we prefer github backed storage to discourse backed storage? In part I think this will come down to what searches will value – although in the end google may index it all so it won’t matter. Specifically though, if the comment threads are here the search will find topics here, but won’t on github – and vice versa. I think I give the edge to discourse searches but lets discuss.
My first thought would be that the likelihood that (potential) contributed have already a GitHub account, and discussions can directly be linked to issues or PR’s is nice, but there are for sure a few other things also that makes GH discussions the right place for something that is hosted on GH
You can log into discourse with a github account – and other options so I’d argue discourse is better.
Well we have GH discussions shut-off specifically because we have discourse and don’t want to have confusion between discussion platforms. So because of this I lean towards the idea that discourse storage is actually what we want.
React integration & MDX support: Docusaurus allows embedding React components in Markdown via MDX, offering more dynamic content. We may actually use that!
Built-in documentation features: Docusaurus is tailored for documentation with features like versioning and pre-configured components.
Better search: Docusaurus offers smoother search with advanced filtering and dedicated result pages.
Easy tagging & filtering: Docusaurus simplifies tag filtering for blog posts and content, with minimal setup.
Community & Ecosystem: Maintained by Facebook, Docusaurus is part of the React ecosystem, making integration with modern tools easier. I see this as a small advantage.
@RaduNichita@mguludag , would you like to comment on the doc/here? (Or in the sync);
I presented the previous analysis and the document in today’s sync.
We took a decision: we will move forward with docusaurus, for small features already available out of the box and for possible a long-term website lifetime, where we may use some of the React/mdx features.
Thanks @mguludag and @RaduNichita for great work! We really appreciate both of the efforts, and we’ll actually use features from both templates, applied to the docusaurus template.
I (@neatudarius) will coordinate the website development, I will do reviews, and I will try to make sure we have a set of issues to be resolved by our newcomers recruited at C++Now.
TLDR: We’ll try to have a functional website before C++Now.
