Skip to content

Commit 6d85fc3

Browse files
jstirnamanjstirnaman
committed
feat(api): Add section index and All endpoints nav item
- Add api/section-children.html partial for API section index pages - Update api/list.html to detect section index vs tag pages - Add "All endpoints" nav item listing all operations sorted by method+path - Remove {{< children >}} shortcode from API index pages (use data-driven list)
1 parent 706d4f6 commit 6d85fc3

File tree

4 files changed

+166
-57
lines changed

4 files changed

+166
-57
lines changed

‎assets/styles/layouts/_sidebar.scss‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -263,6 +263,14 @@
263263
align-items: center;
264264
gap: 0.4rem;
265265
}
266+
267+
// Path-based operation display (All endpoints list)
268+
&--path .api-path {
269+
font-family: $proxima;
270+
font-size: 0.55rem;
271+
color: inherit;
272+
word-break: break-all;
273+
}
266274
}
267275

268276
.api-method {

‎layouts/api/list.html‎

Lines changed: 19 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -1,70 +1,38 @@
11
{{/*
2-
API Documentation Tag/List Layout
2+
API Documentation Layout
33

4-
Displays tag-based API documentation pages with:
5-
1. Title
6-
2. Summary (brief description)
7-
3. Operations list (links to nested operation pages)
8-
4. Description (detailed content)
4+
Handles two cases:
5+
1. Section index (no 'tag' param) - shows list of tag pages from article data
6+
2. Tag pages (has 'tag' param) - shows operations list and description
97

108
For conceptual pages (isConceptual: true), shows content without operations list.
11-
12-
Required frontmatter:
13-
- title: Page title
14-
- description or summary: Brief description
15-
- operations: Array of operation objects (for non-conceptual pages)
169
*/}}
1710

1811
{{ partial "header.html" . }}
1912
{{ partial "topnav.html" . }}
2013

2114
<div class="page-wrapper">
22-
{{/* Left: Existing Hugo sidebar (includes API nav via sidebar.html) */}}
2315
{{ partial "sidebar.html" . }}
2416

25-
{{/* Center + Right: Content and TOC */}}
2617
<div class="content-wrapper api-content">
2718
<div class="api-main">
2819
<article class="article article--content api-reference" role="main">
2920
<header class="article--header">
30-
<div class="article--header-row">
31-
<div class="article--header-text">
32-
<h1 class="article--title">{{ .Title }}</h1>
33-
34-
{{/* Summary - first sentence only at top */}}
35-
{{ with .Params.summary }}
36-
<p class="article--summary">{{ . | markdownify }}</p>
37-
{{ else }}
38-
{{/* Extract first sentence from description (or full text if no sentence ending) */}}
39-
{{ with .Description }}
40-
{{ $matches := findRE `^[^.!?]*[.!?]` . 1 }}
41-
{{ if gt (len $matches) 0 }}
42-
{{ $firstSentence := index $matches 0 }}
43-
<p class="article--summary">{{ $firstSentence | markdownify }}</p>
44-
{{ else }}
45-
{{/* No sentence ending found - use first line or full description */}}
46-
{{ $firstLine := index (split . "\n") 0 }}
47-
<p class="article--summary">{{ $firstLine | markdownify }}</p>
48-
{{ end }}
49-
{{ end }}
50-
{{ end }}
51-
</div>
52-
53-
{{/* Download OpenAPI spec button */}}
54-
{{ with .Params.staticFilePath }}
55-
<div class="api-spec-actions">
56-
<a href="{{ . }}" class="btn api-spec-download" download>
57-
<svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor" aria-hidden="true">
58-
<path d="M8 12L3 7h3V2h4v5h3L8 12z"/>
59-
<path d="M1 14h14v2H1v-2z"/>
60-
</svg>
61-
Download OpenAPI Spec
62-
</a>
63-
</div>
64-
{{ end }}
65-
</div>
21+
<h1 class="article--title">{{ .Title }}</h1>
22+
{{ with .Description }}
23+
<p class="article--description">{{ . }}</p>
24+
{{ end }}
6625
</header>
6726

27+
{{/* Check if this is a section index (no tag param) or a tag page */}}
28+
{{ $hasTag := isset .Params "tag" }}
29+
30+
{{ if not $hasTag }}
31+
{{/* SECTION INDEX - Show tag pages from article data */}}
32+
{{ partial "api/section-children.html" . }}
33+
34+
{{ else }}
35+
{{/* TAG PAGE - Show operations or conceptual content */}}
6836
{{ $isConceptual := .Params.isConceptual | default false }}
6937

7038
{{ if $isConceptual }}
@@ -78,17 +46,15 @@ <h1 class="article--title">{{ .Title }}</h1>
7846
{{ end }}
7947
{{ end }}
8048
</section>
49+
8150
{{ else }}
8251
{{/* Operational Page - Show operations list then description */}}
83-
84-
{{/* Operations List */}}
8552
{{ $operations := .Params.operations }}
8653
{{ if $operations }}
8754
<section class="api-operations-list">
8855
<h2 id="endpoints">Endpoints</h2>
8956
<div class="api-operations-grid">
9057
{{ range $operations }}
91-
{{/* Build URL: parent section (e.g., /influxdb3/core/api/) + operation path + method */}}
9258
{{ $apiBase := $.Parent.RelPermalink }}
9359
{{ $operationURL := printf "%s%s/%s/" $apiBase .path (lower .method) }}
9460
<a href="{{ $operationURL }}" class="api-operation-card">
@@ -117,18 +83,14 @@ <h2 id="overview">Overview</h2>
11783
</section>
11884
{{ end }}
11985

120-
{{/* RapiDoc renderer - only for pages with additional content beyond description */}}
121-
{{/* Don't show RapiDoc on list pages since operations are already shown as cards above */}}
122-
86+
{{ end }}
12387
{{ end }}
12488

125-
{{/* Related documentation links */}}
12689
{{ partial "article/related.html" . }}
12790

12891
</article>
12992
</div>
13093

131-
{{/* Right: Page TOC - "ON THIS PAGE" */}}
13294
<aside class="api-toc" data-component="api-toc">
13395
<h4 class="api-toc-header">ON THIS PAGE</h4>
13496
<nav class="api-toc-nav"></nav>

‎layouts/partials/api/section-children.html‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
{{/*
2+
API Section Children
3+
4+
Renders tag pages from article data as a children list.
5+
Sort order: conceptual tags (traitTags) first, then other tags alphabetically.
6+
7+
Uses data from:
8+
- data/article_data/influxdb/{product}/articles.yml
9+
*/}}
10+
11+
{{ $currentPage := . }}
12+
13+
{{/* Extract product and version from URL */}}
14+
{{ $productPathData := findRE "[^/]+.*?" .RelPermalink }}
15+
{{ $product := index $productPathData 0 }}
16+
{{ $version := index $productPathData 1 }}
17+
18+
{{/* Build data key for article data lookup */}}
19+
{{ $dataKey := "" }}
20+
{{ if eq $product "influxdb3" }}
21+
{{ $dataKey = print "influxdb3_" $version }}
22+
{{ else if eq $product "influxdb" }}
23+
{{ $dataKey = print $version }}
24+
{{ else }}
25+
{{ $dataKey = $product }}
26+
{{ end }}
27+
28+
{{/* Get article data for this product */}}
29+
{{ $articles := slice }}
30+
{{ with site.Data.article_data }}
31+
{{ with index . "influxdb" }}
32+
{{ with index . $dataKey }}
33+
{{ with index . "articles" }}
34+
{{ with .articles }}
35+
{{ $articles = . }}
36+
{{ end }}
37+
{{ end }}
38+
{{ end }}
39+
{{ end }}
40+
{{ end }}
41+
42+
{{ if gt (len $articles) 0 }}
43+
{{/* Separate conceptual (traitTag) and non-conceptual articles */}}
44+
{{ $conceptualArticles := slice }}
45+
{{ $operationArticles := slice }}
46+
47+
{{ range $articles }}
48+
{{ if and (reflect.IsMap .) (isset . "fields") }}
49+
{{ $fields := index . "fields" }}
50+
{{ if reflect.IsMap $fields }}
51+
{{ $isConceptual := false }}
52+
{{ if isset $fields "isConceptual" }}
53+
{{ $isConceptual = index $fields "isConceptual" }}
54+
{{ end }}
55+
{{ if $isConceptual }}
56+
{{ $conceptualArticles = $conceptualArticles | append . }}
57+
{{ else }}
58+
{{ $operationArticles = $operationArticles | append . }}
59+
{{ end }}
60+
{{ end }}
61+
{{ end }}
62+
{{ end }}
63+
64+
{{/* Sort each group alphabetically by tag name */}}
65+
{{ $conceptualArticles = sort $conceptualArticles "fields.tag" }}
66+
{{ $operationArticles = sort $operationArticles "fields.tag" }}
67+
68+
{{/* Combine: conceptual first, then operations */}}
69+
{{ $sortedArticles := $conceptualArticles | append $operationArticles }}
70+
71+
<section class="api-children children">
72+
{{ range $sortedArticles }}
73+
{{ $path := index . "path" }}
74+
{{ $fields := index . "fields" }}
75+
{{ $tag := index $fields "tag" }}
76+
{{ $description := index $fields "description" | default "" }}
77+
{{ $tagPageUrl := print "/" $product "/" $version "/" $path "/" | relURL }}
78+
79+
<div class="child-item">
80+
<h3 id="{{ $tag | urlize }}"><a href="{{ $tagPageUrl }}">{{ $tag }}</a></h3>
81+
{{ with $description }}
82+
<p>{{ . }}</p>
83+
{{ end }}
84+
</div>
85+
{{ end }}
86+
</section>
87+
{{ end }}

‎layouts/partials/sidebar/api-menu-items.html‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -148,4 +148,56 @@
148148
{{ end }}
149149
</li>
150150
{{ end }}
151+
152+
{{/* ALL ENDPOINTS - Collect all operations and sort by method+path */}}
153+
{{ $allOperations := slice }}
154+
{{ range $operationArticles }}
155+
{{ $fields := index . "fields" }}
156+
{{ if isset $fields "operations" }}
157+
{{ range index $fields "operations" }}
158+
{{ $allOperations = $allOperations | append . }}
159+
{{ end }}
160+
{{ end }}
161+
{{ end }}
162+
163+
{{ if gt (len $allOperations) 0 }}
164+
{{/* Sort operations alphabetically by path, then method */}}
165+
{{ $sortedOps := slice }}
166+
{{ range $allOperations }}
167+
{{ $sortKey := printf "%s %s" .path (upper .method) }}
168+
{{ $sortedOps = $sortedOps | append (dict "sortKey" $sortKey "op" .) }}
169+
{{ end }}
170+
{{ $sortedOps = sort $sortedOps "sortKey" }}
171+
172+
{{/* Check if any operation is active */}}
173+
{{ $anyOpActive := false }}
174+
{{ range $sortedOps }}
175+
{{ $op := .op }}
176+
{{ $opPathSlug := $op.path | replaceRE "^/" "" }}
177+
{{ $opUrl := printf "/%s/%s/api/%s/%s/" $product $version $opPathSlug (lower $op.method) }}
178+
{{ if eq $currentPage.RelPermalink $opUrl }}
179+
{{ $anyOpActive = true }}
180+
{{ end }}
181+
{{ end }}
182+
183+
<li class="nav-item">
184+
<a href="#" class="children-toggle{{ if $anyOpActive }} open{{ end }}"></a>
185+
<span class="nav-group-label">All endpoints</span>
186+
<ul class="children{{ if $anyOpActive }} open{{ end }}">
187+
{{ range $sortedOps }}
188+
{{ $op := .op }}
189+
{{ $apiPath := $op.path }}
190+
{{ $opPathSlug := $apiPath | replaceRE "^/" "" }}
191+
{{ $operationUrl := printf "/%s/%s/api/%s/%s/" $product $version $opPathSlug (lower $op.method) | relURL }}
192+
{{ $opIsActive := eq $currentPage.RelPermalink (printf "/%s/%s/api/%s/%s/" $product $version $opPathSlug (lower $op.method)) }}
193+
<li class="nav-item api-operation api-operation--path{{ if $opIsActive }} active{{ end }}">
194+
<a href="{{ $operationUrl | safeURL }}">
195+
<span class="api-method api-method--{{ lower $op.method }}">{{ upper $op.method }}</span>
196+
<span class="api-path">{{ $apiPath }}</span>
197+
</a>
198+
</li>
199+
{{ end }}
200+
</ul>
201+
</li>
202+
{{ end }}
151203
{{ end }}

0 commit comments

Comments
 (0)