simple-site
A minimal GitHub Pages website
This website is generated by GitHub Pages with the absolute minimum of configuration (View the source). You do not need to know about static site generators (SSGs) like Jekyll, Hugo, MySTMD, Quarto to use GitHub Pages. Under the hood, GitHub is using Jekyll to render this site. If you want anything more than a very simple single-page site, you might want to learn more about SSGs!
Tutorial
Step 1: Set your repository to deploy to GitHub Pages from the “main” (default) branch. From your GitHub repository, navigate to “Settings” at the top navigation bar. Then, select “Pages” from the left sidebar menu. Finally, configure your build and deployment source to “Deploy from a branch”, select the “main” branch”, and leave the folder set to “/ (root)”. Click “Save”.
Step 2:
Create Markdown content in your repository in an index.md file, which will become the landing page of your GitHub pages site.
At this point, you should have a functional site! :tada: The URL of your site can be viewed by clicking the “Edit repository details” button, which is shown as a cog or gear icon (:gear:). Within this menu, select “Use your GitHub Pages website”, and click “Save changes”.
Limitations
You can’t go much further than this with only Markdown in your toolbelt.
For example, to add more pages, you need some minor knowledge about Jekyll’s syntax (Liquid) and configuration schema.
Use Jekyll’s link syntax to link any other pages,
and in most cases you’ll also need to set baseurl in Jekyll’s config file.
Thoughts on Static Site Generators (SSGs)
There are many SSGs and which you use can be a matter of preference.
I often reach for Quarto and recommend it to my colleagues because (1) it’s aimed at technical publishing and (1a) can execute code cells much like a Jupyter Notebook and (1b) has strong citation support; (2) content format is very close to pure Markdown and doesn’t require learning a templating language; (3) it supports basic features any other SSG might support, like blogging.
Jekyll has been around for a long time. I don’t recommend it to my colleagues because it requires at minimum knowing 2 new “languages” (assuming the user is already familiar with and prefers Markdown): Liquid, and Jekyll’s configuration schema. I think of Jekyll as low level web development tool, not as a high-level content publishing tool.
Keep an eye out for MySTMD, which uses an superset of Markdown called MyST to provide a stronger foundation for extensions.
These opinions are mine alone :smile: