From f2fde4312bf880ce5400d7b23d4d04315daa74b6 Mon Sep 17 00:00:00 2001 From: Chris Wood Date: Sat, 1 Nov 2025 17:58:22 +0000 Subject: [PATCH 1/5] chore: Add initial revision --- .prettierrc.json | 7 +- src/website/design/content-redesign-notes.md | 92 ++++++++++++++++++++ 2 files changed, 95 insertions(+), 4 deletions(-) create mode 100644 src/website/design/content-redesign-notes.md diff --git a/.prettierrc.json b/.prettierrc.json index d6752c8..82d30fb 100644 --- a/.prettierrc.json +++ b/.prettierrc.json @@ -1,10 +1,9 @@ { "overrides": [ { - "files": ["*.md"], - "options": { - "proseWrap": "always" - } + "files": [ + "*.md" + ] } ] } \ No newline at end of file diff --git a/src/website/design/content-redesign-notes.md b/src/website/design/content-redesign-notes.md new file mode 100644 index 0000000..833b8bd --- /dev/null +++ b/src/website/design/content-redesign-notes.md @@ -0,0 +1,92 @@ +# Website Layout + +This document provides an overview of the content design for the revised openapis.org website. + +## Menu + +This section provides the content of the menu bar. + +### Drop downs + +The following are the drop downs we should aim for. + +```text +Learn +├── What Is OpenAPI? (Relocate existing page). +├── [Learn About OAI](https://learn.openapis.org/) +├── [OAI Courses](https://training.linuxfoundation.org/full-catalog/?_sf_s=openapi) +Specifications +| +├── [OpenAPI](https://spec.openapis.org/oas) +├── [Arazzo](https://spec.openapis.org/arazzo) +├── [Overlay](https://spec.openapis.org/overlay) +├── [Registries](https://spec.openapis.org/registry/) +Community +├── [Collaborate on Slack](https://communityinviter.com/apps/open-api/openapi) +├── Participate + ├── [OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/main/README.md#participation) + ├── [Arazzo](https://github.com/OAI/Arazzo-Specification?tab=readme-ov-file#getting-involved) + ├── [Overlay](https://github.com/OAI/Overlay-Specification) +├── Current Members (Relocate existing page) +├── Become a Member (Relocate existing page) +Events +Blog +``` + +## Homepage + +Proposed design notes for homepage. + +### Banner + +> Looking at the top section of https://graphql.org/ for inspiration here, think the headline section works really well. + +Title: API Description Languages for the API Economy. + +- Open, language-agnostic API description with the OpenAPI Specification. + +- Extend descriptions to multistep API-driven workflows with the Arazzo Specification. + +- Automate maintenance and increase efficiency with the Overlay Specification. + +The OpenAPI Initiative supports the development of the OpenAPI, Arazzo, and Overlay Specifications, which are trusted by millions of developers when creating, describing and consuming APIs. + +> HERE LETS HAVE A CAROUSEL OF MEMBER LOGOS THAT AUTO TRANSITIONS RIGHT TO LEFT, SHOWING MEMBER LOGOS +> Button under the carousel - "All Current Members" - goes to https://www.openapis.org/members + +### Main Section + +> These are just rough ideas, to iterate over some content for the page. Ignore the formatting, it's the layout calls to action that are important. + +
+ +
+

Why Use OpenAPI?

+
+ +
+

OpenAPI is the foremost API description language available to the API community today, and powers how knowledge of APIs are shared between API creators and the organization that use them. OpenAPI is a rich, vendor and programming language and vendor agnostic language, that reflects how APIs are created and published, and is supported by a huge and vibrant tooling community.

