diff --git a/frontend/styles/atoms/table.css b/frontend/styles/atoms/table.css
index 3d4536ed..fa247858 100644
--- a/frontend/styles/atoms/table.css
+++ b/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;
+ }
}
}
diff --git a/frontend/styles/index.css b/frontend/styles/index.css
index fe45fffb..af5f27d8 100644
--- a/frontend/styles/index.css
+++ b/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";
diff --git a/frontend/styles/pages/guides.css b/frontend/styles/pages/guides.css
index 9aeb363f..e2c4b24f 100644
--- a/frontend/styles/pages/guides.css
+++ b/frontend/styles/pages/guides.css
@@ -26,10 +26,6 @@
}
.guide {
- & h1 {
- font-size: clamp(2rem, 10vw, 2.5rem);
- }
-
.double-pane {
--side-min-width: 250px;
}
@@ -37,6 +33,10 @@
.guide-content {
padding-block: var(--spacing-10);
+ h1 {
+ font-size: clamp(2rem, 10vw, 2.5rem);
+ }
+
.guide-cover {
margin-bottom: var(--spacing-10);
}
diff --git a/frontend/styles/pages/indepth-guide.css b/frontend/styles/pages/indepth-guide.css
new file mode 100644
index 00000000..76567589
--- /dev/null
+++ b/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);
+ }
+}
diff --git a/frontend/styles/variables/fonts.css b/frontend/styles/variables/fonts.css
index e1df2029..789d01f6 100644
--- a/frontend/styles/variables/fonts.css
+++ b/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;
}
diff --git a/plugins/builders/sidebar.rb b/plugins/builders/sidebar.rb
index ffb920c3..0f2be246 100644
--- a/plugins/builders/sidebar.rb
+++ b/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
diff --git a/src/_components/guides/category/section.rb b/src/_components/guides/category/section.rb
index 688ce44e..78f31ae8 100644
--- a/src/_components/guides/category/section.rb
+++ b/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
diff --git a/src/_components/guides/in_depth/post_info.css b/src/_components/guides/in_depth/post_info.css
new file mode 100644
index 00000000..d7df007f
--- /dev/null
+++ b/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;
+ }
+}
diff --git a/src/_components/guides/in_depth/post_info.erb b/src/_components/guides/in_depth/post_info.erb
new file mode 100644
index 00000000..a2f7a3ea
--- /dev/null
+++ b/src/_components/guides/in_depth/post_info.erb
@@ -0,0 +1,16 @@
+
+
+ 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 %>
+
+
+ <%= "Last update on #{@last_update.strftime("%B %d, %Y")}" %>
+
+
diff --git a/src/_components/guides/in_depth/post_info.rb b/src/_components/guides/in_depth/post_info.rb
new file mode 100644
index 00000000..b59ddfe6
--- /dev/null
+++ b/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
diff --git a/src/_data/sidebars/guides/openapi/v3-1.yml b/src/_data/sidebars/guides/openapi/v3-1.yml
new file mode 100644
index 00000000..3e3138f4
--- /dev/null
+++ b/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/
diff --git a/src/_data/sidebars/help.yml b/src/_data/sidebars/help.yml
new file mode 100644
index 00000000..861d3fcc
--- /dev/null
+++ b/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
diff --git a/src/_guides/openapi/_defaults.yml b/src/_guides/openapi/_defaults.yml
index 1193614e..6003ad3f 100644
--- a/src/_guides/openapi/_defaults.yml
+++ b/src/_guides/openapi/_defaults.yml
@@ -1 +1,2 @@
categories: OpenAPI
+sidebar: true
diff --git a/src/_guides/openapi/specification/_defaults.yml b/src/_guides/openapi/specification/_defaults.yml
new file mode 100644
index 00000000..2c565685
--- /dev/null
+++ b/src/_guides/openapi/specification/_defaults.yml
@@ -0,0 +1,4 @@
+layout: indepth_guide
+page_class: guide indepth-guide with-sidebar
+sidebar_title: OpenAPI Specification
+skip_listing: true
diff --git a/src/_guides/openapi/specification/v3.1/_defaults.yml b/src/_guides/openapi/specification/v3.1/_defaults.yml
new file mode 100644
index 00000000..3f143b9d
--- /dev/null
+++ b/src/_guides/openapi/specification/v3.1/_defaults.yml
@@ -0,0 +1,2 @@
+sidebar_version: "v3.1"
+sidebar_name: openapi_v3-1
diff --git a/src/_layouts/indepth_guide.erb b/src/_layouts/indepth_guide.erb
new file mode 100644
index 00000000..ffc0e3ac
--- /dev/null
+++ b/src/_layouts/indepth_guide.erb
@@ -0,0 +1,25 @@
+---
+layout: default
+---
+
+<% @entries = site.data.guides_sidebar[resource.data.sidebar_name] %>
+<%= render Shared::Sidebar.new(data: @entries, current: resource) do |sidebar| %>
+ <% sidebar.slot :before do %>
+
+ <%= resource.data.sidebar_title %>
+ <%= resource.data.sidebar_version %>
+
+ <% end %>
+ <% sidebar.slot :after do %>
+ <%= render Shared::BumpCta.new(slug: site.data.slug) %>
+ <% end %>
+<% end %>
+
+
+ <%= data.title %>
+ <%= render Guides::InDepth::PostInfo.new(authors: data.authors, last_update: data.date) %>
+ <%= yield %>
+ <%= render Shared::PageNavigation.new(entries: @entries, current: resource) %>
+
diff --git a/src/images/icons/documentation.svg b/src/images/icons/documentation.svg
new file mode 100644
index 00000000..aefce1b3
--- /dev/null
+++ b/src/images/icons/documentation.svg
@@ -0,0 +1,8 @@
+
diff --git a/src/images/logos/openapi.svg b/src/images/logos/openapi.svg
new file mode 100644
index 00000000..f8615c1a
--- /dev/null
+++ b/src/images/logos/openapi.svg
@@ -0,0 +1,12 @@
+