treewide: code readability improvements

All downstream changes from the theme (i.e. here) will be denoted with:

/* hacks-guide change start */
and
/* hacks-guide change end */

One-line changes are marked with

/* hacks-guide change */

next to it.

Since our theme does not have linear history with upstream, this allows
quicker identification of what exactly has differentiated downstream,
as we do have a few out-of-tree patches for extra functionality.

_includes/footer.html

@@ -11,16 +11,21 @@
         {% endif %}
       {% endfor %}
     {% endif %}
+
+<!-- hacks-guide change start: force disable atom feed-->
 <!--
     {% unless site.atom_feed.hide %}
       <li><a href="{% if site.atom_feed.path %}{{ site.atom_feed.path }}{% else %}{{ '/feed.xml' | relative_url }}{% endif %}"><i class="fas fa-fw fa-rss-square" aria-hidden="true"></i> {{ site.data.ui-text[site.locale].feed_label | default: "Feed" }}</a></li>
     {% endunless %}
     </ul>
   -->
+<!-- hacks-guide change end -->
+
 </div>
 
-<!-- custom footer, guide specific -->
+<!-- hacks-guide change start: custom footer -->
 {% assign split_path = page.path | split: "/" %}
 {% assign locale = split_path[1] %}
 {% assign titles = site.data.navigation[locale].footer %}
 <div class="page__footer-copyright">&copy; {{ site.time | date: '%Y' }} {{ site.name | default: site.title }}. - <a href="site-navigation">{{ titles[1].title }}</a> - <a href="privacy-policy">{{ titles[2].title }}</a> <!-- {{ site.data.ui-text[site.locale].powered_by | default: "Powered by" }} <a href="https://jekyllrb.com" rel="nofollow">Jekyll</a> &amp; <a href="https://mademistakes.com/work/minimal-mistakes-jekyll-theme/" rel="nofollow">Minimal Mistakes</a>.--></div>
+<!-- hacks-guide change end -->

_includes/head/custom.html

@@ -1,6 +1,9 @@
 <!-- start custom head snippets -->
+
 <!-- insert favicons. use http://realfavicongenerator.net/ -->
 
+<!-- hacks-guide change start: cookie consent, favicon, locales -->
+
 <link rel="apple-touch-icon" sizes="180x180" href="{{ base_path }}/images/site-config/apple-touch-icon.png?v=PYEmwKvQAx">
 <link rel="icon" type="image/png" href="{{ base_path }}/images/site-config/favicon-16x16.png?v=PYEmwKvQAx" sizes="16x16">
 <link rel="icon" type="image/png" href="{{ base_path }}/images/site-config/favicon-32x32.png?v=PYEmwKvQAx" sizes="32x32">
@@ -46,5 +49,6 @@ window.cookieconsent.initialise({
   }
 })});
 </script>
+<!-- hacks-guide change end -->
 
-<!-- end custom head snippets -->
+<!-- end custom head snippets -->

_includes/masthead.html

@@ -7,13 +7,16 @@
         {% unless logo_path == empty %}
           <a class="site-logo" href="{{ '/' | relative_url }}"><img src="{{ logo_path | relative_url }}" alt="{{ site.masthead_title | default: site.title }}"></a>
         {% endunless %}
-        <!-- <a class="site-title" href="{{ '/' | relative_url }}">
+<!-- hacks-guide change start: disable default masthead title -->
+      <!--
+        <a class="site-title" href="{{ '/' | relative_url }}">
           {{ site.masthead_title | default: site.title }}
           {% if site.subtitle %}<span class="site-subtitle">{{ site.subtitle }}</span>{% endif %}
         </a>
       -->
+<!-- hacks-guide change end -->
         <ul class="visible-links">
-          <!-- modified to use multilang, guide-specific -->
+<!-- hacks-guide change start: multi-language configuration -->
           {% assign split_path = page.path | split: "/" %}
           {% assign locale = split_path[1] %}
           {% assign titles = site.data.navigation[locale].main %}
