Creating a static website

I like to share notes and information with Internet friends, and sharing .md files over Nextcloud was nice but not very intuitive. After hearing Pixel talk for a while about his website and digital gardening, I wanted to do the same!

I wanted to use something like GitHub Pages, but without GitHub because I heard it’s problematic. Not open source enough I guess.
After asking around, I decided to use Codeberg Pages – same idea, but more open source and smaller: I like smaller.

In order to use Codeberg, I:

• created an account
• created a repository called “pages” (following the documentation on creating a repository)
  • looked to the ChooseALicense website to choose a license, and decided on CC-BY-4.0, advised for non-software media and educational projects
• then remembered I actually had to install Git, following the Codeberg documentation on installing Git
  • I decided against installing a GUI client, I remember enough from my days in my school’s IT club to run git with the command line.
• I then set up Git to work with my repository, and made my first commit (creating “index.html”)! 🎉

Jekyll

I was advised to use Jekyll as a static site generator (since I know almost nothing of HTML, it seems like the safest bet). Following the Windows installation procedures I installed Ruby 3.0, ran the ridk install command, then opened the Ruby command prompt window as administrator from the Start menu and installed jekyll nicely. (I tried a first time and something went wrong, maybe I hadn’t run the installer as administrator so it didn’t have PATH access rights)

I then got stuck at… step 1 of the step-by-step tutorial.

• One basic error: there were accented letters (é) in the file path to my repository, so Jekyll couldn’t access it. My bad for speaking French I guess *rolls eyes*
• Furthermore, the basic bundle command doesn’t include the webrick gem in Ruby 3.0, as explained in a Jekyll GItHub issue page. I had to add the gem (bundle add webrick) and then everything worked fine.

After I got this solved, the rest of the tutorial was very smooth! I love the feeling of seeing things suddenly come together.
Jekyll is such a nice tool: once you get it to build your website locally, the site will automatically update every time you change something in a file. (Except for the Jekyll config.yml file, for this one you have to restart the server.)

One last advice: by default, Jekyll builds the website in a folder named “_site”. However, the Codeberg Page repository has to be named “pages”. What I did is:

• create the “pages” folder where I have my Git repositories
• in the Jekyll _config.yml file, I added the command destination: [relative-path-to-my-pages-folder]. Works like a charm, every change I make is instantly available in my repository and ready to be git-pushed.

More stuff

• I’m creating tables of contents using kramdown, the default parser for Jekyll.
• After months of not monitoring the width of my webpage because I didn’t want to choose an arbitrary size, I decided to go with a max width of 700px so that the website gets more readable. The idea is that the website will be much more readable if the eye doesn’t have to move too much from side to side, as is explained in this excerpt from “Web Style Guide – Basic Design Principles for Creating Website”.
• In order to save me the trouble of typing the same command lines every time I want to tweak my website, I created a shortcut of the Ruby Command Prompt, with the following instructions: C:\Windows\System32\cmd.exe /E:ON /K C:\Ruby30-x64\bin\setrbvars.cmd && CD C:\repositories\jekyll && bundle update && bundle exec jekyll serve