The content of this site is written in Org-mode markup in, well, Org mode. I use Spacemacs as my editor of choice, along with a lot of macros and text expansions done through keyboard firmware and software remapping packages.
Exporting to HTML
This site uses Hugo as its static site generator. Posts, pages, and pages of links are run through templates to produce web-ready output. Hugo is incredibly fast, and has been in development long enough that the templating it offers is sufficient for such things as automatically creating content display pages (for all the content that matches a particular tag, for example), or conditionally showing page elements depending on what “kind” (Hugospeak: taxonomy) of page is being generated.
This site has the source content located in a Github repository, with the generated files being hosted on Netlify. Netlify has an extremely fast global content delivery Network (CDN) that caches the entire site, since everything is static. I am using Netlify as my DNS as well, since having the DNS through them lets the CDN work at maximum effectiveness with little configuration.
Netlify also allows for continuous deployment by means of a build command. Netlify.toml contains information relating to the continuous deployment I use via Netlify (mainly information pertaining to the Hugo command to run on their server). Whenever a build is triggered (I push to the Github repository containing the source), Netlify automatically updates all the cache fingerprints for assets, so only the most recent files are on the CDN. Not having to worry about invalidating out of date assets has been one of my favorite things about this current workflow.
Domain redirects and subdomains
Netlify automatically handles the 301s between the www and non-www versions of the site. I am keeping the www subdomain for several reasons:
- Having a proper subdomain (rather than a CNAME at root, as in CNAME flattening) allows for Netlify’s CDN to work somewhat more effectively, as described on this page. The performance considerations apparently revolve around how Netlify’s CDN interacts with the caches commonly kept by DNS providers.
- Using a proper subdomain allows for cookie separation on subdomains. This is the biggie. Using an Apex domain does not allow you to be selective about which subdomains use the cookies of the main domain, which is a bad thing. Unnecessary cookies slightly increase security risk, and, perhaps more importantly, slow down page loads. This is especially noticeable if you store static assets on the same domain as your primary site (rather than using a separate site entirely, like some big websites do). This is because the cookies will get sent for every single static asset loaded – every style sheet, every script, every image. A few kilobytes of cookies can amount to a fairly significant increase in page size if many static assets are used. I much prefer to use a static subdomain on the main site for serving static content (rather than using a separate domain entirely), since it allows you to mirror static URLs to exactly correspond with the content URLs they are associated with. (For example, www.mysite.com/posts/somepost/ might have an image stored at static.mysite.com/posts/somepost/img1.png). This is much more intuitive and easier for readers to link to, and also happens to save a not insubstantial amount of money in the long run by making extra domain registration costs unnecessary.
- There is not any performance reason to use a bare domain if you can just type in the bare domain and get redirected to the www subdomain anyway (a redirect so fast a human could never process it). So you can still do less typing by ignoring the www if you wish, but the performance benefits of the www subdomain will still be in effect.
Netlify provides easy HTTPS for custom domains by partnering with Let’s Encrypt. While security is not super important for this site as I don’t have user sessions or deal with credit card information, I am 100% behind encrypting everything simply on principle.
I also force HTTPS sitewide. So all non-HTTPS requests will automatically get converted to HTTPS requests.
Performance: gzipping, minification, etc.
Netlify automatically minifies and gzips many content types. It is theoretically possible to gain a better compression level by running a more size-efficient DEFLATE encoder (like Zopfli), but the added cycles would slow down site builds for not much gain.
I use Mailgun to handle all email through the site (rather than, say, Google Apps for Business).
Credits and copyrights
The base theme of this site is Blackburn, with heavy customization on top. I credit this theme with introducing me to the world of Hugo templating. Copyright (c) 2016 Yoshiharu Yamashita, MIT License.
Table of contents
I use a Kanban-esque Waffle.io board to track all of the things that I am currently working on, plan to work on soon, or plan to work on eventually. Put simply, this is where you should start if you want to contribute to this site, because this is the roadmap for the future. If you see something you want to help with, I’d be happy to have your assistance.
This is the side of contribution that is structured: groups of people work together to achieve planned goals in an orderly fashion.
Ad Hoc Contributions
Things can also be improved over time without any sort of overarching plan to bind contributions together: “organic growth”, if you will. If there is something about the content or design of the site that you think could be done better, that is valid grounds for contributing. Nothing on this site is off limits – you are free to contribute, as you see fit, in whatever way you want, pending my approval. Below are some examples of what ad hoc contributions could look like.
Example Content Contributions:
- Eliminating typos
- Eliminating unecessary verbosity or denseness of prose
- Improving phrasing, flow, or pacing
- Adding visual aids, such as diagrams, to enhance comprehension
- Expanding vague sections or adding additional support for points
- Anything else you think could make the content better
Example Design Contributions:
- Improving the desktop UX
- Improving the mobile UX
- Improving accessibility
- Adding customization options for various aspects of the site’s appearance and functionality
- Anything else you think could make the site better
This is the side of contribution that is unstructured: individuals contribute over time to make the site better.
How To Contribute With Respect To Content
In the menu on all the content pages, I have included an “Edit on Github” link. Clicking on this link, if you have a Github account and are logged in, will let you edit the page on the Github web interface and submit a pull request. Note that there is a “preview” button on Github that lets you see the Org file rendered, in case you are not up to speed on all the syntax. Even though you need a GitHub account to propose changes, you need little other knowledge, so once you set up a Github account, you can contribute freely without having to know very much complicated programmer stuff. If you aren’t comfortable contributing in this way, you can also just email improvements to email@example.com.
Of course, you can do things the “old-fashioned” way too, if you’d rather work in a local repository and send pull requests remote. This might be best if you are comfortable in Org mode and you are contributing in a major way (like significantly expanding a section).
How To Contribute With Respect To Design
You can help improve the site itself by submitting pull requests with design improvements. If you are comfortable with web development languages but not GitHub pull requests, you can send implementations to firstname.lastname@example.org, and I’ll incorporate them into the repository myself. If you aren’t comfortable with web development languages or GitHub pull requests, your ideas are still valuable, and you can send them to that same address.
For pull requests requiring significant amounts of work, it would be a good idea to check with me early on to make sure I approve of the changes or enhancements being considered. I don’t want to put you in a situation where you put a lot of work into something that I wouldn’t ultimately use.
Restrictions on Contribution
I enjoy working with other people – and benefit immensely from constructive criticism and new perspectives – but ultimately, decisions about the direction of this site come down to me. In particular, this means that I alone will choose:
- what gets written about
- which improvements find their way into the main repository, and
- how things are shared and licensed
I want to be transparent about this: all contributions to this site are subject to the three statements above.
The contents of this site are licensed under the Creative Commons Attribution-ShareAlike 4.0 International License. Code associated with subprojects will likely be licensed under the GNU General Public License v3 (since I am supportive of forceful copyleft), but sometimes it may be licensed under MIT, Apache, etc. To be sure in any case, you should check the project repositories and their LICENSE files.