From 9e959f3922f1b3594602a9832660ef70b6171e3a Mon Sep 17 00:00:00 2001 From: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> Date: Thu, 18 Dec 2025 14:59:18 +0000 Subject: [PATCH] Add a list of endpoints to the top of each spec (#2262) Fixes #784 Add a collapsible list of endpoints to the top of the page for each distinct spec. We do this by storing endpoint metadata on $page and creating a new partial, endpoints-toc.html, which renders it. --- assets/scss/_styles_project.scss | 65 +++++++++++++- .../internal/newsfragments/2262.clarification | 1 + content/application-service-api.md | 14 ++- content/client-server-api/_index.md | 90 +++++++++---------- content/identity-service-api.md | 16 ++-- content/push-gateway-api.md | 7 +- content/server-server-api.md | 79 ++++++++-------- layouts/_partials/endpoints-toc.html | 61 +++++++++++++ layouts/_partials/openapi/render-api.html | 12 ++- .../_partials/openapi/render-operation.html | 25 ++++++ layouts/_partials/spec-content.html | 14 +++ layouts/_shortcodes/cs-module.html | 29 +++++- layouts/_shortcodes/http-api.html | 16 +++- layouts/content.html | 4 - layouts/docs/list.html | 18 ++-- layouts/docs/single.html | 19 ++++ 16 files changed, 345 insertions(+), 125 deletions(-) create mode 100644 changelogs/internal/newsfragments/2262.clarification create mode 100644 layouts/_partials/endpoints-toc.html create mode 100644 layouts/_partials/spec-content.html delete mode 100644 layouts/content.html create mode 100644 layouts/docs/single.html diff --git a/assets/scss/_styles_project.scss b/assets/scss/_styles_project.scss index 0131f1f1..f20dc096 100644 --- a/assets/scss/_styles_project.scss +++ b/assets/scss/_styles_project.scss @@ -257,6 +257,69 @@ Custom SCSS for the Matrix spec } +.endpoints-toc { + summary { + cursor: pointer; + font-weight: $font-weight-bold; + font-size: 1.05rem; + margin-bottom: 0.5rem; + } + + .endpoint-list { + list-style: none; + padding-left: 0; + margin: 0; + } + + .endpoint-list li { + margin: 0.2rem 0; + } + + .endpoint-list a { + text-decoration: none; + color: inherit; + padding: 0.05rem 0.25rem; + border-radius: 0.2rem; + + &:hover { + background-color: $secondary-background; + } + } + + .endpoint-list .http-api-method { + margin-right: 0.35rem; + font-weight: $font-weight-bold; + } + + .endpoint-path { + font-family: $font-family-monospace; + color: $secondary; + } + + .endpoint-deprecated { + color: $danger; + font-weight: $font-weight-bold; + margin-left: 0.35rem; + } + + .endpoint-module { + &:not(:first-child) { + margin-top: 0.75rem; + } + } + + .endpoint-module-title { + // font-weight: $font-weight-bold; + font-size: 1.20rem; + margin-bottom: 0.35rem; + } +} + +.page-description { + margin-bottom: 1rem; + color: inherit; +} + /* Styles for alert boxes */ .alert { &.note { @@ -581,4 +644,4 @@ dd { .breadcrumb { margin: 0; } -} \ No newline at end of file +} diff --git a/changelogs/internal/newsfragments/2262.clarification b/changelogs/internal/newsfragments/2262.clarification new file mode 100644 index 00000000..117c2bec --- /dev/null +++ b/changelogs/internal/newsfragments/2262.clarification @@ -0,0 +1 @@ +Add a list of endpoints to the top of each spec page. \ No newline at end of file diff --git a/content/application-service-api.md b/content/application-service-api.md index 5f6b17ab..d1b9c638 100644 --- a/content/application-service-api.md +++ b/content/application-service-api.md @@ -2,16 +2,14 @@ title: "Application Service API" weight: 30 type: docs +description: | + The Matrix client-server API and server-server APIs provide a consistent, + self-contained federated messaging fabric but leave little room for custom + server-side behaviour such as gateways, filters, or extensible hooks. The + Application Service API defines a standard way to add this extensible + functionality, independent of the underlying homeserver implementation. --- -The Matrix client-server API and server-server APIs provide the means to -implement a consistent self-contained federated messaging fabric. -However, they provide limited means of implementing custom server-side -behaviour in Matrix (e.g. gateways, filters, extensible hooks etc). The -Application Service API (AS API) defines a standard API to allow such -extensible functionality to be implemented irrespective of the -underlying homeserver implementation. - ## Application Services Application services are passive and can only observe events from the diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 4c76d6a5..8f8092b5 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -2,14 +2,14 @@ title: "Client-Server API" weight: 10 type: docs +description: | + The client-server API allows clients to send messages, control rooms and + synchronise conversation history. It is designed to support both lightweight + clients which store no state and lazy-load data from the server as required, + as well as heavyweight clients which maintain a full local persistent copy of + server state. --- -The client-server API allows clients to -send messages, control rooms and synchronise conversation history. It is -designed to support both lightweight clients which store no state and -lazy-load data from the server as required - as well as heavyweight -clients which maintain a full local persistent copy of server state. - ## API Standards {{% boxes/note %}} @@ -3962,42 +3962,42 @@ operations and run in a resource constrained environment. Like embedded applications, they are not intended to be fully-fledged communication systems. -{{% cs-module name="instant_messaging" %}} -{{% cs-module name="rich_replies" %}} -{{% cs-module name="voip_events" %}} -{{% cs-module name="typing_notifications" %}} -{{% cs-module name="receipts" %}} -{{% cs-module name="read_markers" %}} -{{% cs-module name="presence" %}} -{{% cs-module name="content_repo" %}} -{{% cs-module name="send_to_device" %}} -{{% cs-module name="device_management" %}} -{{% cs-module name="end_to_end_encryption" %}} -{{% cs-module name="secrets" %}} -{{% cs-module name="history_visibility" %}} -{{% cs-module name="push" %}} -{{% cs-module name="third_party_invites" %}} -{{% cs-module name="search" %}} -{{% cs-module name="guest_access" %}} -{{% cs-module name="room_previews" %}} -{{% cs-module name="tags" %}} -{{% cs-module name="account_data" %}} -{{% cs-module name="admin" %}} -{{% cs-module name="event_context" %}} -{{% cs-module name="sso_login" %}} -{{% cs-module name="dm" %}} -{{% cs-module name="ignore_users" %}} -{{% cs-module name="stickers" %}} -{{% cs-module name="report_content" %}} -{{% cs-module name="third_party_networks" %}} -{{% cs-module name="openid" %}} -{{% cs-module name="server_acls" %}} -{{% cs-module name="mentions" %}} -{{% cs-module name="room_upgrades" %}} -{{% cs-module name="server_notices" %}} -{{% cs-module name="moderation_policies" %}} -{{% cs-module name="spaces" %}} -{{% cs-module name="event_replacements" %}} -{{% cs-module name="event_annotations" %}} -{{% cs-module name="threading" %}} -{{% cs-module name="reference_relations" %}} +{{% cs-module name="Instant Messaging" filename="instant_messaging" %}} +{{% cs-module name="Rich replies" filename="rich_replies" %}} +{{% cs-module name="Voice over IP" filename="voip_events" %}} +{{% cs-module name="Typing Notifications" filename="typing_notifications" %}} +{{% cs-module name="Receipts" filename="receipts" %}} +{{% cs-module name="Read and unread markers" filename="read_markers" %}} +{{% cs-module name="Presence" filename="presence" %}} +{{% cs-module name="Content repository" filename="content_repo" %}} +{{% cs-module name="Send-to-Device messaging" filename="send_to_device" %}} +{{% cs-module name="Device Management" filename="device_management" %}} +{{% cs-module name="End-to-End Encryption" filename="end_to_end_encryption" %}} +{{% cs-module name="Secrets" filename="secrets" %}} +{{% cs-module name="Room History Visibility" filename="history_visibility" %}} +{{% cs-module name="Push Notifications" filename="push" %}} +{{% cs-module name="Third-party invites" filename="third_party_invites" %}} +{{% cs-module name="Server Side Search" filename="search" %}} +{{% cs-module name="Guest Access" filename="guest_access" %}} +{{% cs-module name="Room Previews" filename="room_previews" %}} +{{% cs-module name="Room Tagging" filename="tags" %}} +{{% cs-module name="Client Config" filename="account_data" %}} +{{% cs-module name="Server Administration" filename="admin" %}} +{{% cs-module name="Event Context" filename="event_context" %}} +{{% cs-module name="SSO client login/authentication" filename="sso_login" %}} +{{% cs-module name="Direct Messaging" filename="dm" %}} +{{% cs-module name="Ignoring Users" filename="ignore_users" %}} +{{% cs-module name="Sticker Messages" filename="stickers" %}} +{{% cs-module name="Reporting Content" filename="report_content" %}} +{{% cs-module name="Third-party Networks" filename="third_party_networks" %}} +{{% cs-module name="OpenID" filename="openid" %}} +{{% cs-module name="Server Access Control Lists (ACLs) for rooms" filename="server_acls" %}} +{{% cs-module name="User and room mentions" filename="mentions" %}} +{{% cs-module name="Room Upgrades" filename="room_upgrades" %}} +{{% cs-module name="Server Notices" filename="server_notices" %}} +{{% cs-module name="Moderation policy lists" filename="moderation_policies" %}} +{{% cs-module name="Spaces" filename="spaces" %}} +{{% cs-module name="Event replacements" filename="event_replacements" %}} +{{% cs-module name="Event annotations and reactions" filename="event_annotations" %}} +{{% cs-module name="Threading" filename="threading" %}} +{{% cs-module name="Reference relations" filename="reference_relations" %}} diff --git a/content/identity-service-api.md b/content/identity-service-api.md index 3c20a12a..8946ad34 100644 --- a/content/identity-service-api.md +++ b/content/identity-service-api.md @@ -2,17 +2,15 @@ title: "Identity Service API" weight: 40 type: docs +description: | + The Matrix client-server and server-server APIs are largely expressed in + Matrix user identifiers. Sometimes it is useful to refer to users by other + (“third-party”) identifiers such as email addresses or phone numbers. The + Identity Service API describes how mappings between 3PIDs and Matrix user + IDs can be established, validated, and used; in practice this has been + applied to email addresses and phone numbers. --- -The Matrix client-server and server-server APIs are largely expressed in -Matrix user identifiers. From time to time, it is useful to refer to -users by other ("third-party") identifiers, or "3PID"s, e.g. their email -address or phone number. This Identity Service Specification describes -how mappings between third-party identifiers and Matrix user identifiers -can be established, validated, and used. This description technically -may apply to any 3PID, but in practice has only been applied -specifically to email addresses and phone numbers. - ## General principles The purpose of an identity server is to validate, store, and answer diff --git a/content/push-gateway-api.md b/content/push-gateway-api.md index 161cf24f..f74decd9 100644 --- a/content/push-gateway-api.md +++ b/content/push-gateway-api.md @@ -2,12 +2,11 @@ title: "Push Gateway API" weight: 50 type: docs +description: | + Clients may want to receive push notifications when events are received at the + homeserver. This is managed by a distinct entity called the Push Gateway. --- -Clients may want to receive push notifications when events are received -at the homeserver. This is managed by a distinct entity called the Push -Gateway. - ## Overview A client's homeserver forwards information about received events to the diff --git a/content/server-server-api.md b/content/server-server-api.md index ca1cdd2e..1ab7e3ba 100644 --- a/content/server-server-api.md +++ b/content/server-server-api.md @@ -2,49 +2,46 @@ title: "Server-Server API" weight: 20 type: docs +description: | + Matrix homeservers use the Federation APIs (also known as server-server APIs) + to communicate with each other. Homeservers use these APIs to push messages in + real-time, retrieve historic messages, and query profile or presence + information about users on other servers. The APIs are implemented over HTTPS, + with authentication provided by public key signatures both at the TLS + transport layer and in HTTP Authorization headers. + + There are three main kinds of communication that occur between + homeservers: + + Persistent Data Units (PDUs): + These events are broadcast from one homeserver to any others that have + joined the same room (identified by Room ID). They are persisted in + long-term storage and record the history of messages and state for a + room. + + Like email, it is the responsibility of the originating server of a PDU + to deliver that event to its recipient servers. However PDUs are signed + using the originating server's private key so that it is possible to + deliver them through third-party servers. + + Ephemeral Data Units (EDUs): + These events are pushed between pairs of homeservers. They are not + persisted and are not part of the history of a room, nor does the + receiving homeserver have to reply to them. + + Queries: + These are single request/response interactions between a given pair of + servers, initiated by one side sending an HTTPS GET request to obtain + some information, and responded by the other. They are not persisted and + contain no long-term significant history. They simply request a snapshot + state at the instant the query is made. + + EDUs and PDUs are further wrapped in an envelope called a Transaction, + which is transferred from the origin to the destination homeserver using + an HTTPS PUT request. + --- -Matrix homeservers use the Federation APIs (also known as server-server -APIs) to communicate with each other. Homeservers use these APIs to push -messages to each other in real-time, to retrieve historic messages from -each other, and to query profile and presence information about users on -each other's servers. - -The APIs are implemented using HTTPS requests between each of the -servers. These HTTPS requests are strongly authenticated using public -key signatures at the TLS transport layer and using public key -signatures in HTTP Authorization headers at the HTTP layer. - -There are three main kinds of communication that occur between -homeservers: - -Persistent Data Units (PDUs): -These events are broadcast from one homeserver to any others that have -joined the same room (identified by Room ID). They are persisted in -long-term storage and record the history of messages and state for a -room. - -Like email, it is the responsibility of the originating server of a PDU -to deliver that event to its recipient servers. However PDUs are signed -using the originating server's private key so that it is possible to -deliver them through third-party servers. - -Ephemeral Data Units (EDUs): -These events are pushed between pairs of homeservers. They are not -persisted and are not part of the history of a room, nor does the -receiving homeserver have to reply to them. - -Queries: -These are single request/response interactions between a given pair of -servers, initiated by one side sending an HTTPS GET request to obtain -some information, and responded by the other. They are not persisted and -contain no long-term significant history. They simply request a snapshot -state at the instant the query is made. - -EDUs and PDUs are further wrapped in an envelope called a Transaction, -which is transferred from the origin to the destination homeserver using -an HTTPS PUT request. - ## API standards The mandatory baseline for server-server communication in Matrix is diff --git a/layouts/_partials/endpoints-toc.html b/layouts/_partials/endpoints-toc.html new file mode 100644 index 00000000..f5a652ef --- /dev/null +++ b/layouts/_partials/endpoints-toc.html @@ -0,0 +1,61 @@ +{{/* + + Renders a list of API endpoints for the current page, given: + + The outer page's Scratch must contain an "api_endpoints" key, which is either + a slice of maps (a list of endpoint metadata dicts) or a map of module name -> + slice of endpoint metadata dicts (representing the API modules and the + endpoints they each contain). Each endpoint dict must contain the following + keys: + + * `anchor`: the HTML anchor for the endpoint + * `method`: the HTTP method + * `endpoint`: the endpoint path + * `summary`: a short summary of the endpoint + * `deprecated`: whether the endpoint is deprecated + * `module`: the CS API module name, if any, for grouping purposes. If empty, + the endpoint is considered "base" or "required". + +*/}} + +{{ $raw := .Scratch.Get "api_endpoints" }} +{{/* Normalize to a slice */}} +{{ $endpoints := slice }} +{{ if reflect.IsSlice $raw }} + {{ $endpoints = $raw }} +{{ else if reflect.IsMap $raw }} + {{ range $raw }} + {{ $endpoints = append $endpoints . }} + {{ end }} +{{ end }} +{{ if gt (len $endpoints) 0 }} +
+
+ List of Endpoints + {{/* Sort by module to group visually */}} + {{ $sorted := sort $endpoints "module" }} + {{ $current := "" }} + {{ range $sorted }} + {{ $mod := .module }} + {{/* Set a title for the base endpoints */}} + {{ if not $mod }}{{ $mod = "Required" }}{{ end }} + {{ if ne $mod $current }} + {{ if $current }}
{{ end }} +
+
{{ $mod }}
+
{{ end }} + + +{{ end }} diff --git a/layouts/_partials/openapi/render-api.html b/layouts/_partials/openapi/render-api.html index 608cfa33..92d2bdd8 100644 --- a/layouts/_partials/openapi/render-api.html +++ b/layouts/_partials/openapi/render-api.html @@ -7,6 +7,8 @@ of each value in `paths` to get a complete URL. * `anchor_base`: an optional prefix for the HTML IDs generated by this template. + * `page`: the (Hugo) Page object to store endpoint metadata in the Scratch of. Used to build the endpoints TOC. + * `module`: the current CS API module name, if any. Used to group endpoints in the TOC. This template replaces the old {{*_http_api}} template. @@ -15,6 +17,8 @@ {{ $api_data := index .api_data }} {{ $base_url := .base_url }} {{ $anchor_base := .anchor_base }} +{{ $page := .page }} +{{ $module := .module }} {{ range $path_name, $path_data := $api_data.paths }} @@ -26,28 +30,28 @@ {{ with $path_data.get }} - {{ $operation_params := merge $params (dict "method" "GET" "operation_data" . "anchor_base" $anchor_base) }} + {{ $operation_params := merge $params (dict "method" "GET" "operation_data" . "anchor_base" $anchor_base "page" $page "module" $module) }} {{ partial "openapi/render-operation" $operation_params }} {{ end }} {{ with $path_data.post }} - {{ $operation_params := merge $params (dict "method" "POST" "operation_data" . "anchor_base" $anchor_base) }} + {{ $operation_params := merge $params (dict "method" "POST" "operation_data" . "anchor_base" $anchor_base "page" $page "module" $module) }} {{ partial "openapi/render-operation" $operation_params }} {{ end }} {{ with $path_data.put }} - {{ $operation_params := merge $params (dict "method" "PUT" "operation_data" . "anchor_base" $anchor_base) }} + {{ $operation_params := merge $params (dict "method" "PUT" "operation_data" . "anchor_base" $anchor_base "page" $page "module" $module) }} {{ partial "openapi/render-operation" $operation_params }} {{ end }} {{ with $path_data.delete }} - {{ $operation_params := merge $params (dict "method" "DELETE" "operation_data" . "anchor_base" $anchor_base) }} + {{ $operation_params := merge $params (dict "method" "DELETE" "operation_data" . "anchor_base" $anchor_base "page" $page "module" $module) }} {{ partial "openapi/render-operation" $operation_params }} {{ end }} diff --git a/layouts/_partials/openapi/render-operation.html b/layouts/_partials/openapi/render-operation.html index c1e34ddf..d90a1d7e 100644 --- a/layouts/_partials/openapi/render-operation.html +++ b/layouts/_partials/openapi/render-operation.html @@ -7,6 +7,8 @@ * `operation_data`: the OpenAPI data for the operation * `anchor_base`: an optional prefix for the HTML IDs generated by this template. + * `page`: the (Hugo) Page object to store endpoint metadata in the Scratch of. Used to build the endpoints TOC. + * `module`: the current CS API module name, if any. Used to group endpoints in the TOC. This template renders the operation as a `
` containing: @@ -22,6 +24,8 @@ {{ $method := .method }} {{ $endpoint := .endpoint }} {{ $operation_data := .operation_data }} +{{ $page := .page }} +{{ $module := .module }} {{ $anchor := "" }} {{ if .anchor_base }} @@ -29,6 +33,27 @@ {{ end }} {{ $anchor = printf "%s%s%s" $anchor (lower $method) (anchorize $endpoint) }} +{{/* Collect endpoints for the on-page endpoints TOC */}} +{{ if $page }} + {{/* Store each endpoint's metadata in a scratch variable */}} + {{ $entry := dict "anchor" $anchor "method" $method "endpoint" $endpoint "summary" $operation_data.summary "deprecated" $operation_data.deprecated "module" $module }} + {{ if not ($page.Scratch.Get "api_endpoints_seen") }} + {{ $page.Scratch.Set "api_endpoints_seen" dict }} + {{ end }} + {{/* Keep a map of seen endpoints. This is necessary as this partial may be + rendered multiple times for the same endpoint (e.g. in the TOC and + in the main content), leading to duplicates. */}} + {{ $seen := $page.Scratch.Get "api_endpoints_seen" }} + {{ $key := printf "%s|%s" $method $endpoint }} + {{ if not (index $seen $key) }} + {{ if not (reflect.IsSlice ($page.Scratch.Get "api_endpoints")) }} + {{ $page.Scratch.Set "api_endpoints" (slice) }} + {{ end }} + {{ $page.Scratch.Add "api_endpoints" (slice $entry) }} + {{ $page.Scratch.SetInMap "api_endpoints_seen" $key true }} + {{ end }} +{{ end }} +
diff --git a/layouts/_partials/spec-content.html b/layouts/_partials/spec-content.html new file mode 100644 index 00000000..23e5a807 --- /dev/null +++ b/layouts/_partials/spec-content.html @@ -0,0 +1,14 @@ +{{- /* Shared render for spec pages: title, optional description, endpoints list, body, and last-mod info. */ -}} +
+

{{ .Title }}

+ {{ with .Params.description }}

{{ . | markdownify }}

{{ end }} + + {{/* + Render an endpoints table of contents. This is the main difference + between our templates (which call the spec-content partial) and the default + Docsy template. + */}} + {{ partial "endpoints-toc.html" . }} + + {{ .Content }} +
\ No newline at end of file diff --git a/layouts/_shortcodes/cs-module.html b/layouts/_shortcodes/cs-module.html index 52c9a5d9..6385d914 100644 --- a/layouts/_shortcodes/cs-module.html +++ b/layouts/_shortcodes/cs-module.html @@ -3,14 +3,39 @@ This template is used to render a Client-Server API Module. Modules are defined alongside the `_index.md` for the CS API. - The `name` parameter is the file name without extension. + The following parameters are expected: + + * `filename` the name of the module file to render, without extension (i.e. `spaces`). + * `name` the display name of the module (i.e. `Spaces`). */}} {{ $name := .Params.name }} +{{ $filename := .Params.filename }} {{ with .Site.GetPage "client-server-api/modules" }} - {{ with .Resources.GetMatch (printf "%s%s" $name ".md") }} + {{ with .Resources.GetMatch (printf "%s%s" $filename ".md") }} + {{/* Preserve previous scratch values so nested modules don't leak */}} + {{ $prevPage := .Scratch.Get "endpoint_page" }} + {{ $prevModule := .Scratch.Get "endpoint_module" }} + + {{/* Allow endpoints rendered in the module to accumulate on the parent page */}} + {{ .Scratch.Set "endpoint_page" $.Page }} + {{/* Name the module for grouping in the endpoints list */}} + {{ .Scratch.Set "endpoint_module" $name }} + {{ .RenderShortcodes }} + + {{/* Restore previous scratch values */}} + {{ if $prevPage }} + {{ .Scratch.Set "endpoint_page" $prevPage }} + {{ else }} + {{ .Scratch.Delete "endpoint_page" }} + {{ end }} + {{ if $prevModule }} + {{ .Scratch.Set "endpoint_module" $prevModule }} + {{ else }} + {{ .Scratch.Delete "endpoint_module" }} + {{ end }} {{ end }} {{ end }} diff --git a/layouts/_shortcodes/http-api.html b/layouts/_shortcodes/http-api.html index b5201c49..a5268323 100644 --- a/layouts/_shortcodes/http-api.html +++ b/layouts/_shortcodes/http-api.html @@ -23,6 +23,20 @@ {{ $api := .Params.api}} {{ $anchor_base := .Params.anchor_base}} +{{/* + + Figure out which Page object to pass to the `openapi/render-api` partial. + Either our own, or one stored under `endpoint_page` in the Scratch, if one + exists. + +*/}} +{{ $target_page := .Page }} +{{ with .Page.Scratch.Get "endpoint_page" }} + {{ $target_page = . }} +{{ end }} + +{{ $module_name := .Page.Scratch.Get "endpoint_module" }} + {{ $api_data := index .Site.Data.api .Params.spec .Params.api }} {{ $base_url := (index $api_data.servers 0).variables.basePath.default }} {{ $path := delimit (slice "api" $spec $api) "/" }} @@ -30,4 +44,4 @@ {{ $api_data = partial "json-schema/resolve-refs" (dict "schema" $api_data "path" $path) }} {{ $api_data = partial "json-schema/resolve-allof" $api_data }} -{{ partial "openapi/render-api" (dict "api_data" $api_data "base_url" $base_url "anchor_base" $anchor_base) }} +{{ partial "openapi/render-api" (dict "api_data" $api_data "base_url" $base_url "anchor_base" $anchor_base "page" $target_page "module" $module_name) }} diff --git a/layouts/content.html b/layouts/content.html deleted file mode 100644 index e58073f3..00000000 --- a/layouts/content.html +++ /dev/null @@ -1,4 +0,0 @@ -
-