+
+ +
+ +> Here an overview diagram that lays out view of where OpenAPI + +### Footer + +Much of this content will be relocated from existing pages... + +- See the Audit Section that provides list of pages to be relocated. + +## Audit + +This is intended to provide an overview of where pages go from and to. + +Not complete, will be gradually updated as this work progresses. + +| Page | Location | New Location | Actions | Location | +| ----------------------------------- | -------------------------------------------------- | -------------------------------------------- | -------------------------------------------------------- | ----------------- | +| About | Menu > About > About | Footer > About | | /about | +| Technical Steering Committee | Menu > About > Technical Steering Committee | Footer > Technical Steering Committee | | /governance/tsc | +| Code of Conduct Transparency Report | Menu > About > Code of Conduct Transparency Report | Footer > Code of Conduct Transparency Report | | /governance/coctr | +| _All Specifications Menu Items_ | Menu > Specifications > \* | As per new Menu design | Anything not listed in the Menu section above is removed | N/A | From 9aec14d9b3fe3120654f098c04e4be0c2ec799ac Mon Sep 17 00:00:00 2001 From: Chris Wood Date: Sat, 1 Nov 2025 18:00:33 +0000 Subject: [PATCH 2/5] chore: Revert errant changes to prettier config --- .prettierrc.json | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/.prettierrc.json b/.prettierrc.json index 82d30fb..d6752c8 100644 --- a/.prettierrc.json +++ b/.prettierrc.json @@ -1,9 +1,10 @@ { "overrides": [ { - "files": [ - "*.md" - ] + "files": ["*.md"], + "options": { + "proseWrap": "always" + } } ] } \ No newline at end of file From e5201457ce96f9cf034288287f856804ff79bf6f Mon Sep 17 00:00:00 2001 From: Chris Wood Date: Fri, 7 Nov 2025 10:17:00 +0000 Subject: [PATCH 3/5] Update src/website/design/content-redesign-notes.md Accepted suggestion to "Online Courses" Co-authored-by: Pavel Kornev --- src/website/design/content-redesign-notes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/website/design/content-redesign-notes.md b/src/website/design/content-redesign-notes.md index 833b8bd..5f5e8a6 100644 --- a/src/website/design/content-redesign-notes.md +++ b/src/website/design/content-redesign-notes.md @@ -14,7 +14,7 @@ The following are the drop downs we should aim for. Learn ├── What Is OpenAPI? (Relocate existing page). ├── [Learn About OAI](https://learn.openapis.org/) -├── [OAI Courses](https://training.linuxfoundation.org/full-catalog/?_sf_s=openapi) +├── [Online Courses](https://training.linuxfoundation.org/full-catalog/?_sf_s=openapi) Specifications | ├── [OpenAPI](https://spec.openapis.org/oas) From 79d739354f974ca758def1a25589d4d476f16b2a Mon Sep 17 00:00:00 2001 From: Chris Wood Date: Fri, 7 Nov 2025 10:18:19 +0000 Subject: [PATCH 4/5] Update src/website/design/content-redesign-notes.md Accept suggestion to change menu item name, will also look to refactor the page content. Co-authored-by: Pavel Kornev --- src/website/design/content-redesign-notes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/website/design/content-redesign-notes.md b/src/website/design/content-redesign-notes.md index 5f5e8a6..43f2da9 100644 --- a/src/website/design/content-redesign-notes.md +++ b/src/website/design/content-redesign-notes.md @@ -12,7 +12,7 @@ The following are the drop downs we should aim for. ```text Learn -├── What Is OpenAPI? (Relocate existing page). +├── What Is OpenAPI Initiative? (Relocate existing page). ├── [Learn About OAI](https://learn.openapis.org/) ├── [Online Courses](https://training.linuxfoundation.org/full-catalog/?_sf_s=openapi) Specifications From 0949470a332ac5dde31d3e6131390ca1836304f8 Mon Sep 17 00:00:00 2001 From: Chris Wood Date: Sun, 30 Nov 2025 16:50:01 +0000 Subject: [PATCH 5/5] chore: Updated website notes --- src/website/design/content-redesign-notes.md | 58 ++++++++++++++++---- 1 file changed, 46 insertions(+), 12 deletions(-) diff --git a/src/website/design/content-redesign-notes.md b/src/website/design/content-redesign-notes.md index 43f2da9..0b1abdc 100644 --- a/src/website/design/content-redesign-notes.md +++ b/src/website/design/content-redesign-notes.md @@ -51,17 +51,32 @@ Title: API Description Languages for the API Economy. The OpenAPI Initiative supports the development of the OpenAPI, Arazzo, and Overlay Specifications, which are trusted by millions of developers when creating, describing and consuming APIs. -> HERE LETS HAVE A CAROUSEL OF MEMBER LOGOS THAT AUTO TRANSITIONS RIGHT TO LEFT, SHOWING MEMBER LOGOS -> Button under the carousel - "All Current Members" - goes to https://www.openapis.org/members - -### Main Section +### Our Specifications > These are just rough ideas, to iterate over some content for the page. Ignore the formatting, it's the layout calls to action that are important. +The OpenAPI Initiative is a family of three specifications: OpenAPI, Arazzo, and Overlay. + +#### OpenAPI + +
+
+ Graphic showing example OpenAPI Description Document +
+
+

