I am a web development hobbyist and by no means an expert. The following README describes the principles and choices that have guided my implementation of this website.
This site is built with Jekyll, versioned with GitHub, deployed with Netlify, and hosted with Hover.
Jekyll is opinionated, and wherever possible I try to respect those opinions. Respecting Jekyll opinions means protecting site content from formal interference, allowing content to be ported to other sites or applications easily, and so ensuring the sustainability and durability of this content.
Jekyll has three primary types of content: posts, pages, and data.
Posts and pages are differentiated by whether or not the file requires a date in the front matter. Post files must be prefixed with an ISO 8601 date, using the format YYYY-MM-DD-title.md. Page files do not require a date prefix in the filename, and can simply be formatted as title.md.
Originally, this site used Jekyll collections to group related content types: the _posts collection included all dated content (blogs, articles, updates, etc.) and the _pages collection included all undated content (primarily wiki entries). However, this added a layer of interpretation that I wanted to avoid, so I have reverted the collections and am now just using posts and pages as their native Jekyll defaults (accessed via site.posts and site.pages), organizing these files with categories, subcategories, and tags in the front matter.
Permalinks for pages and posts are defined in the Defaults section of my _config.yml. All posts have a permalink in the format /:year/:month/:day/:title/, and all pages a permalink in the format /:title/. In the past, I have preserved the folder tree for post and page permalinks, but because a cool URI is one which does not change, I prefer to use strong canonical links relative to the site root to mitigate link rot due to site restructures. I use trailing slashes in my URIs because I have encountered issues with different hosts when I leave the trailing slash off, but all hosts seem to understand when it is present.
Posts and pages are written in Markdown. This site specifically uses the CommonMark syntax for Markdown to ensure content compatibility across apps and platforms. This means Markdown syntax flavours used by popular apps like Obsidian or Roam (especially elements like wiki links) are not used on this site, since these undermine the sustainability and durability of site content. Wherever possible, posts and pages should exclusively contain content, prioritizing human readability.
Site formatting is handled with Jekyll layouts and the Liquid templating functionality, which is built into Jekyll. Layouts are separate .html files, stored in the _layouts directory in the site root, and are specified in post and page frontmatter to indicate to Jekyll how to wrap the file content. All critical HTML syntax is kept in the default.html layout. Other layouts should only include formatting for content that appears in the site <main> tags.
Unlike posts and pages, data files are .yml, .yaml, .json, .tsv, or .csv files, which can be used for a variety of purposes, but on this site primarily for populating data content to posts or pages. Data files are stored in the _data directory in the site root.
This site uses native CSS, as opposed to preprocessors like Sass or LESS, prioritizing transparent and traceable styles that allow for easy DOM inspection. Current styles include stylesheets written by Nicolas Gallagher and Maxime Vaillancourt, as well as the stylesheet for DataTables 2.3.0. This site also uses microformats wherever appropriate, which facilitate participation in the IndieWeb.
Prior sites I have built were entirely static, utilizing no JavaScript elements. This site does have some dynamic elements which extend site functionality and improve the user experience. All currently deployed JavaScript is directly served with the website to minimize external dependencies. Current JavaScript includes: jQuery 3.7.1, DataTables 2.3.1, Mermaid 11.6.0, and some in-line code for Toggleable Tabs.