solita/solita.github.com

Solita Developer Blog

/dev/solita

A blog from developers to developers. Developer-oriented insights from the folks at Solita. Check it out at dev.solita.fi!

Writing a blog post

If you want to write a post, here's how:

1. Fork this repository under your own GitHub account

2. Clone your own fork to your local computer

3. Add your author details to _config.yml

   • The email value is a MD5 hash of your email
   • Optional: to have your avatar show up, make sure you have a Gravatar account registered with your solita.fi email address and a photo of yourself

4. Write a new post under the _posts folder using Markdown

   • Name the file with this format: YYYY-MM-DD-post-name.md

   • You might want to copy some previous post as a template

   • If you don't see your blog post, change the date on the file to today or a past date

   • Normally the publication date of the post is read from the filename. In this case the publishing time will show up as 00:00:00. If you want to specify the exact time your post was published, you can add a date field to your post's front matter. In the date field you can specify the publication time in the format YYYY-MM-DD HH:MM:SS +/-TTTT. For example:

     ---
     title: Post Title
     date: 2016-04-25 13:30:00 +0200
     ....
     ---

5. Preview and proof read your post. You have three options for previewing:

   • Use your IDE
     • VS Code: Command palette -> Markdown: Open preview
     • IDEA: Just open the file
     • Sublime Text: MarkdownPreview
   • Preview the post in GitHub (Pull request -> Files changed -> ... on your post -> View file)
   • Run the site locally and preview the post in it's natural habitat

6. Submit a pull request

   • Select compare accross forks
   • Choose your fork on the right
   • Write an informative description for your pull request

7. Ask someone to review your post

8. Publish by merging the branch

Formatting tips

Double curlies

To render double curly braces ({{...text...}}) in post content, you must surround it with raw-tags:

{%- raw -%}
printf("Hello, {{foo}}", foo)
{% endraw %}

More info in Jekyll docs.

Understanding how the deploy works

There are no workflows in this repo for the deploy - Github has builtin Jekyll based workflows as part of the Github Pages support. You can learn more about it at https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/about-github-pages-and-jekyll or in the Actions run logs that show which actions are being invoked (to see eg Jekyll and Ruby versions involved).

Running the site locally

Option A: Running the site in a container (recommended)

1. Install Docker or Podman (with alias docker=podman)
2. Run ./docker/init.sh (need to be run only the first time launching the site)
3. Run ./docker/start.sh
4. The blog should now be live at localhost:4444
5. Stop the container with ctrl+c

Tips and tricks

• ./docker/destroy.sh -> Delete image
• ./docker/troubleshoot.sh -> Open bash to container without starting jekyl and compass

Option B: Running a Vagrant virtual machine

1. Install Vagrant
2. Install Virtualbox
3. Run cd vagrant
4. Run vagrant up blag
5. Wait patiently as the ruby goodness is downloaded and configured
6. The blog should now be live at localhost:4444

Tips and tricks

• If anything goes wrong, good luck. vagrant ssh blag and try figure it out.
• When you're done you might want to shutdown the virtual machine. vagrant destroy or something like that.

Option C: Running with local Ruby installation

1. Navigate to your working directory and make sure you are running a comatible version of Ruby with ruby -v
2. gem install bundler -v 2.4.22
3. bundle install
4. bundle exec jekyll serve --watch
5. The blog should now be live at localhost:4000

Tips and tricks

• It's highly recommended to use a Ruby version manager like rvm or rbenv.
• For maximum compatibility, use the same version of Ruby as GitHub pages is using.

solita.github.com's Issues

Post Meta overflowing issues

Author information is overflowing on top of content. See screen below.

Suggestion: use flexbox to lay out each post.

PS. Greetings from a fellow blogger: https://dev.solteq.com (You inspired us!)

Personal RSS feeds are broken

After Jekyll 3.0 update the personal feeds have been broken. E.g. http://dev.solita.fi/feeds/rss_rinorragi.xml

Updating blog to GitHubPages Jekyll 3 before 1.5.2016

Highlighter should be changed to "rouge" and markdown to "kramdown". This seems to have negative effect on our vagrant machine. Please communicate without using here tags while fixing this.

https://github.com/blog/2100-github-pages-now-faster-and-simpler-with-jekyll-3-0

Spam from mailto: links?

The author names are now links to our internal email accounts. Won't this generate spam?

Add tw:via="SolitaOy" to tweet button