OpenAPI is the foremost API description language available to the API community today, and powers how knowledge of APIs are shared between API creators and the organization that use them. OpenAPI is a rich, vendor and programming language and vendor agnostic language, that reflects how APIs are created and published, and is supported by a huge and vibrant tooling community.

+
+
+ +
+
+ +#### Arazzo +
-

Why Use OpenAPI?

+

Arazzo Specification

@@ -70,7 +85,26 @@ The OpenAPI Initiative supports the development of the OpenAPI, Arazzo, and Over
-> Here an overview diagram that lays out view of where OpenAPI +### Join the Community! + +The OpenAPI Initiative is a not-for-profit organization funded entirely by membership. Our members understand and rely our specifications for this success in the API economy. + +_I would suggest we use a 2x2 grid here maybe, to compress the content to shoehorn as much as possible._ + +_List the follow_ + +- Join us on Slack +- Join our meetings (link to calendar) +- Upcoming events (link to conference site) +- Latest news (link to blog) + +### Become a Member + +Want to help fund the future development of OpenAPI Initiative specifications? + +[Learn more](###MEMBER LINK###) about becoming a member. + +> Just above the footer some means to display member logos - could be a carousel of all members, could be a just the biggest - however we do it, I think it should be equitable i.e. everyone who is a member gets their logo displayed at some point ### Footer @@ -84,9 +118,9 @@ This is intended to provide an overview of where pages go from and to. Not complete, will be gradually updated as this work progresses. -| Page | Location | New Location | Actions | Location | -| ----------------------------------- | -------------------------------------------------- | -------------------------------------------- | -------------------------------------------------------- | ----------------- | -| About | Menu > About > About | Footer > About | | /about | -| Technical Steering Committee | Menu > About > Technical Steering Committee | Footer > Technical Steering Committee | | /governance/tsc | -| Code of Conduct Transparency Report | Menu > About > Code of Conduct Transparency Report | Footer > Code of Conduct Transparency Report | | /governance/coctr | -| _All Specifications Menu Items_ | Menu > Specifications > \* | As per new Menu design | Anything not listed in the Menu section above is removed | N/A | +| Page | Location | New Location | Actions | Location | +| --- | --- | --- | --- | --- | +| About | Menu > About > About | Footer > About | | /about | +| Technical Steering Committee | Menu > About > Technical Steering Committee | Footer > Technical Steering Committee | | /governance/tsc | +| Code of Conduct Transparency Report | Menu > About > Code of Conduct Transparency Report | Footer > Code of Conduct Transparency Report | | /governance/coctr | +| _All Specifications Menu Items_ | Menu > Specifications > \* | As per new Menu design | Anything not listed in the Menu section above is removed | N/A |