git: 88afe2c0b5 - main - Documentation Portal - Improve UX

From: Sergio Carlavilla Delgado <carlavilla_at_FreeBSD.org>
Date: Wed, 05 Oct 2022 21:35:13 UTC
The branch main has been updated by carlavilla:

URL: https://cgit.FreeBSD.org/doc/commit/?id=88afe2c0b5f25f27d6ca3baf68599b6be5ef0425

commit 88afe2c0b5f25f27d6ca3baf68599b6be5ef0425
Author:     Sergio Carlavilla Delgado <carlavilla@FreeBSD.org>
AuthorDate: 2022-10-05 21:33:23 +0000
Commit:     Sergio Carlavilla Delgado <carlavilla@FreeBSD.org>
CommitDate: 2022-10-05 21:35:04 +0000

    Documentation Portal - Improve UX
    
    * Move main page to use CSS grid for the entries
    * Fix articles, books and languages list
    * Prepare CSS classes to allow other documents
    * Improve book menu sidenav
---
 .../beastie/assets/styles/documentation.scss       |   4 +-
 .../themes/beastie/assets/styles/footer.scss       |   7 +-
 .../themes/beastie/assets/styles/global.scss       | 207 ++++++++-------------
 .../themes/beastie/assets/styles/header.scss       |  12 +-
 .../themes/beastie/layouts/_default/languages.html |  24 +--
 .../beastie/layouts/articles/total-list.html       |   2 +-
 .../themes/beastie/layouts/books/total-list.html   |   2 +-
 documentation/themes/beastie/layouts/index.html    | 108 +++++------
 .../beastie/layouts/partials/site-footer.html      |   2 +-
 .../beastie/layouts/partials/site-header.html      |   2 +-
 .../shortcodes/list-articles-directories.html      |   2 +-
 .../layouts/shortcodes/list-books-directories.html |   2 +-
 12 files changed, 166 insertions(+), 208 deletions(-)

diff --git a/documentation/themes/beastie/assets/styles/documentation.scss b/documentation/themes/beastie/assets/styles/documentation.scss
index 39d4c1d27f..dbb015b745 100644
--- a/documentation/themes/beastie/assets/styles/documentation.scss
+++ b/documentation/themes/beastie/assets/styles/documentation.scss
@@ -26,7 +26,7 @@
  *
  */
 