{{ .Title }}

- {{ .Content }} -
diff --git a/layouts/docs/list.html b/layouts/docs/list.html index 01145138..6bd0dcb5 100644 --- a/layouts/docs/list.html +++ b/layouts/docs/list.html @@ -1,13 +1,19 @@ {{/* - A simplified version of the list.html partial in Docsy. + Override the `layouts/docs/list.html` template from Docsy. While this template + is equivalent to `single.html`, it's necessary to override both templates to + avoid falling back to the default Docsy templates. + + https://gohugo.io/templates/types/#list + + We use this list template to render the Client-Server API spec page and each + of its modules. + + The contents of the "main" block below are inserted into the `./baseof.html` + base template. */}} {{ define "main" }} -
-

{{ .Title }}

- {{ with .Params.description }}
{{ . | markdownify }}
{{ end }} - {{ .Content }} -
+ {{ partial "spec-content.html" . }} {{ end }} diff --git a/layouts/docs/single.html b/layouts/docs/single.html new file mode 100644 index 00000000..67b0dae0 --- /dev/null +++ b/layouts/docs/single.html @@ -0,0 +1,19 @@ +{{/* + + Override the `layouts/docs/single.html` template from Docsy. While this template + is equivalent to `list.html`, it's necessary to override both templates to + avoid falling back to the default Docsy templates. + + https://gohugo.io/templates/types/#single + + We use this single template to render the all API spec pages *except* the + Client-Server API. The Client-Server API spec page contains modules, and thus + is handled separately, via the `layouts/docs/list.html` template. + + The contents of the "main" block below are inserted into the `./baseof.html` + base template. + +*/}} +{{ define "main" }} + {{ partial "spec-content.html" . }} +{{ end }}