diff --git a/.changeset/quiet-suns-report.md b/.changeset/quiet-suns-report.md new file mode 100644 index 0000000000..bab7d12de8 --- /dev/null +++ b/.changeset/quiet-suns-report.md @@ -0,0 +1,10 @@ +--- +'@commercetools-website/self-learning-smoke-test': minor +'@commercetools-website/api-docs-smoke-test': minor +'@commercetools-docs/gatsby-theme-docs': minor +'@commercetools-website/docs-smoke-test': minor +'@commercetools-website/documentation': minor +'@commercetools-website/site-template': minor +--- + +Enable support for clickable chapter titles in websites. This is NOT a breaking change as we keep supporting non clickable chapters. diff --git a/packages/gatsby-theme-docs/gatsby-node.mjs b/packages/gatsby-theme-docs/gatsby-node.mjs index 0601716a0d..6f45142617 100644 --- a/packages/gatsby-theme-docs/gatsby-node.mjs +++ b/packages/gatsby-theme-docs/gatsby-node.mjs @@ -162,6 +162,7 @@ export const createSchemaCustomization = ({ actions, schema }) => { type NavigationYaml implements Node @dontInfer { id: ID! chapterTitle: String! @proxy(from: "chapter-title") + path: String beta: Boolean pagination: Boolean pages: [NavigationPage!] @@ -471,6 +472,7 @@ async function createContentPages( allNavigationYaml { nodes { chapterTitle + path pages { title path diff --git a/packages/gatsby-theme-docs/src/components/content-pagination.js b/packages/gatsby-theme-docs/src/components/content-pagination.js index a1240c0a4d..f44cb0b886 100644 --- a/packages/gatsby-theme-docs/src/components/content-pagination.js +++ b/packages/gatsby-theme-docs/src/components/content-pagination.js @@ -104,25 +104,76 @@ PaginationLink.propTypes = { direction: PropTypes.oneOf(['left', 'right']).isRequired, }; +// TODO: cleanup. After docs websites migrate to clickable chapter, this function +// can be simplified/removed or refactored since is currently supporting both clickable +// and non-clickable configs +const isChapterPathOrPageMatchingSlug = (node, slug) => { + if (node.path && isMatching(slug, node.path)) { + return true; + } + return node.pages.some((page) => isMatching(slug, page.path)); +}; + +// TODO: cleanup. After docs websites migrate to clickable chapter, this function +// can be simplified/removed or refactored since is currently supporting both clickable +// and non-clickable configs +const findActivePageIndex = (node, slug) => { + let indexOffset = 0; + if (node.path) { + indexOffset = 1; + } + if (node.path && isMatching(slug, node.path)) { + return 0; + } + const index = node.pages.findIndex( + (page) => page.path && isMatching(slug, page.path) + ); + if (index >= 0) { + return index + indexOffset; + } + return index; +}; + +// TODO: cleanup. After docs websites migrate to clickable chapter, this function +// can be simplified/removed or refactored since is currently supporting both clickable +// and non-clickable configs +const getPreviousPageLink = (node, currentIndex) => { + if (node.path) { + if (currentIndex === 1) { + // return the chapter + return { path: node.path, title: node.chapterTitle }; + } else { + return node.pages[currentIndex - 2]; + } + } + return node.pages[currentIndex - 1]; +}; + +// TODO: cleanup. After docs websites migrate to clickable chapter, this function +// can be simplified/removed or refactored since is currently supporting both clickable +// and non-clickable configs +const getNextPageLink = (node, currentIndex) => { + const indexOffset = node.path ? 1 : 0; + return node.pages[currentIndex - indexOffset + 1]; +}; + export const PurePagination = (props) => { const activeChapter = props.data.allNavigationYaml.nodes.find((node) => { const isPaginationEnabledForChapter = typeof node.pagination === 'boolean' ? node.pagination : true; if (!isPaginationEnabledForChapter) return false; if (!node.pages) return false; - return node.pages.some((page) => isMatching(props.slug, page.path)); + return isChapterPathOrPageMatchingSlug(node, props.slug); }); if (!activeChapter) { return ; } - const currentPageLinkIndex = activeChapter.pages.findIndex((page) => - isMatching(props.slug, page.path) - ); + const currentPageLinkIndex = findActivePageIndex(activeChapter, props.slug); const hasPagination = currentPageLinkIndex > -1; - const previousPage = activeChapter.pages[currentPageLinkIndex - 1]; - const nextPage = activeChapter.pages[currentPageLinkIndex + 1]; + const previousPage = getPreviousPageLink(activeChapter, currentPageLinkIndex); + const nextPage = getNextPageLink(activeChapter, currentPageLinkIndex); return ( @@ -176,6 +227,7 @@ const Pagination = (props) => { allNavigationYaml { nodes { chapterTitle + path pagination pages { title diff --git a/packages/gatsby-theme-docs/src/layouts/internals/sidebar.js b/packages/gatsby-theme-docs/src/layouts/internals/sidebar.js index 2cc25246bc..7cc46a9116 100644 --- a/packages/gatsby-theme-docs/src/layouts/internals/sidebar.js +++ b/packages/gatsby-theme-docs/src/layouts/internals/sidebar.js @@ -83,6 +83,16 @@ const LinkTitle = styled.div` overflow-x: hidden; width: 100%; `; +const LinkChapterTitle = styled.div` + font-size: ${designSystem.typography.fontSizes.body}; + text-overflow: ellipsis; + overflow-x: hidden; + width: 100%; + color: ${designSystem.colors.light.textPrimary}; + :hover { + color: ${designSystem.colors.light.linkNavigation}; + } +`; const LinkSubtitle = styled.div` font-size: ${designSystem.typography.fontSizes.small}; text-overflow: ellipsis; @@ -96,8 +106,16 @@ const LinkItem = styled.div` align-items: flex-end; vertical-align: middle; `; + +// TODO: cleanup. After docs websites migrate to clickable chapter, this component +// can be simplified/removed or refactored since is currently supporting both clickable +// and non-clickable configs const LinkItemWithIcon = styled.div` - padding: 0 0 0 ${designSystem.dimensions.spacings.m}; + ${(props) => + !props.clickable && + ` + padding: 0 0 0 ${designSystem.dimensions.spacings.m}; + `} display: flex; flex-direction: row; vertical-align: middle; @@ -278,10 +296,42 @@ const SidebarChapter = (props) => { [elemId] ); + // TODO: cleanup. After docs websites migrate to clickable chapter, this component + // can be simplified/removed or refactored since is currently supporting both clickable + // and non-clickable configs return (
- {courseId ? ( + {props.chapter.path ? ( + div { + color: ${designSystem.colors.light.linkNavigation} !important; + } + `} + > + {courseId ? ( + + + + {props.chapter.chapterTitle} + + + ) : ( + {props.chapter.chapterTitle} + )} + + ) : courseId ? ( {props.chapter.chapterTitle} @@ -333,6 +383,7 @@ SidebarChapter.propTypes = { index: PropTypes.number.isRequired, chapter: PropTypes.shape({ chapterTitle: PropTypes.string.isRequired, + path: PropTypes.string, beta: PropTypes.bool, pages: PropTypes.arrayOf( PropTypes.shape({ @@ -358,6 +409,7 @@ const SidebarNavigationLinks = (props) => { allNavigationYaml { nodes { chapterTitle + path pages { title path diff --git a/websites/api-docs-smoke-test/src/content/docs-replications/overview.mdx b/websites/api-docs-smoke-test/src/content/docs-replications/overview.mdx new file mode 100644 index 0000000000..10d91b418d --- /dev/null +++ b/websites/api-docs-smoke-test/src/content/docs-replications/overview.mdx @@ -0,0 +1,9 @@ +--- +title: Docs Replications +showTimeToRead: false +timeToRead: false +--- + +# Contents of this chapter + +- [Long Page with Many Types](/docs-replications/long-page) diff --git a/websites/api-docs-smoke-test/src/content/e2e-tests/overview.mdx b/websites/api-docs-smoke-test/src/content/e2e-tests/overview.mdx new file mode 100644 index 0000000000..f5976e3d4a --- /dev/null +++ b/websites/api-docs-smoke-test/src/content/e2e-tests/overview.mdx @@ -0,0 +1,10 @@ +--- +title: E2E Tests +showTimeToRead: false +timeToRead: false +--- + +# Contents of this chapter + +- [Soft Linking First Page](/e2e-tests/soft-linking-first-page) +- [Soft Linking Second Page](/e2e-tests/soft-linking-second-page) diff --git a/websites/api-docs-smoke-test/src/content/endpoints/overview.mdx b/websites/api-docs-smoke-test/src/content/endpoints/overview.mdx new file mode 100644 index 0000000000..d44e5ec5b5 --- /dev/null +++ b/websites/api-docs-smoke-test/src/content/endpoints/overview.mdx @@ -0,0 +1,10 @@ +--- +title: Endpoints +showTimeToRead: false +timeToRead: false +--- + +# Contents of this chapter + +- [Methods](/endpoints/methods) +- [All Endpoints of Resource](/endpoints/endpoints-for-resource) diff --git a/websites/api-docs-smoke-test/src/content/layouts/overview.mdx b/websites/api-docs-smoke-test/src/content/layouts/overview.mdx new file mode 100644 index 0000000000..194f575e57 --- /dev/null +++ b/websites/api-docs-smoke-test/src/content/layouts/overview.mdx @@ -0,0 +1,12 @@ +--- +title: Layouts +showTimeToRead: false +timeToRead: false +--- + +# Contents of this chapter + +- [API Type Large Desktop](/layouts/type-large-desktop) +- [API Type Regular Desktop](/layouts/type-regular-desktop) +- [API Endpoint Large Desktop](/layouts/endpoint-large-desktop) +- [API Endpoint Regular Desktop](/layouts/endpoint-regular-desktop) diff --git a/websites/api-docs-smoke-test/src/content/types/overview.mdx b/websites/api-docs-smoke-test/src/content/types/overview.mdx new file mode 100644 index 0000000000..a42b8cbe58 --- /dev/null +++ b/websites/api-docs-smoke-test/src/content/types/overview.mdx @@ -0,0 +1,12 @@ +--- +title: Types +showTimeToRead: false +timeToRead: false +--- + +# Contents of this chapter + +- [General](/types/general) +- [Scalars](/types/scalars) +- [Examples](/types/examples) +- [Enums, Constants & Unions](/types/enums-constants-unions) diff --git a/websites/api-docs-smoke-test/src/data/navigation.yaml b/websites/api-docs-smoke-test/src/data/navigation.yaml index 2094a8cc87..bde02eca2e 100644 --- a/websites/api-docs-smoke-test/src/data/navigation.yaml +++ b/websites/api-docs-smoke-test/src/data/navigation.yaml @@ -1,4 +1,5 @@ - chapter-title: Layouts + path: /layouts/overview pages: - title: API Type Large Desktop path: /layouts/type-large-desktop @@ -9,6 +10,7 @@ - title: API Endpoint Regular Desktop path: /layouts/endpoint-regular-desktop - chapter-title: Types + path: /types/overview pages: - title: General path: /types/general @@ -19,18 +21,21 @@ - title: Enums, Constants & Unions path: /types/enums-constants-unions - chapter-title: Endpoints + path: /endpoints/overview pages: - title: Methods path: /endpoints/methods - title: All Endpoints of Resource path: /endpoints/endpoints-for-resource - chapter-title: E2E Tests + path: /e2e-tests/overview pages: - title: Soft Linking First Page path: /e2e-tests/soft-linking-first-page - title: Soft Linking Second Page path: /e2e-tests/soft-linking-second-page - chapter-title: Docs Replications + path: /docs-replications/overview pages: - title: Long Page with Many Types path: /docs-replications/long-page diff --git a/websites/docs-smoke-test/src/content/components/overview.mdx b/websites/docs-smoke-test/src/content/components/overview.mdx new file mode 100644 index 0000000000..b058c498d5 --- /dev/null +++ b/websites/docs-smoke-test/src/content/components/overview.mdx @@ -0,0 +1,17 @@ +--- +title: Components +showTimeToRead: false +timeToRead: false +--- + +# Contents of this chapter + +- [Code blocks](/components/code-blocks) +- [Code Examples](/components/code-examples) +- [Content notifications](/components/content-notifications) +- [Images](/components/images) +- [Cards](/components/cards) +- [RSS Feeds](/components/rss-feeds) +- [Child section navigation](/components/child-section-navigation) +- [Mermaid Diagrams](/components/mermaid-diagram) +- [Video Player](/components/video-player) diff --git a/websites/docs-smoke-test/src/content/empty-pages/overview-1.mdx b/websites/docs-smoke-test/src/content/empty-pages/overview-1.mdx new file mode 100644 index 0000000000..d8b6ffc819 --- /dev/null +++ b/websites/docs-smoke-test/src/content/empty-pages/overview-1.mdx @@ -0,0 +1,10 @@ +--- +title: Empty pages +showTimeToRead: false +timeToRead: false +--- + +# Contents of this chapter + +- [PageWithLongNameThatOverflowsBecauseItsOneWord](/empty-pages/empty-page-three) +- [BetaPageWithLongNameThatOverflowsBecauseItsOneWord](/empty-pages/empty-page-four) diff --git a/websites/docs-smoke-test/src/content/empty-pages/overview.mdx b/websites/docs-smoke-test/src/content/empty-pages/overview.mdx new file mode 100644 index 0000000000..20dd0b9703 --- /dev/null +++ b/websites/docs-smoke-test/src/content/empty-pages/overview.mdx @@ -0,0 +1,10 @@ +--- +title: Empty pages +showTimeToRead: false +timeToRead: false +--- + +# Contents of this chapter + +- [Page with some very long title too much for our innocent API to handle](/empty-pages/empty-page-one) +- [Beta Page with some very long title too much for our innocent API to handle](/empty-pages/empty-page-two) diff --git a/websites/docs-smoke-test/src/content/views/overview.mdx b/websites/docs-smoke-test/src/content/views/overview.mdx new file mode 100644 index 0000000000..98a09421cc --- /dev/null +++ b/websites/docs-smoke-test/src/content/views/overview.mdx @@ -0,0 +1,18 @@ +--- +title: Views +showTimeToRead: false +timeToRead: false +--- + +# Contents of this chapter + +- [Markdown](/views/markdown) +- [Empty](/views/empty) +- [Beta with long page title to see how the index nav behaves](/views/beta) +- [Nested headings](/views/nested-headings) +- [Two-level nav](/views/two-level-index-nav) +- [Links](/views/links) +- [Code blocks](/views/code-blocks) +- [Code examples](/views/code-examples) +- [Custom Anchor](/views/custom-anchor) +- [Wide Layout](/views/wide) diff --git a/websites/docs-smoke-test/src/data/navigation.yaml b/websites/docs-smoke-test/src/data/navigation.yaml index 410cc89b3a..9b39b1d65b 100644 --- a/websites/docs-smoke-test/src/data/navigation.yaml +++ b/websites/docs-smoke-test/src/data/navigation.yaml @@ -1,4 +1,5 @@ - chapter-title: Views + path: /views/overview pages: - title: Markdown path: /views/markdown @@ -21,6 +22,7 @@ - title: Wide Layout path: /views/wide - chapter-title: Components + path: /components/overview beta: true pages: - title: Code blocks @@ -42,6 +44,7 @@ - title: Video Player path: /components/video-player - chapter-title: Chapter 9999 With a Longer Multi-Word Name that Wraps + path: /empty-pages/overview pages: - title: Page with some very long title too much for our innocent API to handle path: /empty-pages/empty-page-one @@ -49,6 +52,7 @@ path: /empty-pages/empty-page-two beta: true - chapter-title: ChapterWithLongNameThatOverflowsBecauseItsOneWord + path: /empty-pages/overview-1 pages: - title: PageWithLongNameThatOverflowsBecauseItsOneWord path: /empty-pages/empty-page-three diff --git a/websites/documentation/src/content/api-docs/overview.mdx b/websites/documentation/src/content/api-docs/overview.mdx new file mode 100644 index 0000000000..6fd70bc29a --- /dev/null +++ b/websites/documentation/src/content/api-docs/overview.mdx @@ -0,0 +1,12 @@ +--- +title: Creating API Documentation +showTimeToRead: false +timeToRead: false +--- + +# Contents of this chapter + +- [Add RAML Specs](/api-docs/raml) +- [API Endpoints](/api-docs/endpoints) +- [API Data Types](/api-docs/types) +- [Examples](/api-docs/examples) diff --git a/websites/documentation/src/content/configuration/overview.mdx b/websites/documentation/src/content/configuration/overview.mdx new file mode 100644 index 0000000000..f74ddc7c31 --- /dev/null +++ b/websites/documentation/src/content/configuration/overview.mdx @@ -0,0 +1,18 @@ +--- +title: Configuration +showTimeToRead: false +timeToRead: false +--- + +# Contents of this chapter + +- [Theme Configuration](/configuration/theme) +- [Theme Extensions](/configuration/extensions) +- [Plugins](/configuration/plugins) +- [Packages](/configuration/packages) +- [Custom Components](/configuration/components) +- [Override Components](/configuration/overrides) +- [API Documentation](/configuration/api) +- [RSS](/configuration/rss) +- [Deploy](/configuration/deploy) +- [Troubleshooting](/configuration/troubleshooting) diff --git a/websites/documentation/src/content/developing/overview.mdx b/websites/documentation/src/content/developing/overview.mdx new file mode 100644 index 0000000000..e97f913a87 --- /dev/null +++ b/websites/documentation/src/content/developing/overview.mdx @@ -0,0 +1,13 @@ +--- +title: Developing +showTimeToRead: false +timeToRead: false +--- + +# Contents of this chapter + +- [Get Started Developing](/developing/getting-started) +- [Write an extension](/developing/extensions) +- [Contributing](/developing/contributing) +- [Code of Conduct](/developing/code-of-conduct) +- [Tests](/developing/tests) diff --git a/websites/documentation/src/content/getting-started/overview.mdx b/websites/documentation/src/content/getting-started/overview.mdx new file mode 100644 index 0000000000..dc4dd218d7 --- /dev/null +++ b/websites/documentation/src/content/getting-started/overview.mdx @@ -0,0 +1,10 @@ +--- +title: Getting Started +showTimeToRead: false +timeToRead: false +--- + +# Contents of this chapter + +- [Install a site](/getting-started/setup) +- [Troubleshooting](/getting-started/troubleshooting) diff --git a/websites/documentation/src/content/writing/overview.mdx b/websites/documentation/src/content/writing/overview.mdx new file mode 100644 index 0000000000..420a17d24b --- /dev/null +++ b/websites/documentation/src/content/writing/overview.mdx @@ -0,0 +1,19 @@ +--- +title: Writing Content +showTimeToRead: false +timeToRead: false +--- + +# Contents of this chapter + +- [Pages](/writing/pages) +- [Markdown & MDX](/writing/markdown) +- [Embedding Media](/writing/images) +- [Navigation](/writing/navigation) +- [Code](/writing/code) +- [Reusable content fragments](/writing/import-content) +- [Release notes](/writing/release-notes) +- [Data constants](/writing/constants) +- [Sample Page](/writing/sample) +- [Self-learning](/writing/self-learning) +- [SSO](/writing/sso) diff --git a/websites/documentation/src/data/navigation.yaml b/websites/documentation/src/data/navigation.yaml index db03b66cb8..e4d34b3a05 100644 --- a/websites/documentation/src/data/navigation.yaml +++ b/websites/documentation/src/data/navigation.yaml @@ -1,10 +1,12 @@ - chapter-title: Getting Started + path: /getting-started/overview pages: - title: Install a site # prerequisites, checking out a repo, VSCode workspace, yarn install path: /getting-started/setup - title: Troubleshooting path: /getting-started/troubleshooting - chapter-title: Writing Content + path: /writing/overview pages: - title: Pages # filesystem convention, frontmatter, wide layouts path: /writing/pages @@ -32,6 +34,7 @@ - title: SSO path: /writing/sso - chapter-title: Creating API Documentation + path: /api-docs/overview pages: - title: Add RAML Specs # rmf-codegen/RAMLDOC, filesystem convention, links to specs and resourcess path: /api-docs/raml @@ -42,6 +45,7 @@ - title: Examples # examples in JSON files, example validation, multiple named examples path: /api-docs/examples - chapter-title: Configuration + path: /configuration/overview pages: - title: Theme Configuration path: /configuration/theme @@ -64,6 +68,7 @@ - title: Troubleshooting path: /configuration/troubleshooting - chapter-title: Developing + path: /developing/overview pages: - title: Get Started Developing path: /developing/getting-started diff --git a/websites/self-learning-smoke-test/src/data/navigation.yaml b/websites/self-learning-smoke-test/src/data/navigation.yaml index 19eb46fc1a..430fd5814c 100644 --- a/websites/self-learning-smoke-test/src/data/navigation.yaml +++ b/websites/self-learning-smoke-test/src/data/navigation.yaml @@ -1,16 +1,14 @@ - chapter-title: Self-learning course 1 + path: /course-1/overview pages: - - title: Overview - path: /course-1/overview - title: Test your knowledge with long title path: /course-1/quiz - title: Test your knowledge 2 path: /course-1/2-quiz - chapter-title: Self-learning course 2 + path: /course-2/overview pages: - - title: Overview - path: /course-2/overview - title: Test your knowledge with long title path: /course-2/quiz - title: Test your knowledge 2 diff --git a/websites/site-template/src/data/navigation.yaml b/websites/site-template/src/data/navigation.yaml index 214977a776..bd701cee53 100644 --- a/websites/site-template/src/data/navigation.yaml +++ b/websites/site-template/src/data/navigation.yaml @@ -1,4 +1,5 @@ - chapter-title: CHANGE-ME + path: / pages: - title: CHANGE-ME path: /