imfing · davlgd · Sep 13, 2025 · Sep 13, 2025
diff --git a/docs/content/api/_index.md b/docs/content/api/_index.md
@@ -0,0 +1,23 @@
+---
+type: openapi
+title: API documentation
+swagger:
+  url: https://raw.githubusercontent.com/OAI/learn.openapis.org/refs/heads/main/examples/v3.1/tictactoe.json
+
+  # Could be multiple URLs (need StandaloneLayout)
+  # layout: StandaloneLayout
+  # urls:
+  # - name: Tic Tac Toe
+  #   url: https://raw.githubusercontent.com/OAI/learn.openapis.org/refs/heads/main/examples/v3.1/tictactoe.json
+  # - name: Webhook
+  #   url: https://raw.githubusercontent.com/OAI/learn.openapis.org/refs/heads/main/examples/v3.1/webhook-example.json
+  filter: true
+  operationsSorter: alpha
+  tagsSorter: alpha
+  # tryItOutEnabled: false
+  # supportedSubmitMethods:
+  #   - get
+  # More parameters: https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/
+  #
+  # cssUrl: https://cdn.jsdelivr.net/npm/[email protected]/themes/3.x/theme-muted.css
+---
diff --git a/docs/hugo.yaml b/docs/hugo.yaml
@@ -85,27 +85,31 @@ menu:
     - identifier: versions
       name: Versions
       weight: 2
+    - identifier: api
+      name: API
+      pageRef: /api
+      weight: 3
     - identifier: blog
       name: Blog
       pageRef: /blog
-      weight: 3
+      weight: 4
     - identifier: about
       name: About
       pageRef: /about
-      weight: 4
+      weight: 5
     - identifier: showcase
       name: Showcase
       pageRef: /showcase
-      weight: 5
+      weight: 6
       params:
         type: link
         icon: collection
     - name: Search
-      weight: 6
+      weight: 7
       params:
         type: search
     - name: GitHub
-      weight: 7
+      weight: 8
       url: "https://github.com/imfing/hextra"
       params:
         icon: github

