Repository: omsf/playbooks-website
Pull request #36: Layout updates: Simple Implementations
Author: login: dwhswenson
Created: 2025-04-11T16:43:41Z | Merged: 2025-04-14T19:42:55Z

These some updates for layouts and CSS, especially around the "Implementations" on practice pages.

* Adds an `implementations-simple` class that gives a normal `ul` style for cases where implementations lists don't include advantages and disadvantages
* Adds a little spacing around the implementations div (previously seemed a bit crowded to both top and bottom
* Adds a bit more spacing between advantages/disadvantages when they're side-by-side
* Removes the contributions quiz (can easily be added back later)

These are CSS/layout changes for the existing site, in advance of changes to match this to OMSF styles.


Diff:
diff --git a/.lycheeignore b/.lycheeignore
index 5ba557a..4cfa1ea 100644
--- a/.lycheeignore
+++ b/.lycheeignore
@@ -1 +1,2 @@
 https://www.atlassian.com/software/jira
+https://valgrind.org/
diff --git a/assets/css/custom.css b/assets/css/custom.css
index 29cbeb0..e25c1f4 100644
--- a/assets/css/custom.css
+++ b/assets/css/custom.css
@@ -219,6 +219,7 @@ article {
 }
 
 .disadvantages {
+    margin-left: 1em;
     flex: 1;
 }
 
@@ -228,7 +229,10 @@ article {
     }
     .advantages {
         margin-right: 0;
-        margin-left: 0;
+        margin-left: 1em;
+    }
+    .disadvantages {
+        margin-left: 1em;
     }
 }
 
