Site setup

Planted August 11, 2021 - Last Tended September 03, 2021

  • talk about how I like tinkering and tweaking small things and how much time I waste on this
  • be kind and non-pretentious

Static site generators

Talk about how I made this site and why I don't use jekyll anymore

  • I didn't want to use Ruby anymore
  • Python is powerful and currently my language of choice. Also, it's something I wanted to work on when I started this site.
  • Pelican looked cool, so I ran with it. Turns out it was a nice idea.
  • I was already familiar with Jinja.

Theme

The theme itself is quite simple, dictated by simplicity coming from Markdown-based content. My main inspiration was the solar theme, developed by Marie Otsuka for the solar-powered version of Low-Tech Magazine. They actually provide some interesting insight into the decisions behind the design.

Another source of inspiration was Buttercup Festival by David Troupe - a web comic which I wholeheartedly admire for its humour and calmness. I think the simple design (especially colours, which I stole without any shame) captures the calmness very well.

Accessibility

talk about how big sites affect slow-interneted users (like myself back in my hometown)

Skip-links and minorities

Some screen-reader users don't have the ability to navigate a webpage graphically. To some, it may not be trivial to see where the article begins. A screen reader processes the layout based on DOM elements and reads the content back to the user. If the first focusable content is a skip-link, then there is no need to click through navigation links or nested menus.

If you feel like it, try reloading the page and pressing Tab, and then Enter. The skip-link should move your focus to the article.

More on how to implement a skip-link on css-tricks and WebAIM.

Arias and alts

...

Minimizing size

As a first step, normalize.css is retrieved from a popular CDN. The theme was built, assuming normalize.css will remain present.

  • CSS is generated by libsass and minified with cssmin.
  • It utilizes webassets URL expiry feature.

No custom fonts

Fonts can weigh a lot.

Javascript and usefulness

Javascript is useful, sure. But is it the tool of least power to complete the task?

Pelican: fixing /category/

Turns out I dislike the default Pelican way of structuring sites. By default, categories are accessed at /category/category-name which might make sense when your blog uses a lot of categories or tags. Mine doesn't. That's why I decided to let categories be viewed as folders, i.e. accessed at /category/.

Consider this simple static site:

static
├── file.html
└── folder
    └── index.html

GitHub Pages doesn't allow accessing file.html through /file/ endpoint. It is only accessible through /file and /file.html (Source and full table).

  • /file - OK
  • /file/ - 404
  • /folder - redirects to /folder/
  • /folder/ - OK
  • /folder/index - OK

Current solution

To overcome this, output is structured like so:

output
├── category_1
│   ├── index.html
│   └── <other posts>
└── category_2
    ├── index.html
    └── <other posts>

With respective changes in pelicanconf.py:

ARTICLE_PATHS = ['articles', 'notes', ...]
ARTICLE_URL = '{category}/{slug}'
ARTICLE_SAVE_AS = '{category}/{slug}.html'

...

CATEGORY_URL = '{slug}/'
CATEGORY_SAVE_AS = ''
CATEGORIES_SAVE_AS = ''

This allows accessing categories at /category/ and posts at /category/post.

The only thing left now is to create the actual /category/index.html for each category. It's as easy as creating a page (optionally with a custom template), and changing the Save_as attribute.

Example: front-matter of pages/notes_index.md:

Save_as: notes/index.html

Bonus: pages trailing slash trick

Changing your whole file structure might not be always necessary. For something as simple as allowing access to pages with a trailing slash, consider the following.

output/pages
├── page_1
│   └── index.html
└── page_2
    └── index.html

Respective pelicanconf.py

PAGE_URL = '{slug}/'
PAGE_SAVE_AS '{slug}/index.html'

Or, alternatively, page front-matter:

Save_as: my-page/index.html

Pelican: redirect template

Using a simple http-equiv atribute trick I was able to create a template which redirects on load. This enabled me to create shorter links, such as /resume for resume pdf, instead of /files/resume/resume.pdf. It also provides a fallback link to click on if the redirect somehow wouldn't work.

The whole template presents itself as follows, and was inspired by bryanwweber/pelican-redirect.

<head>
  <link rel="canonical" href="{{ page.redirect_url }}" />
  <meta http-equiv="content-type" content="text/html; charset=utf-8" />
  <meta http-equiv="refresh" content="0;url={{ page.redirect_url }}" />
</head>
<body>
  <p>This content has moved. If you are not redirected, please click here:</p>
  <p><a href="{{ page.redirect_url }}">{{ page.redirect_url }}</a></p>
</body>

← (notes), (home)