Beman Website development

Beman Libraries
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:

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.