From 845e98f04f4f5914d252b771c71cb5607cdc9b13 Mon Sep 17 00:00:00 2001 From: Thimy Kieu Date: Thu, 29 Aug 2024 14:10:52 +0200 Subject: [PATCH 1/4] create layout for new guides --- frontend/styles/index.css | 1 + frontend/styles/pages/guides.css | 8 +- frontend/styles/pages/indepth-guide.css | 25 +++ frontend/styles/variables/fonts.css | 10 ++ plugins/builders/sidebar.rb | 16 +- src/_components/guides/in_depth/post_info.css | 16 ++ src/_components/guides/in_depth/post_info.erb | 16 ++ src/_components/guides/in_depth/post_info.rb | 22 +++ src/_data/sidebars/guides/openapi/v3-1.yml | 75 +++++++++ src/_data/sidebars/help.yml | 145 ++++++++++++++++++ src/_guides/openapi/_defaults.yml | 1 + .../openapi/specification/_defaults.yml | 3 + .../openapi/specification/v3.1/_defaults.yml | 2 + src/_layouts/indepth_guide.erb | 23 +++ src/images/icons/documentation.svg | 8 + src/images/logos/openapi.svg | 12 ++ 16 files changed, 374 insertions(+), 9 deletions(-) create mode 100644 frontend/styles/pages/indepth-guide.css create mode 100644 src/_components/guides/in_depth/post_info.css create mode 100644 src/_components/guides/in_depth/post_info.erb create mode 100644 src/_components/guides/in_depth/post_info.rb create mode 100644 src/_data/sidebars/guides/openapi/v3-1.yml create mode 100644 src/_data/sidebars/help.yml create mode 100644 src/_guides/openapi/specification/_defaults.yml create mode 100644 src/_guides/openapi/specification/v3.1/_defaults.yml create mode 100644 src/_layouts/indepth_guide.erb create mode 100644 src/images/icons/documentation.svg create mode 100644 src/images/logos/openapi.svg 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/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..418e23a6 --- /dev/null +++ b/src/_guides/openapi/specification/_defaults.yml @@ -0,0 +1,3 @@ +layout: indepth_guide +page_class: guide indepth-guide with-sidebar +sidebar_title: OpenAPI Specification 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..20d30288 --- /dev/null +++ b/src/_layouts/indepth_guide.erb @@ -0,0 +1,23 @@ +--- +layout: default +--- + +<%= render Shared::Sidebar.new(data: site.data.guides_sidebar[resource.data.sidebar_name], 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 %> +
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 @@ + + + + + + + + + + + + From a0dac3ddf4f811c484974857a8dfe4f432d96f94 Mon Sep 17 00:00:00 2001 From: Thimy Kieu Date: Mon, 2 Sep 2024 10:36:25 +0200 Subject: [PATCH 2/4] guides: hide guides with skip_listing: true Adds a frontmatter attribute that hides an entry from being listed in the main guides page. --- src/_components/guides/category/section.rb | 4 ++-- src/_guides/openapi/specification/_defaults.yml | 1 + 2 files changed, 3 insertions(+), 2 deletions(-) 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/_guides/openapi/specification/_defaults.yml b/src/_guides/openapi/specification/_defaults.yml index 418e23a6..2c565685 100644 --- a/src/_guides/openapi/specification/_defaults.yml +++ b/src/_guides/openapi/specification/_defaults.yml @@ -1,3 +1,4 @@ layout: indepth_guide page_class: guide indepth-guide with-sidebar sidebar_title: OpenAPI Specification +skip_listing: true From 31070103e1b1e9a3a40201991f4f668e7e653d68 Mon Sep 17 00:00:00 2001 From: Thimy Kieu Date: Wed, 4 Sep 2024 14:19:00 +0200 Subject: [PATCH 3/4] show prev/next nav on openapi tutorials --- src/_layouts/indepth_guide.erb | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/_layouts/indepth_guide.erb b/src/_layouts/indepth_guide.erb index 20d30288..ffc0e3ac 100644 --- a/src/_layouts/indepth_guide.erb +++ b/src/_layouts/indepth_guide.erb @@ -2,7 +2,8 @@ layout: default --- -<%= render Shared::Sidebar.new(data: site.data.guides_sidebar[resource.data.sidebar_name], current: resource) do |sidebar| %> +<% @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 %> @@ -20,4 +21,5 @@ layout: default

<%= data.title %>

<%= render Guides::InDepth::PostInfo.new(authors: data.authors, last_update: data.date) %> <%= yield %> + <%= render Shared::PageNavigation.new(entries: @entries, current: resource) %> From 1063ba9a561f9106d2d20e2f5431ddb18e5e89a3 Mon Sep 17 00:00:00 2001 From: Thimy Kieu Date: Wed, 4 Sep 2024 14:53:06 +0200 Subject: [PATCH 4/4] tables: add classes to handle overflowing tables To be added on a per table basis. * full-bleed lets the table expand beyond the text column * break-word make table content break and wrap instead of forcing width based on content Also added `white-space: nowrap` to `code` in `th` so column name doesn't get squeezed. --- frontend/styles/atoms/table.css | 10 ++++++++++ 1 file changed, 10 insertions(+) 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; + } } }