Beman Website development

Beman Project Development
1

Hey looks like there’s multiple working drafts for the new beman website.

I am excited!

For ease of management, can contributors put a link to their WIP website here so we can give active feedback and compare implementations?

Note: I would suggest using netlify if you want to show multiple variants of your design, netlify is able to build on commit sha/ branch and their free teir is very generous for testing.

Suggests contributor posts the following:

  • clear explanation of design and general overview
  • their WIP website
  • the repo that website code is currently residing in

This is more of a suggestion to @leads / infra/ a vote, it may be better if everyone contribute in a branch/ branches at the private beman website repo, instead of individual personal repos.

Contributor mentioned in earlier minutes:

1 Like
2

Hi everyone,

First, I investigated the tools/techs for static site generation, and I see the hugo is actively maintained, users and community made themes are rich and nice. Then I looked the community made themes from github and I found a nice theme hextra (github: imfing/hextra) will satisfy all needs for beman project website. I selected this theme based on the ease of use, fast setup and its rich features.

  1. Setup: Hextra theme provides template repository and allows use the github codespaces without needing local installation.

  2. Config: The website repo has config file: (example config under /hugo.yaml) We need to change some fields for beman website.

  3. Usage: The website repository contains content folder (root folder for website). In this folder we have some markdown files for pages. Folders use _index.md for their pages and we can create markdown files and folders to make relative links from existing pages. The markdown pages should start with:

---
title: "Example Title"
---

Some pages could contain additional fields like: type: docs/blog/about, toc:true/false

The WIP website: The Beman Project

Website repo: mguludag/beman-project-example-static-site

2 Likes
3

Hey all.

I also did some research and built a site based on Docusaurus, maintained by facebook The default theme may be just enough for the project needs at the moment.

Here is the website - Hello from The Beman Project | The Beman Project
Here is the repository - GitHub - RaduNichita/website

2 Likes
4

Hey @mguludag , thank you for your contribution!

Can you show how the blog will look like when migrated over?

1 Like
5

Hey.

I am posting more details about my findings about my implementation of the Beman website.

Firstly, as in my previous post, it is made by using Docusaurus, an open-source project started by Facebook [1]. As stated on their Github [2], “Docusaurus is a project for building, deploying, and maintaining open source project websites easily.” It uses NPM and it generates a website in either Javascript or Typescript.

It seems that the project is well maintained, as they currently have over 57k+ starts and almost 1.2k contributors. [2] (they recently released their latest version a few days ago). It was quite easy to set up the project, as they have good documentation on their website [3].

Once set up, there is just enough to populate the /docs and /blog folders to see the content of the website, without any addition of JS Code. The Docusaurus supports rendering either .mdx or .md files.

It is also quite easy to deploy to gitub-pages, which we could use for hosting the content [4] so we could only rely on some automated deployment of the content to the website via Github Actions. There are also other ways of deploying, as stated on the documentation page.

Proposed flow of contributing to the website:

  1. Creating a fork of the website repository and cloning it
  2. Running a local webserver - “npm run start”
  3. Making the changes and checking they are not breaking anything
  4. Submitting a PR to the main repository.

At [5] you can check some example of website built with Docusaurus by the system group in UPB (University POLITEHNICA of Bucharest).

If there are any questions or concerns, feel free to address them here.

As stated from my last message, you can find:

[1] https://docusaurus.io/
[2] GitHub - facebook/docusaurus: Easy to maintain open source documentation websites.
[3] Introduction | Docusaurus
[4] Deployment | Docusaurus
[5] Operating Systems | Operating Systems

1 Like
6

Hi @river I added blog posts into wip website.

1 Like
7

Thank you for the update! Looks great.

In this week’s meeting, I’ve raised concern into the lifetime of our website’s underlying template.

I personal have experienced my personal blog template getting abandoned (it was one of gastby’s starter templates), and becoming unmaintainable due to dependencies being out of date and not keeping up with breaking changes.

Can you include a write up like what @RaduNichita did above, to do a little bit of a research into the website template and its underlying generation engines. Make sure we can reasonably assume they will be reasonably maintained in the future?

8

Thanks for the write-up.

I am not familiar with docusaurus. But this looks great.

Are you using any special templates here or is the site generated entirely with docusaurus alone?

Template engines themselves usually does not go unmaintained, but the templates/ styling configs on top of them often do. I want you to double check this.

Thank you for linking the example website, it looks great. Have you had any experience with any TAs/ mentors/ prof who does not have the expertise with docusaurus come in and do an edit? What is their experience with updating the site?

1 Like
9

I am using the classic template, as suggested from documentation [6] . I started from

npx create-docusaurus@latest my-website classic

The only javascript / typescript code that I had to write was the one to change content on the homepage.

I came in contact with people from the university and they said it was quite easy to deploy the blogs / documents after an initial configuration of Docusaurus (which was quite similar to what I did in the prototype - setting up the things).

[6] Installation | Docusaurus

1 Like
10

Thanks for the input, looks great! I have no concerns.

11

Hi! sorry for being late. Here is the extended information about hugo generator and hextra template

Following my earlier post, this site uses Hugo, an open-source static site generator from the Go programming community. According to their GitHub, “Hugo is a fast and customizable static site generator built by spf13 and friends in Go.” It uses the Go language to create adaptable websites.

