openapi tutorial layout

frontend/styles/atoms/table.css

@@ -17,6 +17,12 @@ table {
       }
     }
   }
+
+  &.word-break {
+    td {
+      word-break: break-all;
+    }
+  }
 }
 
 thead {
@@ -35,6 +41,10 @@ thead {
       border-right: var(--border-default);
       border-top-right-radius: var(--border-radius-large);
     }
+
+    code {
+      white-space: nowrap;
+    }
   }
 }
 

frontend/styles/index.css

@@ -32,4 +32,5 @@
 @import "pages/errored.css";
 @import "pages/guides.css";
 @import "pages/help.css";
+@import "pages/indepth-guide.css";
 @import "pages/updates.css";

frontend/styles/pages/guides.css

@@ -26,17 +26,17 @@
 }
 
 .guide {
-  & h1 {
-    font-size: clamp(2rem, 10vw, 2.5rem);
-  }
-
   .double-pane {
     --side-min-width: 250px;
   }
 
   .guide-content {
     padding-block: var(--spacing-10);
 
+    h1 {
+      font-size: clamp(2rem, 10vw, 2.5rem);
+    }
+
     .guide-cover {
       margin-bottom: var(--spacing-10);
     }

frontend/styles/pages/indepth-guide.css

@@ -0,0 +1,25 @@
+.indepth-guide {
+  .guide-content {
+    h1 {
+      margin-block-end: 0;
+    }
+
+    indepth-post-info {
+      margin-block-end: var(--spacing-7);
+    }
+  }
+
+  side-bar {
+    .item {
+      padding-inline: 0;
+    }
+
+    .sidebar-sublist {
+      margin-inline-start: 0;
+    }
+  }
+
+  bump-cta {
+    margin-block-start: var(--spacing-6);
+  }
+}

frontend/styles/variables/fonts.css

@@ -17,4 +17,14 @@
   --font-weight-normal: 500;
   --font-weight-semibold: 600;
   --font-weight-bold: 700;
+
+  --text-xxs: 0.625rem;
+  --text-xs: 0.75rem;
+  --text-sm: 0.875rem;
+  --text-base: 1rem;
+  --text-l: 1.125rem;
+  --text-xl: 1.25rem;
+  --text-2xl: 1.5rem;
+  --text-3xl: 2rem;
+  --text-5xl: 3rem;
 }

plugins/builders/sidebar.rb

@@ -1,23 +1,29 @@
 class Builders::Sidebar < SiteBuilder
   def build
     generator do
-      site.data.help_sidebar = build_resources(@site.data.sidebar.help)
+      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.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)
+        end
+      end
     end
   end
 
-  def build_resources(list)
+  def build_resources(list, collection, root)
     if list.present?
       list.map do |list_item|
         if list_item.link.present?
-          resource = site.collections.help.resources.find do |page|
-            page.relative_url.end_with?("/help#{list_item.link}")
+          resource = site.collections[collection].resources.find do |page|
+            page.relative_url.end_with?("#{root}#{list_item.link}")
           end
         end
         {
           label: list_item.label,
           icon: list_item.icon,
           resource: resource,
-          items: list_item.items.present? && build_resources(list_item.items)
+          items: list_item.items.present? && build_resources(list_item.items, collection, root)
         }
       end
     end

src/_components/guides/category/section.rb

@@ -7,9 +7,9 @@ def initialize(category:, title: nil, css_classes: "")
     @category_name = category.name
     @description = category.description
     @resources = @site.collections.guides.resources.select do |guide|
-      guide.data.categories.find do |category|
+      !guide.data.skip_listing && guide.data.categories.find { |category|
         Bridgetown::Utils.slugify(category) == Bridgetown::Utils.slugify(@category_name)
-      end
+      }
     end
     @remaining_count = @resources.count - 3
   end

src/_components/guides/in_depth/post_info.css

@@ -0,0 +1,16 @@
+indepth-post-info {
+  display: flex;
+  flex-wrap: wrap;
+  justify-content: space-between;
+
+  .author {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--spacing-2);
+  }
+
+  a {
+    display: inline-flex;
+    align-items: center;
+  }
+}