@@ -248,14 +252,21 @@ article {
 /* practice pages */
 section.frontmatter {
     border: 1px solid #ccc;
-    padding: 1em;
+    padding-top: 1em;
+    padding-left: 1em;
+    padding-right: 1em;
+    padding-bottom: 0em;  /* each frontmatter-section has bottom margin */
     margin: 1em;
 }
 
 .frontmatter-section {
+    width: 100%;
+    margin-bottom: 1em;
+}
+
+.required {
     display: grid;
     grid-template-columns: 6em 1fr;
-    width: 100%;
 }
 
 .frontmatter-section .label {
@@ -271,12 +282,22 @@ section.frontmatter {
     content: ":";
 }
 
-.implementation {
-    border: 1px solid #ccc;
+div .frontmatter-title {
+    width: 100%;
+}
+
+ul.implementations div.implementation {
+    margin-top: 0.5em;
     margin-left: 1em;
+    padding: 0.5em;
+}
+
+ul.implementations-simple {
+    list-style: initial;;
+    padding-left: 1.5em;
 }
 
-.implementation:nth-child(odd) div {
+ul.implementations li:nth-child(odd) div {
     background: var(--striping-color);
 }
 
diff --git a/content/contributions/quiz.md b/content/contributions/quiz.md
deleted file mode 100644
index e0f0329..0000000
--- a/content/contributions/quiz.md
+++ /dev/null
@@ -1,6 +0,0 @@
----
-title: Quiz and Badge
-layout: quiz
-badge_name: OMSF Contributions Best Practices
----
-
diff --git a/layouts/_default/practice.html b/layouts/_default/practice.html
index ff8e0e1..ffd327b 100644
--- a/layouts/_default/practice.html
+++ b/layouts/_default/practice.html
@@ -9,13 +9,9 @@
       </section>
       <h2>{{ .Title }}</h2>
       <section class="frontmatter">
-        <div class="frontmatter-section">
+        <div class="frontmatter-section required">
           <div class="label">What</div><div class="values">{{ .Params.what }}</div>
-        </div>
-        <div class="frontmatter-section">
           <div class="label">Why</div><div class="values">{{ .Params.why }}</div>
-        </div>
-        <div class="frontmatter-section">
           <div class="label">When</div><div class="values">{{ .Params.when }}</div>
         </div>
 
@@ -33,30 +29,39 @@ <h2>{{ .Title }}</h2>
       {{ end }}
 
       {{ if .Params.implementations }}
-      <div class="implementations"><b>Implementations:</b>
-      {{/* hasAdv might not longer be needed */}}
-      {{ $hasAdv := where .Params.implementations "isset advantages" true }}
-        <ul class="implementations">
+
+      {{/* figure out if we have details or not */}}
+      {{ $.Scratch.Set "ulclassname" "implementations-simple" }}
+      {{ range .Params.implementations }}
+      {{ if or .advantages .disadvantages }}
+      {{ $.Scratch.Set "ulclassname" "implementations" }}
+      {{ break }}
+      {{ end }}
+      {{ end }}
+
+      <div class="implementations frontmatter-section">
+      <b>Implementations:</b>
+      <ul class="{{ $.Scratch.Get "ulclassname" }}">
         {{ range $impl := .Params.implementations }}
-          <div class="implementation">
+        <li><div class="implementation">
             <div class="impl-desc">{{ $impl.desc | markdownify }}</div>
             {{ if (or $impl.advantages $impl.disadvantages) }}
             {{ partial "advantages-disadvantages.html" $impl }}
             {{ end }}
-          </div>
+            </div></li>
         {{ end }}
         </ul>
       </div>
       {{ end }}
 
       {{ if .Params.recommendation }}
-      <div class="recommendation"><b>Recommendation:</b>
+      <div class="recommendation frontmatter-section"><b>Recommendation:</b>
       {{ .Params.recommendation }}
       </div>
       {{ end }}
 
       {{ if .Params.see_also }}
-      <div class="see-also"><b>See also:</b>
+      <div class="see-also frontmatter-section"><b>See also:</b>
       <ul>
       {{ range $also := .Params.see_also }}
         <li>{{ $also | markdownify }}</li>
@@ -66,7 +71,7 @@ <h2>{{ .Title }}</h2>
       {{ end }}
 
       {{ if .Params.note }}
-      <div class="note"><i>Note:</i> {{ .Params.note }}</div>
+      <div class="note frontmatter-section"><i>Note:</i> {{ .Params.note }}</div>
       {{ end }}
   </section>
   <section class="content">


Reviews:
user: login: copilot-pull-request-reviewer[bot]
body: 

Copilot reviewed 2 out of 3 changed files in this pull request and generated 1 comment.

<details>
<summary>Files not reviewed (1)</summary>

* **assets/css/custom.css**: Language not supported
</details>

<details>
<summary>Comments suppressed due to low confidence (1)</summary>

**layouts/_default/practice.html:38**
* [nitpick] Consider renaming 'ulclassname' to a more descriptive and consistent name such as 'implementationListClass' for improved readability.
```
{{ $.Scratch.Set "ulclassname" "implementations-simple" }}
```
</details>


state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-11T16:44:11Z
user: login: ethanholz
state: CHANGES_REQUESTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-11T19:04:03Z
user: login: ethanholz
body: LGTM
state: APPROVED
author_association: CONTRIBUTOR
submitted_at: 2025-04-14T19:42:45Z

Review comments:
diff_hunk: @@ -33,17 +33,24 @@ <h2>{{ .Title }}</h2>
       {{ end }}
 
       {{ if .Params.implementations }}
+
+      {{/* figure out if we have details or not */}}
+      {{ $.Scratch.Set "ulclassname" "implementations-simple" }}
+        {{ range .Params.implementations }}
+        {{ if or .advantages .disadvantages }}
+        {{ $.Scratch.Set "ulclassname" "implementations" }}
+        {{ end }}
+      {{ end }}
path: layouts/_default/practice.html
user: login: Copilot
body: [nitpick] If the list of implementations is large, consider breaking out of the loop after finding a single entry with details to avoid unnecessary iterations.
```suggestion
      {{ range .Params.implementations }}
      {{ if or .advantages .disadvantages }}
      {{ $.Scratch.Set "ulclassname" "implementations" }}
      {{ break }}
      {{ end }}
      {{ end }}
```
created_at: 2025-04-11T16:44:11Z
author_association: CONTRIBUTOR
diff_hunk: @@ -271,12 +275,22 @@ section.frontmatter {
     content: ":";
 }
 
-.implementation {
+div .implementations {
+    margin-top: 0.5em;
path: assets/css/custom.css
user: login: ethanholz
body: Not sure if we really should add a top margin here since we don't have top margins for the other elements in of this type. Bottom margin is okay. Ideally, I would like to see that all the frontmatter headings have the same margins to keep everything consistent.
created_at: 2025-04-11T19:03:46Z
author_association: CONTRIBUTOR

PR comments:
user: login: github-actions[bot]
created_at: 2025-04-11T16:56:17Z
body: This PR has been staged at https://fe683b98.omsf-playbooks.pages.dev.

It has been updated for commit 79ee6c49732ec2a78fb21c12f2e5c7e2092308ff.
<!-- Sticky Pull Request Comment -->
author_association: NONE
user: login: dwhswenson
created_at: 2025-04-11T16:59:32Z
body: Examples of where this affects things.

Implementation with advantages/disadvantages (a bit more spacing):
* Current: https://omsf-playbooks.pages.dev/developer/code-style-and-quality/enforce-your-chosen-code-style/
* These changes: https://pr36.omsf-playbooks.pages.dev/developer/code-style-and-quality/enforce-your-chosen-code-style/

Implementation without advantages/disadvantages (much nicer, IMO, styling of the list items):
* Current: https://omsf-playbooks.pages.dev/developer/code-style-and-quality/minimize-code-complexity/
* These changes: https://pr36.omsf-playbooks.pages.dev/developer/code-style-and-quality/minimize-code-complexity/
author_association: MEMBER
user: login: ethanholz
created_at: 2025-04-11T19:07:36Z
body: Additionally, I would recommend changing the corner here (see below) so that we a bit more spacing. Ideally we probably want to try styling this section with _too much_ space and then pair it down later. The alternative might be to try centering implementation name to give more space. Might also want to play with bolding or changing the weight of the font that the implementations don't get lost. 
![image](https://github.com/user-attachments/assets/29082da6-8f75-4cec-ab47-8cca0d368aee)

author_association: CONTRIBUTOR
user: login: ethanholz
created_at: 2025-04-11T19:12:03Z
body: Looking into this further, it might be worth removing the borders here as the reduce the amount of space between components.
author_association: CONTRIBUTOR
user: login: dwhswenson
created_at: 2025-04-14T18:00:12Z
body: @ethanholz : Take another look! Updated to:

* Give more space around the implementation boxes
* Give all frontmatter-sections a bottom margin, and use that as the basis of keeping them separate
* Remove the border around the individual implementations.
author_association: MEMBER
user: login: ethanholz
created_at: 2025-04-14T19:42:33Z
body: This looks so much better! I love it! You could potentially, remove the outside border of the entire frontamtter section but I think this is awesome! Going to merge this!
author_association: CONTRIBUTOR