layout: factorize help and in-depths guides (#284)

* layout: factorize help and in-depths guides

Creating a unique layout to be reused between help and in-depths guides
and adding options to display pagination, cta and authors.

* sidebar: remove left padding

* add toc to openapi guides

* docs: give max-height on images and center them

frontend/styles/index.css

@@ -10,6 +10,7 @@
 
 @import "layout.css";
 @import "typography.css";
+@import "layouts/documentation.css";
 
 @import "atoms/blockquote.css";
 @import "atoms/button.css";
@@ -31,6 +32,5 @@
 @import "pages/category.css";
 @import "pages/errored.css";
 @import "pages/guides.css";
-@import "pages/help.css";
 @import "pages/indepth-guide.css";
 @import "pages/updates.css";

frontend/styles/layout.css

@@ -24,50 +24,6 @@ body > footer {
   grid-area: footer;
 }
 
-body.with-sidebar {
-  display: grid;
-  grid-template-areas:
-    "header header"
-    "aside main"
-    "footer footer";
-
-  main {
-    box-sizing: border-box;
-    padding: var(--spacing-8) var(--spacing-10);
-    width: calc(100vw - var(--doc-sidebar-width) - var(--doc-sidebar-padding));
-
-    button {
-      display: none;
-      width: fit-content;
-    }
-
-    img {
-      max-width: 100%;
-    }
-  }
-
-  @media(max-width: 800px) {
-    main {
-      grid-column: 1 / -1;
-      width: 100%;
-
-      button {
-        display: inline-flex;
-      }
-    }
-  }
-
-  @container main (width < 800px) {
-    .main-content {
-      grid-template-columns: 1fr;
-    }
-
-    #markdown-toc {
-      display: none;
-    }
-  }
-}
-
 .wrapper {
   display: grid;
   grid-template-columns: 1fr min(var(--page-content-width), calc(100% - var(--spacing-20))) 1fr;

frontend/styles/pages/help.css → frontend/styles/layouts/documentation.css

@@ -1,14 +1,27 @@
-.help {
+.documentation {
+  display: grid;
+  grid-template-areas:
+    "header header"
+    "aside main"
+    "footer footer";
   height: 100dvh;
   overflow: hidden;
 
   main {
     align-content: start;
     align-items: start;
+    box-sizing: border-box;
     display: grid;
     gap: var(--gap-medium);
     justify-content: center;
     overflow-y: scroll;
+    padding: var(--spacing-8) var(--spacing-10);
+    width: calc(100vw - var(--doc-sidebar-width));
+
+    button {
+      display: none;
+      width: fit-content;
+    }
   }
 
   .main-content {
@@ -47,9 +60,36 @@
       grid-row: 1 / 1000;
     }
 
+    p:has(img) {
+      text-align: center;
+    }
+
     img {
       border-radius: var(--border-radius-xlarge);
       margin-inline: auto;
+      max-width: 100%;
+      max-height: 600px;
+    }
+  }
+
+  @media(max-width: 800px) {
+    main {
+      grid-column: 1 / -1;
+      width: 100%;
+
+      button {
+        display: inline-flex;
+      }
+    }
+  }
+
+  @container main (width < 800px) {
+    .main-content {
+      grid-template-columns: 1fr;
+    }
+
+    #markdown-toc {
+      display: none;
     }
   }
 }

frontend/styles/variables/sizes.css

