mirror of
https://github.com/matrix-org/matrix-spec
synced 2025-12-20 08:38:36 +01:00
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.
This commit is contained in:
Andrew Morgan
GitHub
parent
7c39427d8b
commit
9e959f3922
|
|
@ -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;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
|
|||
1
changelogs/internal/newsfragments/2262.clarification
Normal file
1
changelogs/internal/newsfragments/2262.clarification
Normal file
|
|
@ -0,0 +1 @@
|
|||
Add a list of endpoints to the top of each spec page.
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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" %}}
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
61
layouts/_partials/endpoints-toc.html
Normal file
61
layouts/_partials/endpoints-toc.html
Normal file
|
|
@ -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 }}
|
||||
<div class="endpoints-toc mb-4">
|
||||
<details>
|
||||
<summary>List of Endpoints</summary>
|
||||
{{/* 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 }}</ul></div>{{ end }}
|
||||
<div class="endpoint-module">
|
||||
<div class="endpoint-module-title">{{ $mod }}</div>
|
||||
<ul class="endpoint-list">
|
||||
{{ $current = $mod }}
|
||||
{{ end }}
|
||||
{{ $key := printf "%s|%s" .method .anchor }}
|
||||
<li>
|
||||
<a href="#{{ .anchor }}">
|
||||
<span class="http-api-method">{{ .method }}</span>
|
||||
<span class="endpoint-path">{{ .endpoint }}</span>
|
||||
{{ if .deprecated }}<span class="endpoint-deprecated">(deprecated)</span>{{ end }}
|
||||
</a>
|
||||
</li>
|
||||
{{ end }}
|
||||
{{ if $current }}</ul></div>{{ end }}
|
||||
</details>
|
||||
</div>
|
||||
{{ end }}
|
||||
|
|
@ -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 }}
|
||||
|
|
|
|||
|
|
@ -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 `<section>` 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 }}
|
||||
|
||||
<section class="rendered-data">
|
||||
|
||||
<details {{ if not site.Params.ui.rendered_data_collapsed }}open{{ end }}>
|
||||
|
|
|
|||
14
layouts/_partials/spec-content.html
Normal file
14
layouts/_partials/spec-content.html
Normal file
|
|
@ -0,0 +1,14 @@
|
|||
{{- /* Shared render for spec pages: title, optional description, endpoints list, body, and last-mod info. */ -}}
|
||||
<div class="td-content">
|
||||
<h1>{{ .Title }}</h1>
|
||||
{{ with .Params.description }}<p class="page-description">{{ . | markdownify }}</p>{{ 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 }}
|
||||
</div>
|
||||
|
|
@ -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 }}
|
||||
|
|
|
|||
|
|
@ -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) }}
|
||||
|
|
|
|||
|
|
@ -1,4 +0,0 @@
|
|||
<div class="td-content">
|
||||
<h1>{{ .Title }}</h1>
|
||||
{{ .Content }}
|
||||
</div>
|
||||
|
|
@ -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" }}
|
||||
<div class="td-content">
|
||||
<h1>{{ .Title }}</h1>
|
||||
{{ with .Params.description }}<div class="lead">{{ . | markdownify }}</div>{{ end }}
|
||||
{{ .Content }}
|
||||
</div>
|
||||
{{ partial "spec-content.html" . }}
|
||||
{{ end }}
|
||||
|
|
|
|||
19
layouts/docs/single.html
Normal file
19
layouts/docs/single.html
Normal file
|
|
@ -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 }}
|
||||
Loading…
Reference in a new issue