-.articles-books-list {
+.documents-list {
   list-style: none;
   padding-left: 10px;
 
@@ -134,7 +134,7 @@
       #MenuContents {
         position: sticky;
         overflow: auto;
-        max-height: calc(90vh);
+        max-height: calc(100vh - 8rem);
         line-height: 2;
 
         ul {
diff --git a/documentation/themes/beastie/assets/styles/footer.scss b/documentation/themes/beastie/assets/styles/footer.scss
index 947687c4fe..041e8db47d 100644
--- a/documentation/themes/beastie/assets/styles/footer.scss
+++ b/documentation/themes/beastie/assets/styles/footer.scss
@@ -101,7 +101,12 @@ footer {
 }
 
 .heart {
-  color: red;
+  font-size: 1.2rem;
+  color: #E38582;
+}
+
+.heart:hover {
+  color: #D1332E;
 }
 
 .options-container {
diff --git a/documentation/themes/beastie/assets/styles/global.scss b/documentation/themes/beastie/assets/styles/global.scss
index 83537922e5..a1d8b40e5b 100644
--- a/documentation/themes/beastie/assets/styles/global.scss
+++ b/documentation/themes/beastie/assets/styles/global.scss
@@ -38,7 +38,8 @@ html {
   }
 }
 
-html, body {
+html,
+body {
   text-rendering: optimizeLegibility;
   line-height: 1.5;
 }
@@ -61,18 +62,12 @@ body {
   display: flex;
   flex-direction: column;
   justify-content: center;
-  margin-left: auto;
-  margin-right: auto;
+  margin: 0 auto;
+  width: 100%;
   max-width: var(--max-width);
   transition: padding .15s;
   background-color: var(--global-background-color);
 
-  .article {
-    .paragraph {
-      padding-left: .5rem;
-    }
-  }
-
   .welcome-container {
     display: flex;
     width: 100%;
@@ -89,7 +84,7 @@ body {
       h2 {
         margin: 0;
         border-bottom: 0px;
-        margin-left: auto;
+        margin-left: 10%;
       }
 
       a {
@@ -114,7 +109,7 @@ body {
 
       input {
         display: block;
-        width: 50%;
+        width: 80%;
         padding: 10px 20px;
         border: 1px solid #CCC;
         border-radius: 4px;
@@ -127,52 +122,46 @@ body {
   }
 
   .cards-container {
-    display: flex;
-    flex-direction: column;
-    justify-content: center;
-    width: 100%;
+    display: grid;
+    grid-gap: 1rem;
+    margin: 0 auto;
     margin-top: 3rem;
     margin-bottom: 3rem;
+    padding-right: 10%;
+    padding-left: 10%;
 
-    .row {
-      display: flex;
-      flex-direction: row;
-      justify-content: center;
-      width: 100%;
-      margin-bottom: 2rem;
+    .card {
+      padding: 1rem;
+      border: 1px solid var(--card-border-color);
+      background-color: var(--card-background-color);
 
-      .card {
+      a {
         display: flex;
-        flex: 280px 0;
-        margin-left: 16px;
-        padding: 24px;
-        border: 1px solid var(--card-border-color);
-        background-color: var(--card-background-color);
-
-        a {
-          display: flex;
-          flex-direction: column;
-          text-decoration: none;
-
-          h5 {
-            color: var(--global-font-color);
-            font-weight: 700;
-            font-size: 22px;
-            margin: 0px 0px 8px 0px;
-            border-bottom: 0px;
-          }
+        flex-direction: column;
+        text-decoration: none;
+
+        h5 {
+          color: var(--global-font-color);
+          font-weight: 700;
+          font-size: 22px;
+          margin: 0px 0px 8px 0px;
+          border-bottom: 0px;
+        }
 
-          p {
-            color: var(--global-font-color);
-            font-size: 18px;
-            margin: 0px;
-            margin-top: auto;
-            text-align: inherit;
-          }
+        p {
+          color: var(--global-font-color);
+          font-size: 18px;
+          margin: 0px;
+          margin-top: auto;
+          text-align: inherit;
         }
       }
     }
   }
+
+  .document {
+    padding: var(--documentation-padding);
+  }
 }
 
 ul.language-list {
@@ -196,72 +185,31 @@ ul.language-list {
   }
 }
 
-@media (max-width: 55em) {
+@media (min-width: 600px) {
   .main-wrapper {
-    padding: 0rem 1rem 2rem 1rem;
-
     .welcome-container {
-      margin-bottom: 2.5rem;
-
-      form {
-        input {
-          width: 100%;
-          background-color: var(--white);
+      .title-language-container {
+        h2 {
+          margin-left: auto;
         }
       }
 
-    }
-
-    .cards-container {
-      display: block;
-      width: 100%;
-      margin: 0;
-      padding: 0;
-
-      .row {
-        display: block;
-        width: 100%;
-
-        .card {
-          display: block;
-          width: 100%;
-          margin: 0px;
-          margin-bottom: 2rem;
-          padding: 0px;
-
-          a {
-            display: flex;
-            padding: 20px;
-            min-height: 100px;
-          }
+      form {
+        input {
+          width: 50%;
         }
       }
     }
   }
 
-}
-
-@media (min-width: 1200px) {
-  .main-wrapper {
-    .cards-container {
-      .row {
-        .card {
-          width: 33.3%;
-        }
-      }
-    }
+  .cards-container {
+    grid-template-columns: repeat(2, 1fr);
   }
 }
 
-@media (min-width: 768px) {
-  .main-wrapper {
-    .cards-container {
-      .row {
-        .card {
-          width: 50%;
-        }
-      }
-    }
+@media (min-width: 900px) {
+  .cards-container {
+    grid-template-columns: repeat(3, 1fr);
   }
 }
 
@@ -316,11 +264,11 @@ h6 {
   font-size: var(--size-300);
 }
 
-h2 > .anchor,
-h3 > .anchor,
-h4 > .anchor,
-h5 > .anchor,
-h6 > .anchor {
+h2>.anchor,
+h3>.anchor,
+h4>.anchor,
+h5>.anchor,
+h6>.anchor {
   text-decoration: none;
 
   &:hover {
@@ -328,11 +276,11 @@ h6 > .anchor {
   }
 }
 
-h2 > .anchor::before,
-h3 > .anchor::before,
-h4 > .anchor::before,
-h5 > .anchor::before,
-h6 > .anchor::before {
+h2>.anchor::before,
+h3>.anchor::before,
+h4>.anchor::before,
+h5>.anchor::before,
+h6>.anchor::before {
   visibility: hidden;
   margin-left: .3rem;
   content: "#";
@@ -405,7 +353,10 @@ p {
   text-justify: inter-word;
 }
 
-b, dt, strong, th {
+b,
+dt,
+strong,
+th {
   font-weight: bolder;
 }
 
@@ -460,7 +411,8 @@ blockquote {
   padding-bottom: 4px;
 }
 
-.colist tr td b, .programlisting b {
+.colist tr td b,
+.programlisting b {
   display: none;
 }
 
@@ -510,11 +462,13 @@ table.tableblock {
     border: none;
   }
 
-  td:first-of-type, th:first-of-type {
+  td:first-of-type,
+  th:first-of-type {
     border-left: none;
   }
 
-  td:last-of-type, th:last-of-type {
+  td:last-of-type,
+  th:last-of-type {
     border-right: none;
   }
 }
@@ -561,27 +515,27 @@ table.stretch {
           }
 
           .icon-note::before {
-            content:"\f05a";
+            content: "\f05a";
             color: var(--admonition-note-color);
           }
 
           .icon-tip::before {
-            content:"\f0eb";
+            content: "\f0eb";
             color: var(--admonition-tip-color)
           }
 
           .icon-warning::before {
-            content:"\f071";
+            content: "\f071";
             color: var(--admonition-warning-color);
           }
 
           .icon-caution::before {
-            content:"\f06d";
+            content: "\f06d";
             color: var(--admonition-caution-color);
           }
 
           .icon-important::before {
-            content:"\f06a";
+            content: "\f06a";
             color: var(--admonition-important-color);
           }
         }
@@ -638,7 +592,8 @@ table.stretch {
 }
 
 /* Example */
-.example, .exampleblock {
+.example,
+.exampleblock {
   border-left: 5px solid var(--example-block-color);
   padding: 1rem;
   background-color: var(--example-block-background-color);
@@ -655,7 +610,7 @@ table.stretch {
 
   .content {
     .literalblock {
-      .content{
+      .content {
         background: #fefde6 !important;
         border: none !important;
         color: var(--global-font-color);
@@ -676,8 +631,8 @@ table.stretch {
 
 /* Misc */
 .fa {
-    font-family: FontAwesome;
-    font-style: normal;
+  font-family: FontAwesome;
+  font-style: normal;
 }
 
 .listingblock {
@@ -710,13 +665,13 @@ details {
 kbd {
   font-family: "DejaVu Sans", "DejaVu Sans Bold";
   display: inline-block;
-  color: rgba(0,0,0,.8);
+  color: rgba(0, 0, 0, .8);
   font-size: .65em;
   line-height: 1.45;
   background-color: #F7F7F7;
   border: 1px solid #ccc;
   border-radius: 3px;
-  box-shadow: 0 1px 0 rgba(0,0,0,.2),0 0 0 .1em #FFF inset;
+  box-shadow: 0 1px 0 rgba(0, 0, 0, .2), 0 0 0 .1em #FFF inset;
   margin: 0 .15em;
   padding: .2em .5em;
   vertical-align: middle;
@@ -789,4 +744,4 @@ kbd {
     transition: visibility 0s easy 0s;
   }
 
-}
+}
\ No newline at end of file
diff --git a/documentation/themes/beastie/assets/styles/header.scss b/documentation/themes/beastie/assets/styles/header.scss
index 25c38759c7..3e151aeb76 100644
--- a/documentation/themes/beastie/assets/styles/header.scss
+++ b/documentation/themes/beastie/assets/styles/header.scss
@@ -205,13 +205,14 @@ input[type='checkbox'] {
   border-radius: .4rem;
 }
 
-.donate a i,
-.heart i {
+.donate a .heart,
+.heart .heart {
+  font-size: 1.2rem;
   color: #E38582;
 }
 
-.donate:hover a i,
-.heart:hover i {
+.donate:hover a .heart,
+.heart:hover .heart {
   color: #D1332E;
 }
 
@@ -328,7 +329,8 @@ input[type='checkbox'] {
     text-align: center;
   }
 
-  .donate a i {
+  .donate a .heart {
+    font-size: 1.2rem;
     color: #D1332E;
   }
 }
diff --git a/documentation/themes/beastie/layouts/_default/languages.html b/documentation/themes/beastie/layouts/_default/languages.html
index ba487c26c3..8743c86312 100644
--- a/documentation/themes/beastie/layouts/_default/languages.html
+++ b/documentation/themes/beastie/layouts/_default/languages.html
@@ -4,17 +4,19 @@
   <body>
     {{ block "header" . }}{{ partial "site-header.html" .}}{{ end }}
     <main class="main-wrapper">
-      {{ $home := .Site.Home }}
-      <h1>{{ i18n "select-language" }}</h1>
-      <p>{{ i18n "current-selection" }} {{ .Site.Language.LanguageName }}</p>
-      <ul class="language-list">
-        {{ range $.Site.Home.AllTranslations }}
-        {{ $isCurrentLang := eq $home.Language .Language }}
-          <li {{ if $isCurrentLang}} class="selected" {{ end }}>
-            <a href="{{ .RelPermalink }}" lang="{{ .Language.Params.languageCode }}">{{.Language.LanguageName }}</a>
-          </li>
-        {{ end }}
-      </ul>
+      <div class="document">
+        {{ $home := .Site.Home }}
+        <h1>{{ i18n "select-language" }}</h1>
+        <p>{{ i18n "current-selection" }} {{ .Site.Language.LanguageName }}</p>
+        <ul class="language-list">
+          {{ range $.Site.Home.AllTranslations }}
+          {{ $isCurrentLang := eq $home.Language .Language }}
+            <li {{ if $isCurrentLang}} class="selected" {{ end }}>
+              <a href="{{ .RelPermalink }}" lang="{{ .Language.Params.languageCode }}">{{.Language.LanguageName }}</a>
+            </li>
+          {{ end }}
+        </ul>
+      </div>
     </main>
     {{ block "footer" . }}{{ partial "site-footer.html" .}}{{ end }}
   </body>
diff --git a/documentation/themes/beastie/layouts/articles/total-list.html b/documentation/themes/beastie/layouts/articles/total-list.html
index 1a279510ad..e266ed2618 100644
--- a/documentation/themes/beastie/layouts/articles/total-list.html
+++ b/documentation/themes/beastie/layouts/articles/total-list.html
@@ -1,6 +1,6 @@
 {{ define "main" }}
 <main class="main-wrapper">
-  <div class="article">
+  <div class="document">
     {{ .Content }}
   </div>
 </main>
diff --git a/documentation/themes/beastie/layouts/books/total-list.html b/documentation/themes/beastie/layouts/books/total-list.html
index 1a279510ad..e266ed2618 100644
--- a/documentation/themes/beastie/layouts/books/total-list.html
+++ b/documentation/themes/beastie/layouts/books/total-list.html
@@ -1,6 +1,6 @@
 {{ define "main" }}
 <main class="main-wrapper">
-  <div class="article">
+  <div class="document">
     {{ .Content }}
   </div>
 </main>
diff --git a/documentation/themes/beastie/layouts/index.html b/documentation/themes/beastie/layouts/index.html
index ac491fa7cd..6ee1b26a3b 100644
--- a/documentation/themes/beastie/layouts/index.html
+++ b/documentation/themes/beastie/layouts/index.html
@@ -8,65 +8,59 @@
   <main class="main-wrapper">
     {{ partial "global-search.html" . }}
     <section class="cards-container">
-      <div class="row">
-        <div class="card">
-          <a href={{ "books/handbook/basics" | absLangURL }}>
-            <h5>{{ i18n "getting-started" }}</h5>
-            <p>{{ i18n "learn-basics" }}</p>
-          </a>
-        </div>
-        <div class="card">
-          <a href={{ printf "%s%s/%s" $.Site.Params.websiteURL $language "where" }}>
-            <h5>{{ i18n "download" }}</h5>
-            <p>{{ i18n "download-freebsd" }}</p>
-          </a>
-        </div>
-        <div class="card">
-          <a href={{ "books/handbook/" | absLangURL }}>
-            <h5>{{ i18n "handbook" }}</h5>
-            <p>{{ i18n "handbook-desc" }}</p>
-          </a>
-        </div>
+      <div class="card">
+        <a href={{ "books/handbook/basics" | absLangURL }}>
+          <h5>{{ i18n "getting-started" }}</h5>
+          <p>{{ i18n "learn-basics" }}</p>
+        </a>
       </div>
-      <div class="row">
-        <div class="card">
-          <a href={{ "books/porters-handbook/" | absLangURL }}>
-            <h5>{{ i18n "porters-handbook" }}</h5>
-            <p>{{ i18n "porters-handbook-desc" }}</p>
-          </a>
-        </div>
-        <div class="card">
-          <a href={{ "books/faq/" | absLangURL }}>
-            <h5>{{ i18n "faq" }}</h5>
-            <p>{{ i18n "faq-desc" }}</p>
-          </a>
-        </div>
-        <div class="card">
-          <a href="https://docs.FreeBSD.org/en/books/fdp-primer/">
-            <h5>{{ i18n "fdp" }}</h5>
-            <p>{{ i18n "fdp-desc" }}</p>
-          </a>
-        </div>
+      <div class="card">
+        <a href={{ printf "%s%s/%s" $.Site.Params.websiteURL $language "where" }}>
+          <h5>{{ i18n "download" }}</h5>
+          <p>{{ i18n "download-freebsd" }}</p>
+        </a>
       </div>
-      <div class="row">
-        <div class="card">
-          <a href={{ "books" | absLangURL }}>
-            <h5>{{ i18n "books" }}</h5>
-            <p>{{ i18n "books-list" }}</p>
-          </a>
-        </div>
-        <div class="card">
-          <a href={{ "articles" | absLangURL }}>
-            <h5>{{ i18n "articles" }}</h5>
-            <p>{{ i18n "articles-list" }}</p>
-          </a>
-        </div>
-        <div class="card">
-          <a href="https://www.FreeBSD.org/cgi/man.cgi">
-            <h5>{{ i18n "manual-pages" }}</h5>
-            <p>{{ i18n "manual-pages-desc" }}</p>
-          </a>
-        </div>
+      <div class="card">
+        <a href={{ "books/handbook/" | absLangURL }}>
+          <h5>{{ i18n "handbook" }}</h5>
+          <p>{{ i18n "handbook-desc" }}</p>
+        </a>
+      </div>
+      <div class="card">
+        <a href={{ "books/porters-handbook/" | absLangURL }}>
+          <h5>{{ i18n "porters-handbook" }}</h5>
+          <p>{{ i18n "porters-handbook-desc" }}</p>
+        </a>
+      </div>
+      <div class="card">
+        <a href={{ "books/faq/" | absLangURL }}>
+          <h5>{{ i18n "faq" }}</h5>
+          <p>{{ i18n "faq-desc" }}</p>
+        </a>
+      </div>
+      <div class="card">
+        <a href="https://docs.FreeBSD.org/en/books/fdp-primer/">
+          <h5>{{ i18n "fdp" }}</h5>
+          <p>{{ i18n "fdp-desc" }}</p>
+        </a>
+      </div>
+      <div class="card">
+        <a href={{ "books" | absLangURL }}>
+          <h5>{{ i18n "books" }}</h5>
+          <p>{{ i18n "books-list" }}</p>
+        </a>
+      </div>
+      <div class="card">
+        <a href={{ "articles" | absLangURL }}>
+          <h5>{{ i18n "articles" }}</h5>
+          <p>{{ i18n "articles-list" }}</p>
+        </a>
+      </div>
+      <div class="card">
+        <a href="https://www.FreeBSD.org/cgi/man.cgi">
+          <h5>{{ i18n "manual-pages" }}</h5>
+          <p>{{ i18n "manual-pages-desc" }}</p>
+        </a>
       </div>
     </section>
   </main>
diff --git a/documentation/themes/beastie/layouts/partials/site-footer.html b/documentation/themes/beastie/layouts/partials/site-footer.html
index 015be73356..be343f7545 100755
--- a/documentation/themes/beastie/layouts/partials/site-footer.html
+++ b/documentation/themes/beastie/layouts/partials/site-footer.html
@@ -107,7 +107,7 @@
       </section>
       <section class="copyright-column">
         <p>&copy; 1994-{{ now.Format "2006" }} {{ i18n "f-all-rights-reserved" }}</p>
-        <span>{{ i18n "f-made-with" }} <span class="heart"><i class="fa fa-heart" aria-hidden="true"></i></span>{{ i18n "f-by-freebsd-community" }}</span>
+        <span>{{ i18n "f-made-with" }} <span class="heart">♥</span> {{ i18n "f-by-freebsd-community" }}</span>
       </section>
   </div>
 </footer>
diff --git a/documentation/themes/beastie/layouts/partials/site-header.html b/documentation/themes/beastie/layouts/partials/site-header.html
index 18480e6d3e..96341eb4ae 100755
--- a/documentation/themes/beastie/layouts/partials/site-header.html
+++ b/documentation/themes/beastie/layouts/partials/site-header.html
@@ -98,7 +98,7 @@
       </form>
       <div class="donate">
         <a href="https://freebsdfoundation.org/donate/" target="_blank">
-          <i class="fa fa-heart" aria-hidden="true"></i>
+          <span class="heart">♥</span>
           {{ i18n "h-donate" }}
         </a>
       </div>
diff --git a/documentation/themes/beastie/layouts/shortcodes/list-articles-directories.html b/documentation/themes/beastie/layouts/shortcodes/list-articles-directories.html
index 6105d1e874..843300d4aa 100644
--- a/documentation/themes/beastie/layouts/shortcodes/list-articles-directories.html
+++ b/documentation/themes/beastie/layouts/shortcodes/list-articles-directories.html
@@ -26,7 +26,7 @@
   {{ end }}
 {{ end }}
 
-<ul class="articles-books-list">
+<ul class="documents-list">
 {{ range sort $articles "weight" "path" }}
   {{ if in .path "_index.adoc" }}
     {{ $articlePath := replaceRE "/_index.adoc" "" .path }}
diff --git a/documentation/themes/beastie/layouts/shortcodes/list-books-directories.html b/documentation/themes/beastie/layouts/shortcodes/list-books-directories.html
index 46e8aef165..10df5da34c 100644
--- a/documentation/themes/beastie/layouts/shortcodes/list-books-directories.html
+++ b/documentation/themes/beastie/layouts/shortcodes/list-books-directories.html
@@ -26,7 +26,7 @@
   {{ end }}
 {{ end }}
 
-<ul class="articles-books-list">
+<ul class="documents-list">
 {{ range sort $books "bookOrder" "path" }}
   {{ if in .path "_index.adoc" }}
     {{ $bookPath := replaceRE "/_index.adoc" "" .path }}