Hugo has a strong community, with over 70k stars and around 800 contributors on GitHub. The project is well-maintained, with frequent new versions that show ongoing improvements and community support. Setting up a Hugo project is easy, thanks to their detailed documentation.

For this project, we’re using the Hextra template, a modern, responsive, batteries-included Hugo theme for creating beautiful static websites. Hextra is inspired by Nextra and utilizes Tailwind CSS to offer a sleek design. It supports responsive layouts and dark mode, ensuring a great user experience on all devices. Additionally, Hextra includes features like full-text search powered by FlexSearch, Markdown support, syntax highlighting, LaTeX math formulae, and more. You can find more about the Hextra template on its GitHub page and the Hextra Starter Template.

The Hextra template is actively maintained, with regular updates and contributions from the community. The latest version was released just a few weeks ago, and the author is responsive to issues and feature requests on GitHub. This ensures that the template remains up-to-date and continues to improve over time.

Once set up, you only need to fill the /content and /static folders to add your website’s content and assets. Hugo supports Markdown (.md) files, which makes content creation straightforward.

Deploying your Hugo site is also hassle-free, with multiple hosting platform options available. GitHub Pages is a great choice for hosting, and you can automate the deployment process with GitHub Actions. The Hugo documentation also outlines other deployment methods.

To contribute to the website, follow these steps:

  1. Fork the website repository and clone it to your local machine.
  2. Start a local server using the commands
    hugo mod tidy
    hugo server --logLevel debug --disableFastRender -p 1313.
  3. Make your changes and ensure everything works smoothly.
  4. Submit a pull request to the main repository.

References:

1 Like
12

I also took a bit of time to work on my proposal for website, the enhanced version is at the same url - Hello from The Beman Project | The Beman Project. (I got very useful feedback from @neatudarius in terms of the content / layout, so many thanks for this).

13

@mguludag @sakshamsharma @RaduNichita .

Will you three be available for the meeting next week?

We will be making a decision soon (~1 week), it would be great for you three to join and tell us more about your implementation for us to make a informed decision.

14

I am available next Monday (27.01), but I will be unable to join the first Monday of February (03.02).

1 Like
15

The intent will be to start a 1 week Beman community review on Monday of next week. I’d like to hear suggestions for evaluation criteria. Some that were mentioned today:

  • minimize template / tooling dependence that might require forced updates
  • should be able to check into repo and handle like normal PR
  • ok for web framework updates to be more difficult
  • writing a blog post needs to be easy
1 Like
16

I also propose:

  • Markdown support for text in docs, libraries, blog etc.

  • GitHub pages deployment. Easy to manage.

17

Hi everyone, joining in the conversation here since I’ve been away for the last few meetings. I am traveling at the time of next week’s Monday meeting but can try to join on my phone, or at least update my thoughts.
I had setup two versions, one with Hugo and one with Jekyll. That said, @RaduNichita 's website at Hello from The Beman Project | The Beman Project looks really good, and probably better than what I might’ve managed with Hugo.

My two cents on the evaluation criteria.
I agree that web framework updates can be allowed to be more difficult. In my experience hosting my own static website for the last 11 years or so, after you’ve got the features down it’s not very common to make fundamental changes since the tech itself is not that unstable overall. Adding to the above, this is also why the theme’s/plugin’s own updates / maintenance isn’t that critical in my experience.

Now this brings us to the topic of longevity. Especially in the situation where some builds break due to dependencies’ compatibility breaking due to lack of maintenance. This can definitely happen, but what I’ve done in the past for my website (it uses haskell and a really unmaintained static site generator), is to setup a docker build image with all the right versions. My job is setup on GitLab (although GitHub would be better), and it basically pulls a docker image to build it. Link here (don’t worry, that “ENCRYPTION_LABEL” is not a sensitive secret :slight_smile: )

I think in the first go it is fine to go with the simplest possible deployment, but to avoid having to spend time in the future dealing with dependency issues, I would recommend making a docker image (and uploading it to DockerHub) in the medium term so we never lose the ability to build the website, irrespective of the framework.

1 Like
18

Agree on these – forgot the markdown part. And I think the implicit thing here is we’re talking about static site generation in all cases which presumably is all github pages can deploy.

1 Like
19

Hi, I am available for next week

1 Like
20

I offer myself to help Radu and I can make a final demo / presentation / reply to questions / whatever will be needed on 2025.02.03 (first Monday from February). - CC: @RaduNichita

I think in the first go it is fine to go with the simplest possible deployment, but to avoid having to spend time in the future dealing with dependency issues, I would recommend making a docker image (and uploading it to DockerHub) in the medium term so we never lose the ability to build the website, irrespective of the framework.

I agree. I propose to have that as a follow-up deployment task after initial bootstrap. BEFORE PEOPLE JUMP AND PROTEST TO THE DOCKER IDEA, I remind you that this is just for website development! NOT ALL of us need to change the website codebase or need to make a deployment. 99% of us probably will just make blog posts (a.k.a. a small PR with a single MD file!).
TLDR: !!! You only need to have Docker installed on local system if and only if you are changing the website itself. !!!

1 Like