create layout for new guides

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/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: History and Evolution of OpenAPI
+        link: /understanding-structure/api-servers/
+      - label: Benefits of Using OpenAPI
+        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/

src/_data/sidebars/help.yml

@@ -0,0 +1,145 @@
+collection_name: help
+root: /help
+resources:
+  - label: Home
+    link: /
+    icon: home
+  - label: Getting started
+    link: /getting-started/
+    items:
+      - label: Important concepts
+        link: /getting-started/concepts/
+      - label: Upload your first API definition
+        link: /getting-started/upload-your-first-definition/
+      - label: Going further
+        link: /getting-started/going-further/
+    icon: zap
+  - type: category
+    label: Integrate Bump.sh with your workflow
+    link: /continuous-integration/
+    icon: terminal
+    items:
+      - label: Github Action
+        link: /continuous-integration/github-actions/
+      - label: CI
+        link: /continuous-integration/ci/
+      - label: CLI
+        link: /continuous-integration/cli/
+      - label: API (advanced)
+        link: /continuous-integration/api/
+  - type: category
+    label: Publish Documentation
+    link: /publish-documentation/
+    icon: book-open-check
+    items:
+      - type: page
+        label: Create and manage documentation
+        link: /publish-documentation/create-and-manage-documentation/
+      - type: page
+        label: Deploy and release management
+        link: /publish-documentation/deploy-and-release-management/
+      - type: page
+        label: Branching
+        link: /publish-documentation/branching/
+      - type: page
+        label: Documentation access management
+        link: /publish-documentation/documentation-access-management/
+      - type: page
+        label: SEO
+        link: /publish-documentation/seo/
+      - type: page
+        label: Get feedback from users
+        link: /publish-documentation/feedback/
+  - type: category
+    label: Enhance your documentation content
+    link: /enhance-documentation-content/
+    icon: pencil-line
+    items:
+      - label: Markdown support
+        link: /enhance-documentation-content/markdown-support/
+      - label: Topics
+        link: /enhance-documentation-content/topics/
+  - type: category
+    label: Customization Options
+    link: /customization-options/
+    icon: sparkles
+    items:
+      - label: Custom domains
+        link: /customization-options/custom-domains/
+      - label: Color, logo and meta images
+        link: /customization-options/color-logo-meta-images/
+      - label: Login page
+        link: /customization-options/login/
+      - label: Operations & Navigation
+        link: /customization-options/operations-navigation/
+  - type: category
+    label: Changes management
+    link: /changes-management/
+    icon: bell-dot
+    items:
+      - label: Changelog
+        link: /changes-management/changelog/
+      - label: Integrations
+        link: /changes-management/integrations/
+  - type: category
+    label: Hubs
+    link: /hubs/
+    icon: hub
+    items:
+      - label: Create and manage hubs
+        link: /hubs/create-and-manage-hubs/
+      - label: Hub settings
+        link: /hubs/hub-settings/
+  - type: category
+    label: Organizations
+    link: /organizations/
+    icon: org
+    items:
+      - label: Create and manage organizations
+        link: /organizations/create-and-manage-organizations/
+      - label: Organization Access Management
+        link: /organizations/organization-access-management/
+      - label: Personal user account migration
+        link: /organizations/personal-user-account-migration/
+  - label: Account
+    icon: user
+    items:
+      - label: User account settings
+        link: /account/user-account-settings/
+      - label: Billing
+        link: /account/billing/
+      - label: Github Student
+        link: /account/github-student/
+  - type: category
+    label: Specification Support
+    link: /specification-support/
+    icon: code-file
+    items:
+      - label: Common elements
+        items:
+          - label: JSON Schema
+            link: /specification-support/json-schema/
+          - label: Multiple servers
+            link: /specification-support/multiple-servers/
+          - label: Polymorphism
+            link: /specification-support/polymorphism/
+          - label: References
+            link: /specification-support/references/
+          - label: Specification extensions
+            link: /specification-support/extensions/
+          - label: Beta
+            link: /specification-support/doc-beta/
+          - label: Overlays
+            link: /specification-support/overlays/
+      - label: OpenAPI support
+        link: /specification-support/openapi-support/
+        items:
+          - label: Webhooks
+            link: /specification-support/openapi-support/webhooks/
+          - label: Custom code samples
+            link: /specification-support/doc-code-samples/
+      - label: AsyncAPI support
+        link: /specification-support/asyncapi-support/
+  - label: FAQ
+    link: /faq/
+    icon: help-circle

src/_guides/openapi/_defaults.yml

@@ -1 +1,2 @@
 categories: OpenAPI
+sidebar: true

src/_guides/openapi/specification/_defaults.yml

@@ -0,0 +1,3 @@
+layout: indepth_guide
+page_class: guide indepth-guide with-sidebar
+sidebar_title: OpenAPI Specification

src/_guides/openapi/specification/v3.1/_defaults.yml

@@ -0,0 +1,2 @@
+sidebar_version: "v3.1"
+sidebar_name: openapi_v3-1