@@ -30,7 +33,7 @@
               <li class="masthead__menu-item"><a href="{{ domain }}{{ locale_var }}{{ link.url }}">{{ link.title }}</a></li>
             {% endif %}
           {% endfor %}
-          <!-- end guide specific -->
+<!-- hacks-guide change end -->
         </ul>
         {% if site.search == true %}
         <button class="search__toggle" type="button">
@@ -38,7 +41,7 @@
           <i class="fas fa-search"></i>
         </button>
         {% endif %}
-        <!-- completely redo hidden links for multilang, guide-specific -->
+<!-- hacks-guide change start: Add language selector -->
         <ul class="hidden-links links-menu hidden"></ul>
         <ul class="hidden-links lang-menu hidden">
           {% assign split_url = page.url | split: "/" %}
@@ -88,6 +91,7 @@
           <div class="navicon"></div>
         </button>
         <button class="greedy-nav__toggle_lang" type="button"><div class="langicon"><i class="fa fa-language fa-lg" aria-hidden="true"></i></div></button>
+<!-- hacks-guide change end -->
       </nav>
     </div>
   </div>

_includes/nav_list

@@ -1,3 +1,4 @@
+<!-- hacks-guide change start: Refactor entire subsection to allow using translations -->
 {% assign split_path = page.path | split: "/" %}
 {% assign locale = split_path[1] %}
 {% if locale == 'en_US' %}
@@ -29,4 +30,5 @@
       </ol>
     </li>
   </ul>
-</nav>
+</nav>
+<!-- hacks-guide change end -->

_includes/scripts.html

@@ -6,7 +6,7 @@
   <script src="{{ '/assets/js/main.min.js' | relative_url }}"></script>
 {% endif %}
 
-<!-- for guide purposes all caching is removed and is separately built. -->
+<!-- hacks-guide change start: Disable caching -->
 {% if site.search == true or page.layout == "search" %}
   {%- assign search_provider = site.search_provider | default: "lunr" -%}
   {%- case search_provider -%}
@@ -18,6 +18,7 @@
       {% include search/algolia-search-scripts.html %}
   {%- endcase -%}
 {% endif %}
+<!-- hacks-guide change end -->
 
 {% include analytics.html %}
 {% include /comments-providers/scripts.html %}

_includes/sidebar.html

@@ -1,4 +1,6 @@
-<!-- {% if page.author_profile or layout.author_profile or page.sidebar %}
+<!-- hacks-guide change start: Implement progress table, replace existing sidebar -->
+<!--
+{% if page.author_profile or layout.author_profile or page.sidebar %}
   <div class="sidebar sticky">
   {% if page.author_profile or layout.author_profile %}{% include author-profile.html %}{% endif %}
   {% if page.sidebar %}
@@ -25,4 +27,5 @@
   {% include nav_list %}
 </div>
 
-{% endif %}
+{% endif %}
+<!-- hacks-guide change end-->

_layouts/default.html

@@ -9,13 +9,13 @@
   https://github.com/mmistakes/minimal-mistakes/blob/master/LICENSE
 -->
 
-<!-- for guide purposes all caching is removed and is separately built. -->
 <html lang="{{ site.locale | slice: 0,2 | default: "en" }}" class="no-js">
   <head>
     {% include head.html %}
     {% include head/custom.html %}
   </head>
 
+<!-- hacks-guide change start: Disable caching -->
   <body class="layout--{{ page.layout | default: layout.layout }}{% if page.classes or layout.classes %}{{ page.classes | default: layout.classes | join: ' ' | prepend: ' ' }}{% endif %}">
     {% include skip-links.html %}
     {% include browser-upgrade.html %}
@@ -37,6 +37,7 @@
         {% include footer.html %}
       </footer>
     </div>
+<!-- hacks-guide change end -->
 
     {% include scripts.html %}
 

_layouts/single.html

@@ -41,6 +41,7 @@ layout: default
           </aside>
         {% endif %}
 
+<!-- hacks-guide change start -->
         <hr>
 
         {% assign split_path = page.path | split: "/" %}
@@ -56,6 +57,7 @@ layout: default
         {% endfor %}
 
         <hr>
