blog

A static, privacy-respecting blog. In ways inspired by both Medium and the popular Medium-look-alike mediumish-theme-jekyll.

Goals

Remember, we moved away from other platforms for very specific reasons.

  1. Completely frictionless for readers.

  2. As few external resources as possible—it slows things down and introduces potential privacy issues.

  3. Little-to-no JavaScript—it’s a blog, not a web app. Currently, we only use progressively-enhancing JS for improving the image zoom experience.

Modern Niceties

Just because it's static and privacy-respecting doesn't mean it's not modern and featureful.

  1. RSS feed support for all the cross-posting you could desire.

  2. Completely responsive design from the start.

  3. Dark style support for everything from day zero.

Editing workflow

Use the GitHub workflow!

  1. Use PRs to propose and work. That means draft PRs for things that aren't ready to publish, too.

  2. All PRs should be reviewed and approved before publishing.

  3. Use reviews and inline comments/suggestions to collaboratively edit.

Handling Images

Ideally, images are put into the images/ directory with a folder name matching the post slug. Since the normal maximum width of articles is 800 pixels, image sizes should be as follows:

When scaling down, use a high quality interpolator like Sinc (Lanczos3) or NoHalo in GIMP to avoid too much blur/fuzziness.

Name your sized images something sane like image-name_800.jpg for the loDPI version, and image-name_1600.jpg for the HiDPI version. When writing the markdown, use this format:

![Alt Text]({{ site.baseurl }}/images/post-name/image-name_800.jpg){: srcset="{{ site.baseurl }}/images/post-name/image-name_1600.jpg 2x"}

This is a bit verbose, but ensures:

Optimize images with the lowest JPG percent that looks good (i.e. manually in GIMP), and use something like Image Optimizer for PNGs.

Also consider JPGs instead of PNGs when the majority of the image is photographic or a gradient (i.e. not solid colors), as that will compress way better than a PNG.

Repos

The blog is actually split into two repos:

  1. @elementary/blog-template, and

  2. @elementary/blog (private)

The template is the source for the design and layout. The private repo holds a copy of the template plus the actual posts themselves, and is set up with GitHub Pages. Layout and design work should always be done against the template repo.

The reason for this separation is to be able to stage future/private blog posts while still letting people benefit from the template work. Ideally we'd have another solution that let us keep the contents of the blog itself public as well, without exposing future posts—or adding significantly to the complexity of maintaining the blog.

Building & Running Locally

The blog is a simple Jekyll-powered site hosted by GitHub Pages. To run it locally, see the GitHub docs.

Dependencies

This guide assumes you're on elementary OS or a similar Ubuntu-based environment.

Packages

Ruby Stuff

We recommend installing gems to a (hidden) directory in your home folder:

echo '' >> ~/.bashrc
echo '# Install Ruby Gems to ~/.gems' >> ~/.bashrc
echo 'export GEM_HOME="$HOME/.gems"' >> ~/.bashrc
echo 'export PATH="$HOME/.gems/bin:$PATH"' >> ~/.bashrc
echo '' >> ~/.bashrc
source ~/.bashrc

Install jekyll and bundler:

gem install jekyll bundler

Install gems:

bundle install

(Adapted from jekyllrb.com/docs/installation/)

Serve

bundle exec jekyll serve --host 0.0.0.0

The site should now be available at 0.0.0.0:4000/ on your local machine, and your local machine's IP address on your network—great for testing on mobile OSes.

Drafts & Future Posts

Append --drafts to the serve command, and drafts in the _drafts folder will show up based on their last-edited time. Similarly, append --future to the serve command to show future posts.