@@ -1,6 +1,5 @@
 :root {
   --doc-sidebar-width: 300px;
-  --doc-sidebar-padding: var(--spacing-16);
   --doc-content-width: 80ch;
 
   --gap-xsmall: var(--spacing-1);

plugins/builders/sidebar.rb

@@ -1,11 +1,11 @@
 class Builders::Sidebar < SiteBuilder
   def build
     generator do
-      site.data.help_sidebar = build_resources(@site.data.sidebars.help.resources, @site.data.sidebars.help.collection_name, @site.data.sidebars.help.root)
-      site.data.guides_sidebar = {}
+      site.data.sidebar_entries = {}
+      site.data.sidebar_entries.help = build_resources(@site.data.sidebars.help.resources, @site.data.sidebars.help.collection_name, @site.data.sidebars.help.root)
       site.data.sidebars.guides.each do |specification_name, list|
         list.each do |version_name, attributes|
-          site.data.guides_sidebar["#{specification_name}_#{version_name}"] = build_resources(attributes.resources, attributes.collection_name, attributes.root)
+          site.data.sidebar_entries["#{specification_name}_#{version_name}"] = build_resources(attributes.resources, attributes.collection_name, attributes.root)
         end
       end
     end

src/_components/shared/sidebar.css

@@ -1,7 +1,6 @@
 side-bar {
   border-right: var(--border-default);
   overflow-y: scroll;
-  padding-inline-start: var(--spacing-16);
   width: var(--doc-sidebar-width);
   z-index: 90;
 

src/_guides/openapi/specification/_defaults.yml

@@ -1,4 +1,7 @@
-layout: indepth_guide
-page_class: guide indepth-guide with-sidebar
+layout: documentation
+page_class: documentation
 sidebar_title: OpenAPI Specification
 skip_listing: true
+display_authors: true
+display_pagination: true
+display_cta: true

src/_guides/openapi/specification/v3.1/advanced/callbacks-webhooks.md

@@ -5,6 +5,9 @@ excerpt: Dive into the world of API file uploads in OpenAPI.
 date: 2024-08-07
 ---
 
+- TOC
+{:toc}
+
 REST/HTTP APIs are often considered to be a simple request and response model, but they have always been a lot more asynchronous than that, and OpenAPI can capture two types of asynchronous HTTP event using `callbacks` and `webhooks`.
 
 Both of these types of events are basically a HTTP request being made by _your_ API, which is the opposite of all the other requests and responses being defined, but it works in a fairly familiar way.

src/_guides/openapi/specification/v3.1/advanced/error-formats.md

@@ -5,6 +5,8 @@ excerpt: Describing HTTP errors efficiently in OpenAPI v3.1.
 date: 2024-08-07
 ---
 
+- TOC
+{:toc}
 
 When your API is happy you return the data or whatever response the action would like to provide, but what happens when you stray off that happy path and into the world of errors? 
 

src/_guides/openapi/specification/v3.1/advanced/file-uploads.md

@@ -5,6 +5,9 @@ excerpt: Dive into the world of API file uploads in OpenAPI.
 date: 2024-08-07
 ---
 
+- TOC
+{:toc}
+
 APIs can handle file uploads in a variety of ways, and OpenAPI can help you describe any of them. The two most common methods are directly accepting the file based on the content-type of the request, e.g.: a HTTP request with `image/png`, `image/jpeg`, `text/csv`, etc., or a HTTP request with a `multipart/form-data` content type which allows you to combine text and file data in a single request. 
 
 Here's an example of accepting a CSV file being directly passed in the request body, showing how the HTTP request would look, then how that would be described in OpenAPI v3.1.

src/_guides/openapi/specification/v3.1/advanced/multipart-form-data.md

@@ -5,6 +5,9 @@ excerpt: Dive into the world of API file uploads in OpenAPI.
 date: 2024-08-06
 ---
 
+- TOC
+{:toc}
+
 Multipart form data is a content type used for HTTP requests to send a combination of text and file data in a single request, allowing for one or more uploaded files to be sent with other form fields. 
 
 In the context of an API, using multipart form data enables clients to send files to the server as part of a single API request, avoiding the need for metadata to be uploaded as one request then linking it back to the file somehow. This is handy when building resources that might have an avatar or a cover image, or sending a PDF that needs a name, description, and list of recipients.

src/_guides/openapi/specification/v3.1/advanced/multiple-content-types.md

@@ -5,6 +5,9 @@ excerpt:
 date: 2024-08-07
 ---
 
+- TOC
+{:toc}
+
 Let's dive into the nitty-gritty of describing multiple content types in OpenAPI. If you’ve ever needed to handle JSON, XML, CSV, and maybe even images in your API, you’re in the right place. This tutorial will guide you through setting up your OpenAPI document to gracefully handle multiple different formats.
 
 ### Why Support Multiple Content Types?

src/_guides/openapi/specification/v3.1/advanced/security.md

@@ -5,6 +5,9 @@ excerpt: Learn how OpenAPI describes authentication and authorization schemes fo
 date: 2024-08-07
 ---
 
+- TOC
+{:toc}
+
 OpenAPI uses the term "security scheme" to cover both authentication and authorization schemes. 
 
 - **Authentication:** Who is this user, are they who they say they are.

src/_guides/openapi/specification/v3.1/advanced/splitting-documents-with-ref.md

@@ -7,6 +7,9 @@ excerpt: Learn how to use $ref to reduce clutter and repetition in your OpenAPI
 date: 2024-07-10
 ---
 
+- TOC
+{:toc}
+
 After using OpenAPI for a while, you might notice your description documents have become a rather unwieldy mess of YAML and JSON. You end up with a whole lot of repetition, and this huge mess just loves to trigger merge conflicts as multiple developers change different things but Git seems none the wiser.
 
 You can avoid this pain by splitting description documents up with `$ref`, using various reusable components, but how exactly you go about doing that can be a tricky one to work out.

src/_guides/openapi/specification/v3.1/data-models/examples.md

@@ -5,6 +5,9 @@ excerpt: Use examples and defaults in OpenAPI to demonstrate API inputs and outp
 date: 2024-07-10
 ---
 
+- TOC
+{:toc}
+
 Examples and defaults are a change to demonstrate some potential input and output values. Examples are particularly useful at showing off parameters, headers, requests, responses, and various other bits of OpenAPI, which is handy for creating API documentation. These They can also be read by tools and libraries for other purposes, like an [API mocking tool][microcks] can use sample values to generate mock requests.
 
 # Examples

src/_guides/openapi/specification/v3.1/data-models/json-schema.md

@@ -5,6 +5,9 @@ excerpt: Learn how JSON Schema and OpenAPI Schema are similar and how they are d
 date: 2024-07-17
 ---
 
+- TOC
+{:toc}
+
 For a long time JSON Schema and OpenAPI Schema Objects were similar but different. OpenAPI was inspired by JSON Schema, then they both evolved separately, but finally in OpenAPI v3.1 with lots of work from both teams, the specifications realigned on JSON Schema Draft 2020-12. This means you can learn more about OpenAPI Schema Objects by learning more about JSON Schema.
 
 ## JSON Schema Documentation

src/_guides/openapi/specification/v3.1/data-models/representing-xml.md

@@ -5,6 +5,9 @@ excerpt: OpenAPI can describe XML APIs with a little work, learn how!
 date: 2024-07-24
 ---
 
+- TOC
+{:toc}
+
 OpenAPI is set up with the assumption that you're most likely describing JSON, because that's what over 80% of APIs are using, but XML is still in the game and you could be using both in the same API. OpenAPI supports this with the `xml` keyword, which helps when XML output is using XML-specific syntax like attributes and wrapped arrays.
 
 By combining [schema composition](_guides/openapi/specification/v3.1/data-models/schema-composition.md) and [references](_guides/openapi/specification/v3.1/advanced/splitting-documents-with-ref.md), it's possible to create reusable components that be used for both JSON and XML output, like this simplistic example below.

src/_guides/openapi/specification/v3.1/data-models/schema-and-data-types.md

@@ -5,6 +5,9 @@ excerpt: "Learn about the most important part of OpenAPI: schemas, and data type
 date: 2024-07-18
 ---
 
+- TOC
+{:toc}
+
 One of the most important parts of OpenAPI is the `schema` object. Schema objects are used to describe HTTP request and response bodies, parameters, headers, and all sorts of other data, whether its JSON, XML, or primitive types like integers and strings. 
 
 > If you're familiar with JSON Schema, you'll be right at home here, because OpenAPI v3.1 uses JSON Schema (draft 2020-12). For those who have not used JSON Schema before, that's ok, follow along.

src/_guides/openapi/specification/v3.1/data-models/schema-composition.md

@@ -5,6 +5,9 @@ excerpt: Use oneOf, anyOf, and allOf in OpenAPI & JSON Schema for polymorphism a
 date: 2024-07-24
 ---
 
+- TOC
+{:toc}
+
 In OpenAPI v3.1 and JSON Schema, you can use `oneOf`, `allOf`, and `anyOf` keywords to handle composition, which is the concept of combining multiple schemas and subschemas in various ways to handle polymorphism, or "extending" other schemas to add more criteria.
 
 ## What are oneOf, anyOf, and allOf?

src/_guides/openapi/specification/v3.1/documentation/descriptions-and-summaries.md

@@ -5,6 +5,9 @@ excerpt: Deliver on a great developer experience with improved OpenAPI descripti
 date: 2024-08-07
 ---
 
+- TOC
+{:toc}
+
 Often, API documentation is left to the end of the schedule, which can lead to a rushed set of API reference documentation. This results in terse outlines of what endpoints and parameters exist, but leave out the specifics of your well-designed and implemented API operation. One of the major ways to improve the developer experience is to upgrade your OpenAPI from being a quick list of parameters into a store of import context and human knowledge with expanding descriptions and summaries.
 
 ## Example of Incomplete Documentation

src/_guides/openapi/specification/v3.1/documentation/external-documentation.md

@@ -5,6 +5,9 @@ excerpt: Link OpenAPI documentation with other guides and tutorials.
 date: 2024-08-08
 ---
 
+- TOC
+{:toc}
+
 While the `description` property is excellent for giving a little more information about a specific tag, you might need to provide additional documentation if the business logic by a part of the API is complex, or there are lists of possible values defined outside of the API. 
 
 If anything requires further explanation, you can provide a link to an external web page where you offer a more detailed explanation using the `externalDocs` property.

src/_guides/openapi/specification/v3.1/documentation/grouping-operations-with-tags.md

@@ -6,6 +6,9 @@ excerpt: Learn tips and tricks to group related endpoints in a meaningful way.
 date: 2024-08-08
 ---
 
+- TOC
+{:toc}
+
 Tags are a great way to organize the API endpoints in your OpenAPI documents.
 
 Typically, OpenAPI tags are used to group related endpoints in a meaningful way, such as by business function or logical objects. When using tags, you define an array of tags at the root of your document, like this:

src/_guides/openapi/specification/v3.1/extending/extensions.md

@@ -5,6 +5,9 @@ excerpt: Using extensions allows you to customize and integrate various tools th
 date: 2024-03-20
 ---
 
+- TOC
+{:toc}
+
 OpenAPI v3.1 has a concept of [Specification Extensions](https://spec.openapis.org/oas/v3.1.0#specification-extensions) which are additional properties not specified by the OpenAPI specification. These are a chance to customize and integrate tools from documentation to API gateways, all hooking into the OpenAPI document and storing information important to them in the form of extra properties that will be ignored by other tooling. 
 
 All those properties start with the `x-` naming convention to be identified as “eXternal” from the OpenAPI specification.

src/_guides/openapi/specification/v3.1/extending/overlays.md

@@ -5,6 +5,9 @@ excerpt: Use OpenAPI Overlays to enrich you API descriptions without creating co
 date: 2024-03-20
 ---
 
+- TOC
+{:toc}
+
 However you make OpenAPI descriptions for your APIs, there are all sorts of scenarios where you might want to customize it for different audiences. Perhaps your tech writers want to add amazing longer descriptions but they are locked out of the source code, or you want to hide some internal endpoints from your OpenAPI before publishing. Is it possible to do all this without awkwardly managing multiple similar-but-different OpenAPI documents?
 
 The OpenAPI Initiative have released a new concept called "Overlays". This is [separate specification](https://github.com/OAI/Overlay-Specification) but compatible with OpenAPI, and while it's labelled "experimental" its a v1.0.0, with support in a variety of tooling including [Bump.sh](https://bump.sh). 

src/_guides/openapi/specification/v3.1/introduction/benefits.md

@@ -5,6 +5,9 @@ excerpt: OpenAPI allows to describe how an API works, how a sequence of APIs wor
 date: 2024-07-25
 ---
 
+- TOC
+{:toc}
+
 OpenAPI is a game-changer for saving your team time and money. By automating routine tasks like creating detailed API documentation, generating client libraries and generating chunks of server-side code, even automating the checking of the API against style guides, it frees up your developers to focus on more important work. This means faster development and fewer hours spent on repetitive coding, which saves time and money as better quality APIs can be delivered quicker.
 
 It also makes collaboration smoother and more efficient. With OpenAPI, you have a clear, consistent description of your API that everyone can follow. This reduces misunderstandings and miscommunications between different teams—whether they're front-end, back-end, or QA. Fewer mix-ups mean less time fixing errors and more time building great features.

src/_guides/openapi/specification/v3.1/introduction/history.md

@@ -5,6 +5,9 @@ excerpt: OpenAPI allows to describe how an API works, how a sequence of APIs wor
 date: 2024-07-25
 ---
 
+- TOC
+{:toc}
+
 The OpenAPI Specification started off life with another name, and this can cause a bit of confusion. Until version 3.0, the specification was still called "Swagger", before being renamed to "OpenAPI" in 2016. It's actually a "retroactive" rename, so even v2.0 and earlier are called OpenAPI now.
 
 The OpenAPI Specification is now supervised by the [OpenAPI Initiative](https://www.openapis.org/), an open-source project under the [Linux Foundation](https://linuxfoundation.org/).

src/_guides/openapi/specification/v3.1/introduction/what-is-openapi.md

@@ -5,6 +5,9 @@ excerpt: OpenAPI allows to describe how an API works, how a sequence of APIs wor
 date: 2024-07-25
 ---
 
+- TOC
+{:toc}
+
 OpenAPI is a standard for describing an API (Application Programming Interface). The OpenAPI Specification (OAS) defines an open and independent description format for HTTP API services, which allows both humans and computers to discover and understand how an API works and how to interact with it, without the need to look at the source code. 
 
 OpenAPI provides a machine-readable structured data format which can be also be read and written by people, allowing for tooling to help API developers, API product managers, technical writers, and governance teams, all the way through the API lifecycle.

src/_guides/openapi/specification/v3.1/understanding-structure/api-servers.md

@@ -5,6 +5,9 @@ excerpt: Learn about the API Servers section of the OpenAPI Specification.
 date: 2024-07-02
 ---
 
+- TOC
+{:toc}
+
 The servers section in an OpenAPI specification serves as a roadmap, detailing the various environments your API is accessible from. It's a straightforward yet powerful way to communicate the base URLs of your API across different stages of its lifecycle, or in different environments the end-users might be interested in like a mocking server, or a sandbox for interacting with the API without real-world consequences. 
 
 Here is an example of how you can define API servers in your OpenAPI specification:

src/_guides/openapi/specification/v3.1/understanding-structure/basic-structure.md

@@ -5,6 +5,9 @@ excerpt: Learn your way around the OpenAPI description format for HTTP APIs by l
 date: 2024-07-02
 ---
 
+- TOC
+{:toc}
+
 The OpenAPI Specification (OAS) is an "API Description Format", providing a standard format for describing REST APIs, making it easier to design, document, and consume them.
 
 In this tutorial we'll explore the structure of an OpenAPI document, focusing on the main sections and important elements, so that you can get a feel for where everything is, without having to scan through the whole OpenAPI Specification yourself.