diff --git a/layouts/_partials/head-openapi.html b/layouts/_partials/head-openapi.html
@@ -0,0 +1,77 @@
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  {{- $noindex := .Params.noindex | default false -}}
+  {{ if and (hugo.IsProduction) (not $noindex) -}}
+    <meta name="robots" content="index, follow" />
+  {{ else -}}
+    <meta name="robots" content="noindex, nofollow" />
+  {{ end -}}
+  {{ partialCached "favicons.html" . -}}
+  <title>
+    {{- if .IsHome -}}
+      {{ .Site.Title -}}
+    {{ else -}}
+      {{ with .Title }}{{ . }} – {{ end -}}
+      {{ .Site.Title -}}
+    {{ end -}}
+  </title>
+  <meta name="description" content="{{ partial "utils/page-description.html" . }}" />
+
+  {{- with .Params.canonical -}}
+    <link rel="canonical" href="{{ . }}" itemprop="url" />
+  {{- else -}}
+    <link rel="canonical" href="{{ .Permalink }}" itemprop="url" />
+  {{- end -}}
+
+  {{- partial "opengraph.html" . -}}
+  {{- partial "schema.html" . -}}
+  {{- partial "twitter_cards.html" . -}}
+
+  {{- $mainCss := resources.Get "css/compiled/main.css" -}}
+  {{- $customCss := resources.Get "css/custom.css" -}}
+  {{- $variablesCss := resources.Get "css/variables.css" | resources.ExecuteAsTemplate "css/variables.css" . -}}
+
+  {{- /* Production build */ -}}
+  {{- if hugo.IsProduction }}
+    {{- $styles := slice $variablesCss $mainCss $customCss | resources.Concat "css/compiled/main.css" | minify | fingerprint }}
+    <link rel="preload" href="{{ $styles.RelPermalink }}" as="style" integrity="{{ $styles.Data.Integrity }}" />
+    <link href="{{ $styles.RelPermalink }}" rel="stylesheet" integrity="{{ $styles.Data.Integrity }}" />
+
+  {{- /* Theme development mode (non-production + theme environment) */ -}}
+  {{- else if eq hugo.Environment "theme" }}
+    {{- $devStyles := resources.Get "css/styles.css" | postCSS (dict "inlineImports" true) }}
+    <link href="{{ $devStyles.RelPermalink }}" rel="stylesheet" />
+    <link href="{{ $variablesCss.RelPermalink }}" rel="stylesheet" />
+    <link href="{{ $customCss.RelPermalink }}" rel="stylesheet" />
+
+  {{- /* User local development */ -}}
+  {{- else }}
+    {{- $styles := resources.Get "css/compiled/main.css" -}}
+    <link href="{{ $styles.RelPermalink }}" rel="stylesheet" />
+    <link href="{{ $variablesCss.RelPermalink }}" rel="stylesheet" />
+    <link href="{{ $customCss.RelPermalink }}" rel="stylesheet" />
+  {{- end }}
+
+  <!-- Swagger UI CSS -->
+  <link rel="stylesheet" href="https://unpkg.com/[email protected]/swagger-ui.css" />
+  <!-- Custom Swagger UI CSS (if defined) -->
+  {{ $cssUrl := .Params.swagger.cssUrl }}
+  {{ if $cssUrl }}
+    <link rel="stylesheet" href="{{ $cssUrl }}" />
+  {{ end }}
+
+  {{ partial "components/analytics/analytics.html" . }}
+
+  <!-- Math engine -->
+  {{ $noop := .WordCount -}}
+  {{- $engine := site.Params.math.engine | default "katex" -}}
+  {{ if and (.Page.Store.Get "hasMath") (eq $engine "katex") -}}
+    {{ partialCached "scripts/katex.html" . -}}
+  {{ else if and (.Page.Store.Get "hasMath") (eq $engine "mathjax") -}}
+    {{ partialCached "scripts/mathjax.html" . -}}
+  {{ end -}}
+
+  {{ partial "utils/page-width-override.html" . }}
+  {{ partial "custom/head-end.html" . -}}
+</head>
diff --git a/layouts/openapi/baseof.html b/layouts/openapi/baseof.html
@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html lang="{{ .Site.Language.Lang }}" dir="{{ .Site.Language.LanguageDirection | default `ltr` }}">
+  {{- partial "head-openapi.html" . -}}
+  <body>
+    {{- partial "banner.html" . -}}
+    {{- partial "navbar.html" . -}}
+    {{- block "main" . }}{{ end -}}
+    {{- if or (eq .Site.Params.footer.enable nil) (.Site.Params.footer.enable) }}
+      {{ partial "footer.html" . }}
+    {{ end }}
+    {{ partial "scripts.html" . }}
+  </body>
+</html>
diff --git a/layouts/openapi/openapi.html b/layouts/openapi/openapi.html
@@ -0,0 +1,37 @@
+{{ define "main" }}
+<div class='hx:mx-auto hextra-max-page-width'>
+  <div id="swagger-ui"></div>
+</div>
+
+<!-- Swagger UI JavaScript -->
+<script src="https://unpkg.com/[email protected]/swagger-ui-bundle.js" crossorigin></script>
+<script src="https://unpkg.com/[email protected]/swagger-ui-standalone-preset.js" crossorigin></script>
+<script>
+    window.onload = () => {
+      const config = {
+        dom_id: '#swagger-ui'
+      };
+      {{ if .Params.swagger.presets }}config.presets = {{ .Params.swagger.presets | jsonify | safeJS }};{{ else }}config.presets = [SwaggerUIBundle.presets.apis, SwaggerUIStandalonePreset];{{ end }}
+      {{ if .Params.swagger.layout }}config.layout = {{ .Params.swagger.layout | jsonify | safeJS }};{{ end }}
+      {{ if .Params.swagger.url }}config.url = {{ .Params.swagger.url | jsonify | safeJS }};{{ end }}
+      {{ if .Params.swagger.urls }}config.urls = {{ .Params.swagger.urls | jsonify | safeJS }};{{ end }}
+      {{ if .Params.swagger.operationsSorter }}config.operationsSorter = {{ .Params.swagger.operationsSorter | jsonify | safeJS }};{{ end }}
+      {{ if .Params.swagger.tagsSorter }}config.tagsSorter = {{ .Params.swagger.tagsSorter | jsonify | safeJS }};{{ end }}
+      {{ if .Params.swagger.tryItOutEnabled }}config.tryItOutEnabled = {{ .Params.swagger.tryItOutEnabled }};{{ end }}
+      {{ if .Params.swagger.filter }}config.filter = {{ .Params.swagger.filter }};{{ end }}
+      {{ if .Params.swagger.supportedSubmitMethods }}config.supportedSubmitMethods = {{ .Params.swagger.supportedSubmitMethods | jsonify | safeJS }};{{ end }}
+      {{ if .Params.swagger.syntaxTheme }}config.syntaxHighlight = { theme: {{ .Params.swagger.syntaxTheme | jsonify | safeJS }} };{{ end }}
+      {{ if .Params.swagger.deepLinking }}config.deepLinking = {{ .Params.swagger.deepLinking }};{{ end }}
+      {{ if .Params.swagger.displayOperationId }}config.displayOperationId = {{ .Params.swagger.displayOperationId }};{{ end }}
+      {{ if .Params.swagger.displayRequestDuration }}config.displayRequestDuration = {{ .Params.swagger.displayRequestDuration }};{{ end }}
+      {{ if .Params.swagger.docExpansion }}config.docExpansion = {{ .Params.swagger.docExpansion | jsonify | safeJS }};{{ end }}
+      {{ if .Params.swagger.maxDisplayedTags }}config.maxDisplayedTags = {{ .Params.swagger.maxDisplayedTags }};{{ end }}
+      {{ if .Params.swagger.showExtensions }}config.showExtensions = {{ .Params.swagger.showExtensions }};{{ end }}
+      {{ if .Params.swagger.showCommonExtensions }}config.showCommonExtensions = {{ .Params.swagger.showCommonExtensions }};{{ end }}
+      {{ if .Params.swagger.defaultModelRendering }}config.defaultModelRendering = {{ .Params.swagger.defaultModelRendering | jsonify | safeJS }};{{ end }}
+      {{ if .Params.swagger.url }}config.url = {{ .Params.swagger.url | jsonify | safeJS }};{{ end }}
+
+      window.ui = SwaggerUIBundle(config);
+  };
+</script>
+{{ end }}