• Jekyll 4 Conflict errors



    Jekyll - lingering conflict error

    The only error I was still seeing after upgrading to Jekyll 4.0 is the following:
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    
    ...
              Conflict: The following destination is shared by multiple files.
                        The written file may end up with unexpected contents.
                        /website/_site/tag/js/index.html
                         - tag/js/index.html
                         - tag/js/index.html
    
    
              Conflict: The following destination is shared by multiple files.
                        The written file may end up with unexpected contents.
                        /website/_site/tag/nodejs/index.html
                         - tag/nodejs/index.html
                         - tag/nodejs/index.html
    
    ...
    It took me a bit of time to figure this one out, but the solution ended up being quite simple -
    I was using tags and mixing their lowercase and uppercase (e.g. NodeJS, nodejs, nodeJS).
    Once I aligned the tags to be lowercase at all times, this solved all the conflict errors.
  • Miro, Figma, or Draw.io

    Thanks DALL-E 2!


    There are plenty of tools out there to create mocks, designs, and brainstorm to no end.
    The following describes what I'm looking for in a tool for mocks:
    • Alignments - not only should alignments be very strict, I need buttons/shortcuts to auto-align selected elements in the center/left/right. Gimp has a great alignment tool that does exactly this:
    • Import / Export - I want to be able to fully import and export everything, not some things. Ideally in text, at a level where one could edit/adjust things manually and not graphically.
    • Templating - I appreciate the vast marketplaces that were created for Miro & Figma, really I do, but could I please have a way to quickly grab a group of existing elements, add a few custom inputs, and reproduce them accordingly?
    • Versioning - It would be great if we didn't have to reinvent versioning every time a new web app comes out. I've been using version control for 15 years and it's been quite reliable (with the exception of a few newbie git mishaps from 2009 :)). An added bonus is that one could potentially have multiple branches for different sections of the design and easily merge them together (I know that I'm oversimplifying this by a bit).
    • Lightweight - This needs to be quick and responsive. My Dell XPS cannot be crawling just because there are more than 4 dialogs in the mock. I'm looking at you Figma.
    • Image Search - A quick way to grab images (with the proper license) and use them for designs and mocks has been fantastic. Even better with the new AI engines coming out (DALL-E 2 and the likes).
    • Collaborative - I want to be able to quickly share, give/receive feedback, and iterate on designs.

    And the winner is...

    Nobody! No single solution/app currently out there could do all of these things unfortunately.
    The situation is not that dire though, each tool has shown great strengths when used for the right purpose.

    The right tool for the right job

    I use a combination of all 3 tools at the moment, and each works well doing what it does best:

    Systems Design - Draw.io (aka diagrams.net)

    Draw.io is a wonderful tool for Systems Design.
    It's the most lightweight of the three, allow the creation of complex systems without ever slowing down, and eventually export/import them to XML.
    Because of the built-in proper import/export, Draw.io is the most versatile of the group. I was able to embed Draw.io designs in webpages, posts, and at times even in Confluence docs.
    Alignment is probably the strongest on Draw.io, and while it's not at the levels Gimp can bring to the table, it's fairly accommodating.
    Templating, with a bit of external scripting on top of the XML files, is somewhat doable too.
    Draw.io's image search is ok, though the results tend to be more accurate in Miro.
    Real-time Collaboration has been recently introduced, but it's still nowhere near Miro or Figma.

    Brainstorming and early mocks - Miro

    I have to admit, there's something very alluring about the idea of infinite canvas.
    In terms of collaboration Miro is hands down the best tool for the job. Figma is a close second, but the freedom to collaborate over so many distinct types of concepts gives Miro the upper hand.
    Alignment is pretty good on Miro, though keeping horizontal distance across multiple elements doesn't always work.
    Miro is quite heavy, especially when initially loading. One thing I can say is I have worked with companies that had their entire systems, flows, lifecycles, and design mocks on Miro.

    Web designs and realistic mocks - Figma

    When it starts becoming clear how the app/website should look like, this is where Figma comes into the picture.
    Most designers and web developers find Figma to be the last step before actual implementation.
    If I had a better sense of design it's very likely that Figma would've been my go-to tool for any mockup.
    Figma in 2022 is what Adobe Photoshop was in 2010. It's the go-to tool for web designers and to a lesser extent front-end developers.

    Summary

    When trying to collect ideas together in a brainstorming session - go with Miro.
    When it's time to describe the system in greater detail (especially infrastructure and backend) - go with Draw.io.
    When you need to show what it should actually look like for the users - go with Figma.
  • Upgrading Jekyll 2.x to 4.x



    (or: I already mentioned it's a very old Jekyll setup)


    Turns out I did make it to item #984 on my TODOs.
    Upgrading Jekyll has proven to be far easier than migrating to Hugo.
    There were only 2 issues to tackle:

    Issue 1 - Generating Categories and Tags in Jekyll 4.x.x

    The old scripts of generate_categories.rb and generate_tags.rb and their corresponding liquid filters: tag_links and category_links no longer seem to do the trick in Jekyll 4.
    Is it likely possible to fix these functions and keep using the liquid filters? Probably. Is it necessary? Nope.

    It's much easier to just build a template that does the same job and is certainly more future-proof.
    In short, this was the old template:

    old_template.html
    1
    2
    3
    4
    5
    
    {% raw %}
    <!-- This used to work for Jekyll 2 -->
    <div class="post-tags">Tagged with <span>{{ post.tags | tag_links }}</span></div>
    <div class="post-category">Posted in <span>{{ post.categories | category_links }}</span></div>
    {% endraw %}
    new_template.html
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    
    {% raw %}
    {% comment %}<!-- TODO put this in a separate include to save some trouble. Obviously there's some room for improvement here. -->{% endcomment %}
    <div class="post-tags">Tagged with <span>
      {% for tag in post.tags %}
      <a class="tag" href="{{ "/tag/" | append: tag | downcase | replace: " ", "-" | uri_escape }}">{{ tag }}</a>{% if forloop.last %}{% else %}, {% endif %}
      {% endfor %}
    </span></div>
    <div class="post-category">Posted in <span>
      {% for category in post.categories %}
      <a class="category" href="{{ "/category/" | append: category | downcase | replace: " ", "-" | uri_escape }}">{{ category }}</a>{% if forloop.last %}{% else %}, {% endif %}
      {% endfor %}
    </span></div>
    {% endraw %}
    Full example here (including the old scripts and new template).

    Issue 2 - Unrendered liquid in Paginator

    On generated pages (page/##) I was getting unrendered Jekyll liquid code for my meta_description.
    Why? Not sure. A relatively simple IF change helped handle this and grab the correct parts -
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    
    {% comment %} TODO this should likely be resolved by proper layout usage (dedicated paginator page layout for starters) {% endcomment %}
    
    {% assign meta_desc = site.description %}
    {% raw %}{% unless page.url == '/' %}
      {% if page.meta_description %}
        {% capture meta_desc %}{{ page.meta_description }}{% endcapture %}
      {% elsif page.excerpt %}
        {% capture meta_desc %}{{ page.excerpt | strip_html | strip_newlines | truncate: 160 }}{% endcapture %}
      {% elsif page.content %}
        {% if page.content contains "for post in paginator.posts" %}
          {% capture meta_desc %}{{ paginator.posts | first | strip_html | strip_newlines | strip | split: " - " | first | truncate: 160 }}{% endcapture %}
        {% else %}
          {% capture meta_desc %}{{ page.content | strip_html | strip_newlines | strip | truncate: 160 }}{% endcapture %}
        {% endif %}
      {% endif %}
    {% endunless %}
    {% endcapture %}
    <meta name="description" content="{{ meta_desc }}">
    {% endraw %}
    This ended up giving me the same meta_descriptions as I used to get on Jekyll 2.x.

    The good news is that the build time has decreased by 10X!
    The really good news is that it's now fully within GitHub Actions!
  • Adventures of a very old Jekyll Setup



    A waterfall of errors

    So I've been writing on an old Jekyll website of mine.
    Sooner or later I promised myself to move it to Hugo, however it's #983 on the TODO list.
    For now, during the build I have been bombarded with the following 5 errors on repeat:
    1
    2
    3
    4
    5
    
    /var/lib/gems/2.7.0/gems/jekyll-3.1.2/lib/jekyll/convertible.rb:42: warning: Using the last argument as keyword parameters is deprecated
    /var/lib/gems/2.7.0/gems/jekyll-3.1.2/lib/jekyll/document.rb:265: warning: Using the last argument as keyword parameters is deprecated
    /var/lib/gems/2.7.0/gems/jekyll-3.1.2/lib/jekyll/tags/include.rb:169: warning: Using the last argument as keyword parameters is deprecated
    /var/lib/gems/2.7.0/gems/jekyll-3.1.2/lib/jekyll/url.rb:119: warning: URI.escape is obsolete
    /var/lib/gems/2.7.0/gems/rb-inotify-0.9.7/lib/rb-inotify/watcher.rb:66: warning: rb_safe_level will be removed in Ruby 3.0
    Obviously the real answer here would be to upgrade my Jekyll setup to ensure Ruby stops complaining about my ancient stack.
    I have promptly placed upgrading my stack as item #984 on the TODO list (as this is running in isolation, it's not a huge threat).

    For the time being, I am using the following command to silence the noise:
    1
    
    bundle exec jekyll serve 2>&1 | egrep -v 'deprecated|obsolete|rb_safe_level'
  • AWS S3 Sync in GitHub Actions



    Using GitHub Actions to deploy your static website to S3?

    Great!

    Using AWS S3 Sync command?

    Amazing!

    Did you make sure you have the `--size-only` flag on?

    Without `--size-only`, your entire bucket will be uploaded each time your push to your branch. This includes contents that haven't changed at all.

    Why?

    By default, AWS S3 Sync compares the timestamp of your source and destination files. If the timestamp doesn't match - the file will be uploaded. This is a problem, since the files are newly created on each build (they are checked out as part of the workflow). To ensure only size is compared, use the `--size-only` flag like so:
    1
    
    aws s3 sync ./ s3://YOUR_BUCKET_NAME --size-only --exclude '.git/*' --exclude '.github/*'
    p.s. You may have noticed I've also excluded the .git/ and .github/ folders.

    You're welcome ;)