src/_components/guides/in_depth/post_info.erb

@@ -0,0 +1,16 @@
+<indepth-post-info>
+  <div class="author">
+    By
+    <% @authors.each do |author| %>
+      <%= author_name(author) %>
+      <% if !is_guest?(author) && github_link(author).present? %>
+        <%= link_to github_link(author), "aria-label": "Go to GitHub" do %>
+          <%= svg "images/icons/github.svg" %>
+        <% end %>
+      <% end %>
+    <% end %>
+  </div>
+  <div class="last-update">
+    <%= "Last update on #{@last_update.strftime("%B %d, %Y")}" %>
+  </div>
+</indepth-post-info>

src/_components/guides/in_depth/post_info.rb

@@ -0,0 +1,22 @@
+class Guides::InDepth::PostInfo < Bridgetown::Component
+  def initialize(authors:, last_update:)
+    @authors = authors.class == String ? [authors] : authors
+    @last_update = last_update
+  end
+
+  def is_guest?(author)
+    author_data(author).class == String
+  end
+
+  def author_name(author)
+    is_guest?(author) ? author : author_data(author).name
+  end
+
+  def github_link(author)
+    author_data(author).github.presence
+  end
+
+  def author_data(author)
+    Bridgetown::Current.site.data.authors[author] || author
+  end
+end

src/_data/sidebars/guides/openapi/v3-1.yml

@@ -0,0 +1,75 @@
+collection_name: guides
+root: /guides/openapi/specification/v3.1
+resources:
+  - type: category
+    label: Introduction to OpenAPI
+    items:
+      - label: What is OpenAPI?
+        link: /introduction/what-is-openapi/
+      - label: History and Evolution of OpenAPI
+        link: /introduction/history/
+      - label: Benefits of Using OpenAPI
+        link: /introduction/benefits/
+  - type: category
+    label: Understanding OpenAPI Structure
+    items:
+      - label: Basic Structure
+        link: /understanding-structure/basic-structure/
+      - label: Defining API Servers
+        link: /understanding-structure/api-servers/
+      - label: Paths and Operations
+        link: /understanding-structure/paths-operations/
+      - label: Parameters (Path, Query, Header, and Cookie)
+        link: /understanding-structure/parameters/
+      - label: Parameter Serialization
+        link: /understanding-structure/parameter-serialization/
+      - label: HTTP Requests
+        link: /understanding-structure/http-requests/
+      - label: HTTP Responses
+        link: /understanding-structure/http-responses/
+      - label: Components Section
+        link: /understanding-structure/components/
+  - type: category
+    label: Defining Data Models
+    items:
+      - label: Schema and Data Types
+        link: /data-models/schema-and-data-types/
+      - label: JSON Schema in OpenAPI
+        link: /data-models/json-schema/
+      - label: Examples and Default Values
+        link: /data-models/examples/
+      - label: Schema Composition
+        link: /data-models/schema-composition/
+      - label: Representing XML
+        link: /data-models/representing-xml/
+  - type: category
+    label: Advanced OpenAPI Specification
+    items:
+      - label: Supporting Multiple Content Types
+        link: /advanced/multiple-content-types/
+      - label: Multipart Form Data
+        link: /advanced/multipart-form-data/
+      - label: Handling Error Formats
+        link: /advanced/error-formats/
+      - label: Security Definitions (Authentication and Authorization)
+        link: /advanced/security/
+      - label: Callbacks and Webhooks
+        link: /advanced/callbacks-webhooks/
+      - label: Splitting OpenAPI into Multiple Documents
+        link: /advanced/splitting-documents-with-ref/
+  - type: category
+    label: Documenting APIs
+    items:
+      - label: Adding Descriptions and Summaries
+        link: /documentation/descriptions-and-summaries/
+      - label: Grouping Operations with Tags
+        link: /documentation/grouping-operations-with-tags/
+      - label: Linking to External Documentation
+        link: /documentation/external-documentation/
+  - type: category
+    label: Extending OpenAPI
+    items:
+      - label: Custom Extensions and Vendor Extensions
+        link: /extending/extensions/
+      - label: Enriching OpenAPI with Overlays
+        link: /extending/overlays/