+<!-- hacks-guide change end -->
 
         {{ content }}
         {% if page.link %}<div><a href="{{ page.link }}" class="btn btn--primary">{{ site.data.ui-text[site.locale].ext_link_label | default: "Direct Link" }}</a></div>{% endif %}

_layouts/splash.html

@@ -16,6 +16,8 @@ layout: default
     {% if page.last_modified_at %}<meta itemprop="dateModified" content="{{ page.last_modified_at | date_to_xmlschema }}">{% endif %}
 
     <section class="page__content" itemprop="text">
+
+<!-- hacks-guide change start -->
       <hr>
 
       {% assign split_path = page.path | split: "/" %}
@@ -31,6 +33,8 @@ layout: default
       {% endfor %}
 
       <hr>
+<!-- hacks-guide change end -->
+
       {{ content }}
     </section>
   </article>

_sass/minimal-mistakes/_base.scss

@@ -6,10 +6,12 @@ html {
   /* sticky footer fix */
   position: relative;
   min-height: 100%;
+/* hacks-guide change start: add Nord skin */
   ::selection {
     color: $text-color;
     background: $text-highlight-color;
   }
+/* hacks-guide change end */
 }
 
 body {

_sass/minimal-mistakes/_navigation.scss

@@ -191,14 +191,18 @@
       color: $masthead-link-color-hover;
     }
 
-    // &.site-logo {
+/* hacks-guide change start: disable site logo, site title */
-      // margin-left: 0;
+    /*
-      // margin-right: 0.5rem;
+    &.site-logo {
-    // }
+      margin-left: 0;
+      margin-right: 0.5rem;
+    }
 
-    // &.site-title {
+    &.site-title {
-      // margin-left: 0;
+      margin-left: 0;
-    // }
+    }
+    */
+/* hacks-guide change end */
   }
   
   img{
@@ -216,6 +220,7 @@
     cursor: pointer;
   }
 
+/* hacks-guide change start: add language selector */
   &__toggle_lang {
     -ms-flex-item-align: center;
     align-self: center;
@@ -225,14 +230,17 @@
     background-color: transparent;
     cursor: pointer;
   }
+/* hacks-guide change end */
 
   .visible-links {
     display: -webkit-box;
     display: -ms-flexbox;
     display: flex;
+/* hacks-guide change start: s/end/start */
     -webkit-box-pack: start;
     -ms-flex-pack: start;
     justify-content: flex-start;
+/* hacks-guide change end */
     -webkit-box-flex: 1;
     -ms-flex: 1;
     flex: 1;
@@ -333,9 +341,11 @@
     }
   }
 
+/* hacks-guide change start: adjust links-menu position */
   .links-menu{
     right: 2rem;
   }
+/* hacks-guide change end */
 
 }
 
@@ -458,10 +468,9 @@
 
   a {
     color: inherit;
-    // line-height: 1.6;
   }
 
-  // progress list, guide-specific
+/* hacks-guide change start: Add progress table */
   ol {
     padding-left: 0.9rem;
   }
@@ -474,15 +483,16 @@
     color: $gray;
     text-decoration: line-through;
   }
-  // end guide-specific
+/* hacks-guide change end */
 
+/* hacks-guide change start: disable padding on active */
   .active {
     // margin-left: -0.5em;
     // padding-left: 0.5em;
     // padding-right: 0.5em;
     font-weight: bold;
   }