jarnopeltoniemi commented 2 days ago
Ei suurta merkitystä, mutta laittaisko tuohon tweet-nappiin tw:via="solitaoy". Tulisipa mainittua Solita jakaessa.

Avatar image is a link, but href is empty

Avatar pics are clickable, but the href does not point to real content (only #).

Some options for content:

• Filter post based on that writers account (so that pressing my picture you would only see my posts)
• Link to writers homepage
• mailto

Tag Cloud

A tag cloud would make it easier to find posts related to one topic. Surely there is a way to implement them in Jekyll + GitHub Pages? Also, we'll need to add tags to all the old posts.

Excerpts missing from EPiServer posts

The new layout uses excerpts on the front page. These are now missing for the new EPiServer posts which were freshly merged.

Excerpt should be on one line in the post meta data. Example: https://raw.github.com/solita/solita.github.com/master/_posts/2012-10-30-coffeescript.md

Add OG-tags!

https://developers.facebook.com/docs/opengraphprotocol/

Remove AddThis social sharing buttons

We should probably remove AddThis social sharing buttons, as they can be tracking the users (?). The main Solita site is not using AddThis either. We could just copy the main site's share buttons here as well? Does anyone even use sharing buttons in 2022?

Gravatar integration

Add gravatar image to each post. Could configure in _config.yml for each author.

Any ideas on how to add tags?

I did add tags to my posts. Is there any way to actually support these? :)

Add header for footer links

There are links to other Solita blogs in the footer. We know they are Solita's blogs, but outsiders won't. So we need to add a description which will the what the links are.

E.g. "Solita's other blogs:"

excerpt -> meta description

Eli kun postilla on excerpt, sen voisi laittaa meta descriptioniin, eiks je?

GitHub Pages build is broken

See failed build here https://github.com/solita/solita.github.com/actions/runs/7897753738

Probably caused by GitHub updating some dependencies of the built in Pages builder.
We can be more in control here by starting to use a custom GitHub Action to do the Jekyll build for generating and deploying GitHub Pages instead of using the current zero-config process.

Seems like these issues are related to the problem:

• jekyll/jekyll#9544
• actions/jekyll-build-pages#115

From what I understand it seems the issue manifests when using actions/jekyll-build-pages versions 1.0.10 or 1.0.11 (currently latest and default for GH pages classic build) but you could use older 1.0.9 via custom GH action. The open issue above is in the main jekyll repository so that Jekyll 3.9.4 and 3.9.5 apparently have some issue but that alone doesn't seem to cause the problem in this repo as even those versions seem to work fine in some situations (e.g. when testing locally). Maybe it's a combinations of dependencies that triggers the problem when using those latest versions of jekyll-build-pages.

Rename the repo

Should we rename the repo? I mean, the url that is currently the name isn't even working, it should be solita.github.io. But since we are using a custom domain dev.solita.fi, this repo doesn't need to be named with an url. So we could just rename this to solita-dev-blog or something.

More about GH Pages and domains: https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages#types-of-github-pages-sites

The theme breaks lines in the middle of a word

E.g. if the last word on a line is "in", the theme may add a linebreak between the "i" and the "n".

Tags are case sensitive

The tags are case sensitive which means there appears duplicates like "JavaScript" and "Javascript" which doesn't make much sense, at least to me. IMO, they should be case insensitive making the browsing via tags a little easier.

New slogan/description to header

Current "Solita developer blog" is lame.

Maybe something like:

• Everything from coffee to functional programming"
• Programming motherfucker

Post your ideas here! :)

Fix heading structure

Blog posts are generated from markdown. It's pretty natural to structure the headings starting from h1 (# heading) in markdown, but this results in bad heading structure in the resulting web page. At the moment we have pages that look like this:

<h1>Blog post title from markdown frontmatter</h1>
<h1># First level heading from markdown</h1>
<p>...</p>
<h2>## Second level heading from markdown</h2>
<p>...</p>
<h1># First level heading from markdown</h1>
<p>...</p>

Correct structure would be

<h1>Blog post title from markdown frontmatter</h1>
<h2># First level heading from markdown</h2>
<p>...</p>
<h3>## Second level heading from markdown</h3>
<p>...</p>
<h2># First level heading from markdown</h2>
<p>...</p>

We should limit the headings generated from markdown to be no higher level than h2. Some posts might start from h2 already, so we cant just do heading + 1.