Content: Replace with data attribute grid system

exampleSite/content/_index.md

@@ -0,0 +1,18 @@
+---
+title: Example Site for NGINX Hugo Theme
+description: 
+---
+
+## NGINX Hugo Theme Documentation 
+Documentation for hugo theme
+{{<card-layout>}}
+  {{<card-section showAsCards="true">}}
+    {{<card title="Test Product" titleUrl="/test-product/" icon="test-tubes"  isLanding="true">}}
+      See explanations and usages of shortcodes
+    {{</card >}}
+    {{<card title="NGINX Plus" titleUrl="/nginx/" brandIcon="NGINX-Plus-product-icon-RGB"  isLanding="true">}}
+      See a live example of theme components
+    {{</card >}}
+  {{</card-section>}}
+{{</card-layout>}}
+

exampleSite/content/test-product/call-out/all-callouts.md

@@ -25,15 +25,15 @@ This is a plain callout with a default title for its type. It has a [link](#plai
 
 Naturally, callouts should contain less text within them than the text it lives next to. We do this for several reasons. Firstly, it looks weird to have a big empty space in the primary content area. Secondly, if you have more text in the callout, then it stops being a callout. I have asked an LLM to lengthen this passage.
 
-{{<call-out "side-callout">}}
+{{<call-out sideline="true">}}
 This is a plain side callout with no title. It has a [link](#plain-callouts) to a heading on this page. Its shortcode is `<call-out>` with the `.side-callout` class.
 {{</call-out>}}
 
 When designing effective web layouts, it's important to maintain proper balance between primary content and supplementary elements. Callouts serve as attention-grabbing devices that highlight key information, but they should remain subordinate to the main content flow. This hierarchy helps users navigate your page intuitively, guiding their attention appropriately. A well-designed callout complements the surrounding text rather than competing with it.
 
 Additionally, concise callouts tend to be more effective at capturing user attention. When a callout becomes too verbose, users are less likely to read it entirely, defeating its purpose. The visual weight of callouts should align with their informational importance - brief, impactful statements create better engagement than lengthy explanations. Remember that white space itself is a powerful design element, creating visual breathing room that enhances readability and focus. Ultimately, the most successful callouts follow the principle of "less is more," delivering maximum impact through minimal interruption to the user's reading experience.
 
-{{<call-out "side-callout" "Custom title">}}
+{{<call-out sideline="true" title="Custom title">}}
 This is a plain side callout with a custom title. It has a [link](#plain-callouts) to a heading on this page. Its shortcode is `<call-out>` with the `.side-callout` class, and a custom title.
 {{</call-out>}}
 
@@ -84,4 +84,4 @@ This is `<before-you-begin>`.
 
 {{<see-also>}}
 This is `<see-also>`.
-{{</see-also>}}
+{{</see-also>}}

exampleSite/content/test-product/cards/_index.md

@@ -0,0 +1,5 @@
+---
+description: Card usage
+title: Cards
+weight: 300
+---

exampleSite/content/test-product/cards/permitted.md

@@ -0,0 +1,120 @@
+---
+description: Card usage
+title: Usage
+weight: 100
+---
+## General usage
+The structure of a card looks like the following:
+```plaintext
+<card-layout >
+    <card-section>
+        <card title="SOME_TITLE">SOME CONTENT icon="SOME_LUCIDE_ICON"><\card>
+        ...
+        <card>SOME CONTENT<\card>
+    </card-section>
+</card-layout >
+```
+
+and will render as the following:
+<div data-testid="cards-test__basic">
+  {{<card-layout >}}
+    {{<card-section>}}
+      {{<card title="SOME_TITLE">}}
+        SOME CONTENT
+      {{</card >}}
+    {{</card-section>}}
+  {{</card-layout >}}
+</div>
+
+### Params 
+To support customization, there are also some params you can add to the shortcode `<card>` such as `title`, `titleUrl`, `icon`, `brandIcon`, `isFeaturedCard`, `isFullSize`.
+
+* `title` (required) - Title of the card. 
+<br>
+* `titleUrl` (optional) - URL for the card.
+<br>
+* `icon` (optional) - Custom icon using <a href="https://lucide.dev/icons/">lucide</a> icons.
+<br>
+* `brandIcon` (optional) - Custom icon using image from  `nginx-hugo-theme/static/images/icons`.
+  * Usage: `<card brandIcon="NGINX-App-Protect-WAF-product-icon"...>`
+<br>
+* `isFeaturedCard` (optional) - Boolean indicating whether or not the card should be the first one and full size. By default, false.
+  * Usage: `<card isFeaturedCard="true"...>`
+<br>
+* `isFullSize` (optional) - Boolean indicating whether or not the card should be full size. By default, cards are half sized.
+  * Usage: `<card isFullSize="true"...>`
+
+For the `<card-section>`, there are some params you can add such as `title`, `isFeaturedSection`, and `showAsCards`.
+* `title` - Title of the section.
+<br>
+* `isFeaturedSection` (optional) - Boolean indicating whether or not the section is a featured one - will discuss later down the page. By default, false.
+<br> 
+* `showAsCards` (optional) - Boolean indicating whether or not the cards in the section should appear with borders. By default, false.
+
+### Additional Information
+While it may come immediate, you can't use a `<card>` shortcode on its own in your markdown or else the build will fail. This is because if you call a card, there is no way to structure it in a writer-friendly customizable way. 
+
+## Show as cards
+As you can see from the above example in 'General usage', it renders as a plain box that does not resemble a card. To change the appearance and render as a card, use the param `showAsCards` in the shortcode `<card-section>`. The usage as seen below:
+```plaintext
+<card-layout >
+    <card-section showAsCards="true">
+        <card title="SOME_TITLE">SOME CONTENT icon="SOME_LUCIDE_ICON"><\card>
+        ...
+        <card>SOME CONTENT<\card>
+    </card-section>
+</card-layout >
+```
+and will render as the following:
+<div data-testid="cards-test__showAsCards">
+  {{<card-layout >}}
+    {{<card-section showAsCards="true">}}
+      {{<card title="SOME_TITLE">}}
+        SOME CONTENT
+      {{</card >}}
+    {{</card-section>}}
+  {{</card-layout >}}
+</div>
+
+## Featured Section
+Denoted by the param `isFeaturedSection` in the shortcode `<card-layout>`, this block of cards can contain only up to three cards.
+
+<div data-testid="cards-test__featuredSection">
+  {{<card-layout >}}
+    {{<card-section showAsCards="true" isFeaturedSection="true">}}
+      {{<card title="Everything" titleUrl="everything" icon="circle-dot-dashed">}}
+        All shortcodes in one page.
+      {{</card >}}
+      {{<card title="Call Out usages" titleUrl="call-out/all-callouts/" icon="message-square">}}
+        Examples for call-out shortcode
+      {{</card >}}
+      {{<card title="Code Block usages" titleUrl="code-blocks/code-blocks-highlighting/" icon="code">}}
+        Examples for codeblock shortcode
+      {{</card >}}
+      {{<card title="Code Block usages" titleUrl="code-blocks/code-blocks-highlighting/" icon="code">}}
+        Examples for codeblock shortcode
+      {{</card >}}
+    {{</card-section>}}
+  {{</card-layout >}}
+</div>
+
+## Featured Card
+Denoted by the param `isFeaturedCard` in the shortcode `<card>`, this will push the card up to very top of the section and make it full length.
+<div data-testid="cards-test__featuredCard">
+  {{<card-layout >}}
+    {{<card-section showAsCards="true">}}
+      {{<card title="Everything" titleUrl="everything" icon="circle-dot-dashed">}}
+        All shortcodes in one page.
+      {{</card >}}
+      {{<card title="Call Out usages" titleUrl="call-out/all-callouts/" icon="message-square">}}
+        Examples for call-out shortcode
+      {{</card >}}
+      {{<card title="Code Block usages" titleUrl="code-blocks/code-blocks-highlighting/" icon="code" isFeaturedCard="true">}}
+        Examples for codeblock shortcode
+      {{</card >}}
+      {{<card title="Code Block usages" titleUrl="code-blocks/code-blocks-highlighting/" icon="code">}}
+        Examples for codeblock shortcode
+      {{</card >}}
+    {{</card-section>}}
+  {{</card-layout >}}
+</div>

exampleSite/layouts/index.html

@@ -1,16 +1,3 @@
 {{ define "main" }}
-
-<h1>Homepage Example</h1>
-<p>
-    <ul>
-        <li>
-            <a href="{{ relref . "nginx" }}">NGINX and NGINX Plus</a>
-        </li>
-        <li>
-            <a href="{{ relref . "test-product" }}">Test Product</a>
-        </li>
-    </ul>
-</p>
-
-
+{{ partial "homepage.html" . }}
 {{end}}

layouts/_default/list.html

@@ -1,16 +1,14 @@
 {{ define "main" }}
 
 <main class="content " role="main">
-<section class="main-layout">
-    <section id="maincontent" class="content-layout">
     <div data-cms-edit="content" class="text-content list-page">
-        <section class="breadcrumb-layout wide">
+        <div class="breadcrumb-layout">
         {{ if not .IsHome }}
             {{ if not (in .Params.display_breadcrumb "false" ) }}
             {{ partial "breadcrumb" .}}
             {{ end }}
         {{ end }}
-        </section>
+        </div>
         <div class="list-header-container">
           <img src="/images/icons/{{ .Params.logo | default "NGINX-product-icon.svg" }}">
           <div class="list-header-title">
@@ -42,8 +40,7 @@ <h2>
         {{ end }}
 
     </div>
-    </section>
-</section>
+
 </main>
 
 

layouts/_default/single.html

@@ -1,28 +1,25 @@
 {{ define "main" }}
-
 <main class="content">
     <!-- Replace icons -->
     {{ $content := partial "icon-replacement.html" (dict "content" .Content) }}
 
-
-    <section class="main-layout">
-    <section id="maincontent" class="content-layout">
-        <div data-cms-edit="content" class="text-content">
-        <section class="breadcrumb-layout wide">
-            {{ if not .IsHome }}
-            {{ if not (in .Params.display_breadcrumb "false" ) }}
-            {{ partial "breadcrumb" .}}
-            {{ end }}
-            {{ end }}
-        </section>
+    <div class="breadcrumb-layout">
+        {{ if not .IsHome }}
+        {{ if not (in .Params.display_breadcrumb "false" ) }}
+        {{ partial "breadcrumb" .}}
+        {{ end }}
+        {{ end }}
+    </div>
+    <article data-cms-edit="content" >
         {{ partial "banner" .}}
+
         <h1>{{ .Title }}</h1>
+
         {{ $content | safeHTML }}
+
         {{ if eq .Page.Draft true }}{{ partial "draft-badge.html" . }}{{ end }}
         {{ if in .Params.doctypes "beta" }}{{ partial "beta-badge" . }}{{ end }}
 
-        <hr>
-
         {{ if .Page.Lastmod }}
         <div class="last-modified">
             {{ partial "page-meta-links" . }}
@@ -46,6 +43,4 @@ <h1>{{ .Title }}</h1>
 
 
 
-
-
 {{ end }}

layouts/partials/callout.html

@@ -13,10 +13,10 @@
 {{ $sideOption := "side-callout" }}
 {{ $inlineOption := "inline-callout" }}
 
+{{/*  Default to inline callout  */}}
+{{ $dataGrid := "first-two-thirds" }}
 {{ if $sideline }}
-  {{ $class = printf "%s %s" $class $sideOption }}
-{{ else }}
-  {{ $class = printf "%s %s" $class $inlineOption }}
+  {{ $dataGrid = "last-third" }}
 {{ end }}
 
 {{/*  Render a different block, if "loud" callouts are used  */}}
@@ -33,7 +33,7 @@
 {{ $isSpecialTitle := in $specialTitles $type }}
 {{ if $isSpecialTitle }}
 {{/*  Loud callouts  */}}
-<blockquote class="{{ $class }}">
+<blockquote class="{{ $class }}" data-grid="{{ $dataGrid }}">
   <div>
     <div class="call-out-type">
       {{ partial "feather" (dict "context" . "icon" $icon) .}}
@@ -51,7 +51,7 @@
 
 {{ $cleanTitle := strings.TrimSuffix ":" $title}}
 
-<blockquote class="{{ $class }} note" data-title="{{ $cleanTitle }}">
+<blockquote class="{{ $class }} note" data-title="{{ $cleanTitle }}" data-grid="{{ $dataGrid }}">
   <div class="callout-content">
     {{- with $icon -}}
       <i class="{{ . }}"></i>

layouts/partials/homepage.html

@@ -0,0 +1,5 @@
+<div class="homepage">
+  <div class="homepage-section">
+    {{ .Content }}
+  </div>
+</div>

layouts/shortcodes/card-layout.html

@@ -1,2 +1,2 @@
 <!-- Render the main content first with modifications, then render the custom content -->
-<div class="card-layout">{{- .Inner | markdownify -}}</div>
+<div class="card-layout" data-testid="card-layout">{{- .Inner | markdownify -}}</div>

layouts/shortcodes/card-section.html

@@ -1,6 +1,7 @@
 {{ $title := .Get "title" }}
 {{ $isFeaturedSectionParam := .Get "isFeaturedSection" | default "false" }}
 {{ $showAsCardsParam := .Get "showAsCards" | default "false"}}
+
 {{- /* Validate the parameter strictly */ -}}
 {{- if not (in (slice "true" "false") $showAsCardsParam) -}}
   {{- warnf "The '<card-section>' Shortcode parameter 'showAsCards' must be 'true' or 'false', but got: '%s'. This will now default to 'false'" $showAsCardsParam -}}
@@ -15,14 +16,18 @@
 {{- end -}}
 {{- $isFeaturedSection := cond (eq $isFeaturedSectionParam "true") "true" "false" -}}
 {{- $class := "card-grid" -}}
+
+{{- /* Get number of cards */ -}}
+{{ $cardCount := len (findRE "<div\\s+class=\"card\"[\\s\\S]*?>" .Inner) }}
+
 {{- /* Validate that the parent is card-layout */ -}}
 {{ if eq .Parent.Name "card-layout"}}
-  <div class="card-section {{if eq $isFeaturedSection "true"}}featured-section{{ end }}">
+  <div class="card-section {{if eq $isFeaturedSection "true"}}featured-section{{ end }}" data-testid="{{if eq $isFeaturedSection "true"}}card-section__featured-section{{else}}card-section{{ end }}">
     {{- if $title -}}
       <strong class="card-section-title">{{- $title -}}</strong>
-      <div class="card-section-content{{ if eq $showAsCards "true" }} {{ $class }} {{ end }}">{{- .Inner -}}</div>    
+      <div class="card-section-content{{ if eq $showAsCards "true" }} {{ $class }}{{ end }}" data-testid="{{ if eq $showAsCards "true" }}card-section-content__card-grid{{else}}card-section-content{{ end }}">{{ .Inner }}</div>    
     {{ else }}
-      <div class="card-section-content{{ if eq $showAsCards "true" }} {{ $class }} {{ end }}">{{ .Inner }}</div>    
+      <div class="card-section-content{{ if eq $showAsCards "true" }} {{ $class }}{{ end }}" data-testid="{{ if eq $showAsCards "true" }}card-section-content__card-grid{{else}}card-section-content{{ end }}">{{ .Inner }}</div>    
     {{ end }}
   </div>
 {{ else }}