-
+/* hacks-guide change end */
 
   @include breakpoint(max-width $large - 1px) {
     position: relative;

_sass/minimal-mistakes/_notices.scss

@@ -17,7 +17,7 @@
   font-family: $global-font-family;
   font-size: $type-size-6 !important;
   text-indent: initial; /* override*/
-  font-weight: bold; // guide specific
+  font-weight: bold; /* hacks-guide change: override font-weight on notices for readability */
   background-color: mix($background-color, $notice-color, $notice-background-mix);
   border-radius: $border-radius;
   box-shadow: 0 1px 1px rgba($notice-color, 0.25);
@@ -47,12 +47,13 @@
   }
 
   a {
-    // guide specific linking
+/* hacks-guide change start: adjust colours for links in notices for readability */
     color: mix(#fff, $notice-color, 30%);
 
     &:hover {
       color: mix(#fff, $notice-color, 70%);
     }
+/* hacks-guide change end */
   }
 
   code {

_sass/minimal-mistakes/_page.scss

@@ -98,7 +98,7 @@ body {
 			-moz-transition: opacity 0.2s ease-in-out 0.1s;
 			-o-transition: opacity 0.2s ease-in-out 0.1s;
 			transition: opacity 0.2s ease-in-out 0.1s;
-      user-select: none;
+      user-select: none; /* hacks-guide change: do not change link colour as it hurts readability */
 		}
 
 		&:hover .header-link {

_sass/minimal-mistakes/_tables.scss

@@ -3,13 +3,13 @@
    ========================================================================== */
 
 table {
-  display: table;
+  display: table; /* hacks-guide change */
   margin-bottom: 1em;
   width: 100%;
   font-family: $global-font-family;
   font-size: $type-size-6;
   border-collapse: collapse;
-  border: 1px solid $light-gray; // guide-specific
+  border: 1px solid $light-gray; /* hacks-guide change */
   overflow-x: auto;
 
   & + table {
@@ -19,24 +19,26 @@ table {
 
 thead {
   background-color: $border-color;
+/* hacks-guide change start */
   // border-bottom: 2px solid mix(#000, $border-color, 25%);
-  // guide-specific
   border-bottom: 1px solid $light-gray;
+/* hacks-guide change end */
 }
 
 th {
   padding: 0.5em;
   font-weight: bold;
   text-align: left;
-  border-right: 1px solid $light-gray; // guide-specific
+  border-right: 1px solid $light-gray; /* hacks-guide change */
 }
 
 td {
   padding: 0.5em;
+/* hacks-guide change start */
   // border-bottom: 1px solid mix(#000, $border-color, 25%);
-  // guide-specific
   border-bottom: 1px solid $light-gray;
   border-right: 1px solid $light-gray;
+/* hacks-guide change end */
 }
 
 tr,

_sass/minimal-mistakes/_utilities.scss

@@ -384,6 +384,8 @@ body:hover .visually-hidden button {
     transform: rotate3d(0, 0, 1, -45deg);
   }
 }
+
+/* hacks-guide change start: disable toggle effects on navigation as it breaks the site in some cases */
 /* 
 .greedy-nav__toggle {
   &:before {
@@ -426,6 +428,7 @@ body:hover .visually-hidden button {
   }
 }
 */
+/* hacks-guide change end */
 
 /*
    Sticky, fixed to top content
@@ -593,6 +596,7 @@ a.reversefootnote {
   }
 }
 
+/* hacks-guide change start: Add language selector */
 /*
     Langicons
     ========================================================================== */
@@ -655,3 +659,4 @@ a.reversefootnote {
             transform: rotate3d(0,0,1,-45deg);
   }
 }
+/* hacks-guide change end */

assets/js/_main.js

@@ -144,8 +144,7 @@ $(document).ready(function() {
     }
   });
 
-  // Adding navigation bar and language selector
+/* hacks-guide change start: add configs for navigation bar and language selector */
-
   if((window.location.href.indexOf("/he_IL/") > -1) || (window.location.href.indexOf("/ar_SA/") > -1)) {
     $("body").css("direction", "rtl");
 
@@ -177,4 +176,5 @@ $(document).ready(function() {
     $('nav.greedy-nav').prepend('<style>.hidden-links:after{right:inherit !important;}</style>');
     $('nav.greedy-nav').prepend('<style>.hidden-links:after{left:5px !important;}</style>');
   }
+/* hacks-guide change end */
 });

assets/js/plugins/jquery.greedy-navigation.js

@@ -4,6 +4,8 @@ Licensed under the MIT license - http://opensource.org/licenses/MIT
 Copyright (c) 2015 Luke Jackson
 */
 
+/* hacks-guide change: add language selector, remove logo */
+
 $(function() {
 
   var $btn = $("nav.greedy-nav .greedy-nav__toggle");