Skip to content

Commit ed1e035

Browse files
nginx-jacklamATnginx
nginx-jack
and
lamATnginx
authored
Content: Replace with data attribute grid system (#304)
* Content: Replace with data attribute grid system Add .content class to handle overall content reflow Use scaling fonts Refactor call outs to use grid utilities TODO: Standard mobile sizes horz scroll on some pages TODO: Homepage update to use grid utility TODO: List card layout update to use grid utility * Cards: Replace with data-grid * Cards: Small tweaks * Codeblock: Make highlighted lines stretch to end + fix border * Homepage: Replace with data-grid and cards shortcode * Scroll: Fixed issue with pages overflowing on mobile * Breadcrumb: Cleaned up unused code with wide * Fixed redocly responsive on new grid (#307) * Redoc: Fixed responsive on new grid * Redoc: Fix issue with redocly not going under header * Codeblock: Extend highlight to left side * Cards: Make cards fully clickable + small bug fix with grid ordering * Add new 'card' page to example site + new tests for cards (#305) * Cards: Replace with data-grid * Cards: Add new page to example site * Cards: Add tests * Cards: Small tweaks * Cards: Updated card params in example site * Cards: Fix bugs with the card due to merge * Grid: Resolved issue with grid on mobile * Banner: Add spacing * Card: Fixed relative pathing --------- Co-authored-by: Lam Nguyen <[email protected]> Co-authored-by: Lam <[email protected]>
1 parent 9db8c04 commit ed1e035

File tree

16 files changed

+546
-254
lines changed

16 files changed

+546
-254
lines changed

‎assets/css/v2/style.css

Lines changed: 252 additions & 188 deletions
Large diffs are not rendered by default.

‎exampleSite/content/_index.md

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
---
2+
title: Example Site for NGINX Hugo Theme
3+
description:
4+
---
5+
6+
## NGINX Hugo Theme Documentation
7+
Documentation for hugo theme
8+
{{<card-layout>}}
9+
{{<card-section showAsCards="true">}}
10+
{{<card title="Test Product" titleUrl="test-product/" icon="test-tubes" isLanding="true">}}
11+
See explanations and usages of shortcodes
12+
{{</card >}}
13+
{{<card title="NGINX Plus" titleUrl="nginx/" brandIcon="NGINX-Plus-product-icon-RGB" isLanding="true">}}
14+
See a live example of theme components
15+
{{</card >}}
16+
{{</card-section>}}
17+
{{</card-layout>}}
18+

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,7 @@ This is a compilation of all our shortcodes to show how they look, function, res
5454

5555
{{<card-layout >}}
5656
{{<card-section title="NGINX" showAsCards="true" >}}
57-
{{<card title="NGINX Plus" titleUrl="/nginx/" brandIcon="NGINX-Plus-product-icon-RGB" >}}
57+
{{<card title="NGINX Plus" titleUrl="nginx/" brandIcon="NGINX-Plus-product-icon-RGB" >}}
5858
Installing NGINX
5959
{{</card >}}
6060
{{</card-section >}}

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

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -25,15 +25,15 @@ This is a plain callout with a default title for its type. It has a [link](#plai
2525

2626
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.
2727

28-
{{<call-out "side-callout">}}
28+
{{<call-out sideline="true">}}
2929
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.
3030
{{</call-out>}}
3131

3232
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.
3333

3434
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.
3535

36-
{{<call-out "side-callout" "Custom title">}}
36+
{{<call-out sideline="true" title="Custom title">}}
3737
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.
3838
{{</call-out>}}
3939

@@ -84,4 +84,4 @@ This is `<before-you-begin>`.
8484

8585
{{<see-also>}}
8686
This is `<see-also>`.
87-
{{</see-also>}}
87+
{{</see-also>}}

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

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
description: Card usage
3+
title: Cards
4+
weight: 300
5+
---

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

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
---
2+
description: Card usage
3+
title: Usage
4+
weight: 100
5+
---
6+
## General usage
7+
The structure of a card looks like the following:
8+
```plaintext
9+
<card-layout >
10+
<card-section>
11+
<card title="SOME_TITLE">SOME CONTENT icon="SOME_LUCIDE_ICON"><\card>
12+
...
13+
<card>SOME CONTENT<\card>
14+
</card-section>
15+
</card-layout >
16+
```
17+
18+
and will render as the following:
19+
<div data-testid="cards-test__basic">
20+
{{<card-layout >}}
21+
{{<card-section>}}
22+
{{<card title="SOME_TITLE">}}
23+
SOME CONTENT
24+
{{</card >}}
25+
{{</card-section>}}
26+
{{</card-layout >}}
27+
</div>
28+
29+
### Params
30+
To support customization, there are also some params you can add to the shortcode `<card>` such as `title`, `titleUrl`, `icon`, `brandIcon`, `isFeaturedCard`, `isFullSize`.
31+
32+
* `title` (required) - Title of the card.
33+
<br>
34+
* `titleUrl` (optional) - URL for the card.
35+
<br>
36+
* `icon` (optional) - Custom icon using <a href="https://lucide.dev/icons/">lucide</a> icons.
37+
<br>
38+
* `brandIcon` (optional) - Custom icon using image from `nginx-hugo-theme/static/images/icons`.
39+
* Usage: `<card brandIcon="NGINX-App-Protect-WAF-product-icon"...>`
40+
<br>
41+
* `isFeaturedCard` (optional) - Boolean indicating whether or not the card should be the first one and full size. By default, false.
42+
* Usage: `<card isFeaturedCard="true"...>`
43+
<br>
44+
* `isFullSize` (optional) - Boolean indicating whether or not the card should be full size. By default, cards are half sized.
45+
* Usage: `<card isFullSize="true"...>`
46+
47+
For the `<card-section>`, there are some params you can add such as `title`, `isFeaturedSection`, and `showAsCards`.
48+
* `title` - Title of the section.
49+
<br>
50+
* `isFeaturedSection` (optional) - Boolean indicating whether or not the section is a featured one - will discuss later down the page. By default, false.
51+
<br>
52+
* `showAsCards` (optional) - Boolean indicating whether or not the cards in the section should appear with borders. By default, false.
53+
54+
### Additional Information
55+
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.
56+
57+
## Show as cards
58+
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:
59+
```plaintext
60+
<card-layout >
61+
<card-section showAsCards="true">
62+
<card title="SOME_TITLE">SOME CONTENT icon="SOME_LUCIDE_ICON"><\card>
63+
...
64+
<card>SOME CONTENT<\card>
65+
</card-section>
66+
</card-layout >
67+
```
68+
and will render as the following:
69+
<div data-testid="cards-test__showAsCards">
70+
{{<card-layout >}}
71+
{{<card-section showAsCards="true">}}
72+
{{<card title="SOME_TITLE">}}
73+
SOME CONTENT
74+
{{</card >}}
75+
{{</card-section>}}
76+
{{</card-layout >}}
77+
</div>
78+
79+
## Featured Section
80+
Denoted by the param `isFeaturedSection` in the shortcode `<card-layout>`, this block of cards can contain only up to three cards.
81+
82+
<div data-testid="cards-test__featuredSection">
83+
{{<card-layout >}}
84+
{{<card-section showAsCards="true" isFeaturedSection="true">}}
85+
{{<card title="Everything" titleUrl="everything" icon="circle-dot-dashed">}}
86+
All shortcodes in one page.
87+
{{</card >}}
88+
{{<card title="Call Out usages" titleUrl="call-out/all-callouts/" icon="message-square">}}
89+
Examples for call-out shortcode
90+
{{</card >}}
91+
{{<card title="Code Block usages" titleUrl="code-blocks/code-blocks-highlighting/" icon="code">}}
92+
Examples for codeblock shortcode
93+
{{</card >}}
94+
{{<card title="Code Block usages" titleUrl="code-blocks/code-blocks-highlighting/" icon="code">}}
95+
Examples for codeblock shortcode
96+
{{</card >}}
97+
{{</card-section>}}
98+
{{</card-layout >}}
99+
</div>
100+
101+
## Featured Card
102+
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.
103+
<div data-testid="cards-test__featuredCard">
104+
{{<card-layout >}}
105+
{{<card-section showAsCards="true">}}
106+
{{<card title="Everything" titleUrl="everything" icon="circle-dot-dashed">}}
107+
All shortcodes in one page.
108+
{{</card >}}
109+
{{<card title="Call Out usages" titleUrl="call-out/all-callouts/" icon="message-square">}}
110+
Examples for call-out shortcode
111+
{{</card >}}
112+
{{<card title="Code Block usages" titleUrl="code-blocks/code-blocks-highlighting/" icon="code" isFeaturedCard="true">}}
113+
Examples for codeblock shortcode
114+
{{</card >}}
115+
{{<card title="Code Block usages" titleUrl="code-blocks/code-blocks-highlighting/" icon="code">}}
116+
Examples for codeblock shortcode
117+
{{</card >}}
118+
{{</card-section>}}
119+
{{</card-layout >}}
120+
</div>

‎exampleSite/layouts/index.html

Lines changed: 1 addition & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,3 @@
11
{{ define "main" }}
2-
3-
<h1>Homepage Example</h1>
4-
<p>
5-
<ul>
6-
<li>
7-
<a href="{{ relref . "nginx" }}">NGINX and NGINX Plus</a>
8-
</li>
9-
<li>
10-
<a href="{{ relref . "test-product" }}">Test Product</a>
11-
</li>
12-
</ul>
13-
</p>
14-
15-
2+
{{ partial "homepage.html" . }}
163
{{end}}

‎layouts/_default/list.html

Lines changed: 3 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,14 @@
11
{{ define "main" }}
22

33
<main class="content " role="main">
4-
<section class="main-layout">
5-
<section id="maincontent" class="content-layout">
64
<div data-cms-edit="content" class="text-content list-page">
7-
<section class="breadcrumb-layout wide">
5+
<div class="breadcrumb-layout">
86
{{ if not .IsHome }}
97
{{ if not (in .Params.display_breadcrumb "false" ) }}
108
{{ partial "breadcrumb" .}}
119
{{ end }}
1210
{{ end }}
13-
</section>
11+
</div>
1412
<div class="list-header-container">
1513
<img src="/images/icons/{{ .Params.logo | default "NGINX-product-icon.svg" }}">
1614
<div class="list-header-title">
@@ -42,8 +40,7 @@ <h2>
4240
{{ end }}
4341

4442
</div>
45-
</section>
46-
</section>
43+
4744
</main>
4845

4946

‎layouts/_default/single.html

Lines changed: 11 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,28 +1,25 @@
11
{{ define "main" }}
2-
32
<main class="content">
43
<!-- Replace icons -->
54
{{ $content := partial "icon-replacement.html" (dict "content" .Content) }}
65

7-
8-
<section class="main-layout">
9-
<section id="maincontent" class="content-layout">
10-
<div data-cms-edit="content" class="text-content">
11-
<section class="breadcrumb-layout wide">
12-
{{ if not .IsHome }}
13-
{{ if not (in .Params.display_breadcrumb "false" ) }}
14-
{{ partial "breadcrumb" .}}
15-
{{ end }}
16-
{{ end }}
17-
</section>
6+
<div class="breadcrumb-layout">
7+
{{ if not .IsHome }}
8+
{{ if not (in .Params.display_breadcrumb "false" ) }}
9+
{{ partial "breadcrumb" .}}
10+
{{ end }}
11+
{{ end }}
12+
</div>
13+
<article data-cms-edit="content" >
1814
{{ partial "banner" .}}
15+
1916
<h1>{{ .Title }}</h1>
17+
2018
{{ $content | safeHTML }}
19+
2120
{{ if eq .Page.Draft true }}{{ partial "draft-badge.html" . }}{{ end }}
2221
{{ if in .Params.doctypes "beta" }}{{ partial "beta-badge" . }}{{ end }}
2322

24-
<hr>
25-
2623
{{ if .Page.Lastmod }}
2724
<div class="last-modified">
2825
{{ partial "page-meta-links" . }}
@@ -46,6 +43,4 @@ <h1>{{ .Title }}</h1>
4643

4744

4845

49-
50-
5146
{{ end }}

‎layouts/partials/callout.html

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -13,10 +13,10 @@
1313
{{ $sideOption := "side-callout" }}
1414
{{ $inlineOption := "inline-callout" }}
1515

16+
{{/* Default to inline callout */}}
17+
{{ $dataGrid := "first-two-thirds" }}
1618
{{ if $sideline }}
17-
{{ $class = printf "%s %s" $class $sideOption }}
18-
{{ else }}
19-
{{ $class = printf "%s %s" $class $inlineOption }}
19+
{{ $dataGrid = "last-third" }}
2020
{{ end }}
2121

2222
{{/* Render a different block, if "loud" callouts are used */}}
@@ -33,7 +33,7 @@
3333
{{ $isSpecialTitle := in $specialTitles $type }}
3434
{{ if $isSpecialTitle }}
3535
{{/* Loud callouts */}}
36-
<blockquote class="{{ $class }}">
36+
<blockquote class="{{ $class }}" data-grid="{{ $dataGrid }}">
3737
<div>
3838
<div class="call-out-type">
3939
{{ partial "feather" (dict "context" . "icon" $icon) .}}
@@ -51,7 +51,7 @@
5151

5252
{{ $cleanTitle := strings.TrimSuffix ":" $title}}
5353

54-
<blockquote class="{{ $class }} note" data-title="{{ $cleanTitle }}">
54+
<blockquote class="{{ $class }} note" data-title="{{ $cleanTitle }}" data-grid="{{ $dataGrid }}">
5555
<div class="callout-content">
5656
{{- with $icon -}}
5757
<i class="{{ . }}"></i>

0 commit comments

Comments
 (0)