feat(theme): implement release notes page layout #336

emmenko · 2020-04-02T12:24:58Z

This PR implements the page layout structure for the release note pages. The layout is the same as for the content pages, except for the absence of the site navigation and the page filters (to be done separately).

This does not implement the designs of the release notes, only the layout.

vercel · 2020-04-02T12:25:02Z

This pull request is being automatically deployed with ZEIT Now (learn more).
To see the status of your deployment, click below or on the icon next to each commit.

🔍 Inspect: https://zeit.co/commercetools/commercetools-docs-kit/jqmw4sld4
✅ Preview: https://commercetools-docs-kit-git-nm-theme-release-notes-layout.commercetools.now.sh

emmenko · 2020-04-03T19:26:33Z

packages/gatsby-theme-docs/gatsby-config.js

@@ -19,6 +19,7 @@ const defaultOptions = {
  beta: false,
  gaTrackingId: undefined,
  excludeFromSearchIndex: true,
+  hasReleaseNotes: false,


The link to the release notes is toggled by this config flag.

emmenko · 2020-04-03T19:27:10Z

packages/gatsby-theme-docs/gatsby-node.js

+    node,
+    name: 'isGlobalBeta',
+    value: Boolean(pluginOptions.beta),
+  });


There are used by all templates, because of the sidebar. Therefore we always generate those fields.

emmenko · 2020-04-03T19:28:15Z

packages/gatsby-theme-docs/gatsby-node.js

+    fragment MdxPageFields on MdxFields {
+      slug
+      title
+      beta
+      isGlobalBeta
+      excludeFromSearchIndex
+      hasReleaseNotes
+    }


These fields are shared by all pages. Extra fields (for example for the release notes) should be listed in the specific query.

emmenko · 2020-04-03T19:29:35Z

packages/gatsby-theme-docs/gatsby-node.js

+      component: isOverviewPage
+        ? require.resolve('./src/templates/release-notes-list.js')
+        : require.resolve('./src/templates/release-notes-detail.js'),


After some back and forth I think it's better to just have two separate templates, it makes things easier to implement and separates a bit the concerns, as the pages are indeed different.

emmenko · 2020-04-03T19:30:20Z

packages/gatsby-theme-docs/src/components/release-notes-subscribe-links.js

@@ -0,0 +1,5 @@
+import React from 'react';
+
+const ReleaseNotesSubscribeLinks = () => <div>{'TODO subscribe links'}</div>;


Here we will add the "subscribe" links (rss feed, etc.). To be done in a separate PR.

emmenko · 2020-04-03T19:30:52Z

packages/gatsby-theme-docs/src/hooks/use-layout-state.js

@@ -0,0 +1,51 @@
+import React from 'react';
+
+const useLayoutState = () => {


I moved all this state into a hook, to make is easier to reuse across the different layout components.

emmenko · 2020-04-03T19:33:02Z

packages/gatsby-theme-docs/src/layouts/internals/layout-header-logo.js

+const LayoutHeaderLogo = () => (
+  <Container>
+    <LogoButton />
+  </Container>
+);


Just extracted for better reusability

emmenko · 2020-04-03T19:33:29Z

packages/gatsby-theme-docs/src/layouts/internals/layout-page-release-notes-filters.js

+
+const LayoutPageReleaseNotesFilters = () => (
+  <GridContainer>
+    <StickyContainer>{'TODO: filters'}</StickyContainer>


Here is where the filters will be implemented. To be done in a separate PR.

emmenko · 2020-04-03T19:34:37Z

packages/gatsby-theme-docs/src/layouts/internals/sidebar.js

+const linkStyles = `
+  border-left: ${designSystem.dimensions.spacings.xs} solid ${designSystem.colors.light.surfaceSecondary1};
+  padding-left: calc(${designSystem.dimensions.spacings.m} - ${designSystem.dimensions.spacings.xs});
+  text-decoration: none;
+  color: ${designSystem.colors.light.textSecondary};
+  display: flex;
+  flex-direction: row;
+  align-items: flex-end;
+
+  :hover {
+    color: ${designSystem.colors.light.linkNavigation} !important;
+  }
+
+  > * + * {
+    margin: 0 0 0 ${designSystem.dimensions.spacings.s};
+  }
+`;
+const activeLinkStyles = `
+  border-left: ${designSystem.dimensions.spacings.xs} solid ${designSystem.colors.light.linkNavigation} !important;
+  color: ${designSystem.colors.light.linkNavigation} !important;
+`;


Extracted into variables for better readability

emmenko · 2020-04-03T19:35:26Z

packages/gatsby-theme-docs/src/layouts/internals/sidebar.js

+    customStyles,
+    customActiveStyles,


These two props are new, to allow to override some of the link styles.

emmenko · 2020-04-03T19:36:21Z

packages/gatsby-theme-docs/src/layouts/internals/sidebar.js

+  customActiveStyles: PropTypes.string,
+};
+
+const SidebarLinkWrapper = (props) => {


I split the SidebarLink component into two, with the wrapper containing the logic for the scrolling position.

The base link component is use for the release notes link.

emmenko · 2020-04-03T19:37:32Z

packages/gatsby-theme-docs/src/layouts/internals/sidebar.js

 };

-const Sidebar = (props) => {
+const SidebarNavigationLinks = (props) => {


This component is also extracted and contains the normal navigation links.

emmenko · 2020-04-03T19:37:58Z

packages/gatsby-theme-docs/src/layouts/internals/sidebar.js

+      {props.hasReleaseNotes && (
+        <ReleaseNotesTitle>
+          <SidebarLink
+            to="/releases"


This is the link to the release notes.

emmenko · 2020-04-03T19:38:53Z

packages/gatsby-theme-docs/src/layouts/internals/sidebar.js

+          </SidebarLink>
+        </ReleaseNotesTitle>
+      )}
+      {props.hasReleaseNotes && isReleasePage ? (


If this condition is true, we render the "back" link

emmenko · 2020-04-03T19:39:32Z

packages/gatsby-theme-docs/src/layouts/release-notes-detail.js

+            <SpacingsInline alignItems="center">
+              <AngleLeftIcon size="medium" color="primary" />
+              <Link href="/releases" noUnderline={true}>
+                <span
+                  css={css`
+                    font-size: ${designSystem.typography.fontSizes.small};
+                  `}
+                >
+                  {'Back to all releases'}
+                </span>
+              </Link>
+            </SpacingsInline>


The detail page has this "back" link at the top

emmenko · 2020-04-03T20:11:15Z

packages/gatsby-theme-docs/src/templates/release-notes-detail.js

+  // NOTE: release notes content can only have headings starting from h4.
+  h1: Markdown.withAnchorLink(Markdown.H4),
+  h2: Markdown.withAnchorLink(Markdown.H5),
+  h3: Markdown.withAnchorLink(Markdown.H6),
+  h4: Markdown.withAnchorLink(Markdown.H6),


This is the mapped list of headings for the release notes content.

cc @nkuehn

I think we ended up saying that release notes should not have any headings but I think it's a good idea to treat that decision as a technical writing / lectoring convention but have the implementation still render them as a lower "level". You never know what comes up in the future.

H4 is correct to start with since we skip H2 in that page layout.

emmenko · 2020-04-07T20:07:00Z

packages/gatsby-theme-docs/gatsby-node.js

-          internal: { mediaType: { eq: "text/mdx" } }
-        }
-      ) {
+      allContentPage {


We now have our own custom query fields.

emmenko · 2020-04-07T20:08:27Z

packages/gatsby-theme-docs/gatsby-node.js

+      allReleaseNotePage {
+        totalCount
+      }


We can use this to determine if there are any release notes in the website.

We can then be more specific and define some filters to which release notes we want to include. For example, we can exclude all the ones that are not marked as published.

emmenko · 2020-04-07T20:10:38Z

packages/gatsby-theme-docs/gatsby-node.js

-      // You can use the values in this context in
-      // our page layout component
+      component: isOverviewPage
+        ? require.resolve('./src/templates/release-notes-list.js')


The release overview page needs to be rendered here now. It still has its own template but from a graphql type perspective is considered a "content page" and therefore is queried with all other content pages.

The file is now src/content/releases.mdx instead of src/releases/index.mdx, for the reasons mentioned above.

…ease note pages

emmenko · 2020-04-07T20:13:37Z

packages/gatsby-theme-docs/src/templates/page-content.js

+    contentPage(slug: { eq: $slug }) {
+      title
+      beta
+      isGlobalBeta
+      excludeFromSearchIndex


Those fields should be queried here, we don't need to pass them with the page context.
Also note the we are using the contentPage query field.

emmenko · 2020-04-07T20:14:04Z

packages/gatsby-theme-docs/src/templates/release-notes-detail.js

+      title
+      isGlobalBeta
+      excludeFromSearchIndex
+      date(formatString: "YYYY-MM-DD")


We can format the date here.

emmenko · 2020-04-07T20:14:38Z

packages/gatsby-theme-docs/src/templates/release-notes-list.js

+    allReleaseNotePage(sort: { order: DESC, fields: date }) {
+      nodes {
+        slug
+        title
+        date(formatString: "YYYY-MM-DD")
+        description
+        type
+        topics
+        body
+      }
+    }


Here we query all release notes and sort them by date descending.

nkuehn

Thank you! It's definitely the best way to directly switch to using a fully custom graphQL API surface. It matches the experiences we made in building the API types stuff. Plus I really really like the look of the left menu now that it's even cleaner.

!! One bug remains when opening a build (not development): The main nav link to the release notes has a flash of unstyled content (it moves from right to left).

To not block this another full day I leave this here as an approval, please manage yourself whether to directly fix it or to open a separate issue to track it.

emmenko · 2020-04-07T20:41:05Z

packages/gatsby-theme-api-docs/src/hooks/use-type-locations.js

+              parent {
+                id
+                ... on File {
+                  relativePath
+                  ext
+                }


This is now necessary because the slug is not created as a MDX field anymore.

emmenko · 2020-04-08T07:43:33Z

@nkuehn the FOUC bug is fixed now, I'll merge the PR once CI passes.

emmenko requested review from davifantasia, nkuehn and Shecki April 2, 2020 12:25

emmenko added the 🚀 Type: New Feature Something new label Apr 2, 2020

vercel bot temporarily deployed to Preview April 2, 2020 12:52 Inactive

This comment has been minimized.

Sign in to view

vercel bot temporarily deployed to Preview April 2, 2020 13:35 Inactive

vercel bot temporarily deployed to Preview April 2, 2020 13:51 Inactive

emmenko force-pushed the nm-theme-release-notes-layout branch from 5bd4ad4 to ccb1cbb Compare April 3, 2020 19:22

vercel bot temporarily deployed to Preview April 3, 2020 19:22 Inactive

vercel bot temporarily deployed to Preview April 3, 2020 19:26 Inactive

emmenko commented Apr 3, 2020

View reviewed changes

vercel bot temporarily deployed to Preview April 3, 2020 19:46 Inactive

vercel bot temporarily deployed to Preview April 3, 2020 20:10 Inactive

emmenko commented Apr 3, 2020

View reviewed changes

vercel bot had a problem deploying to Preview April 7, 2020 19:51 Failure

emmenko requested review from nkuehn and davifantasia April 7, 2020 19:53

emmenko force-pushed the nm-theme-release-notes-layout branch from 5ba7b73 to b4e6927 Compare April 7, 2020 20:01

vercel bot had a problem deploying to Preview April 7, 2020 20:02 Failure

emmenko force-pushed the nm-theme-release-notes-layout branch from b4e6927 to 4a08d4d Compare April 7, 2020 20:06

vercel bot had a problem deploying to Preview April 7, 2020 20:06 Failure

emmenko commented Apr 7, 2020

View reviewed changes

refactor(theme): define new schema and node types for content and rel…

7861024

…ease note pages

emmenko force-pushed the nm-theme-release-notes-layout branch from 4a08d4d to 7861024 Compare April 7, 2020 20:11

vercel bot had a problem deploying to Preview April 7, 2020 20:11 Failure

emmenko commented Apr 7, 2020

View reviewed changes

vercel bot temporarily deployed to Preview April 7, 2020 20:36 Inactive

nkuehn approved these changes Apr 7, 2020

View reviewed changes

fix(api-theme): typeLocations query for getting page slug

1d8d0b5

emmenko force-pushed the nm-theme-release-notes-layout branch from d41ccf9 to 1d8d0b5 Compare April 7, 2020 20:39

vercel bot had a problem deploying to Preview April 7, 2020 20:39 Failure

emmenko commented Apr 7, 2020

View reviewed changes

fix(theme): safe guard if date field is not inferred

30d943f

vercel bot temporarily deployed to Preview April 7, 2020 20:48 Inactive

fix(theme): try to fix FOUC for release notes link

715195e

vercel bot temporarily deployed to Preview April 8, 2020 07:36 Inactive

emmenko merged commit d4a86bc into master Apr 8, 2020

emmenko deleted the nm-theme-release-notes-layout branch April 8, 2020 07:55

emmenko mentioned this pull request Apr 8, 2020

fix: leftovers of release notes layout implementation #350

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(theme): implement release notes page layout #336

feat(theme): implement release notes page layout #336

emmenko commented Apr 2, 2020 •

edited

Loading

vercel bot commented Apr 2, 2020 •

edited

Loading

This comment has been minimized.

emmenko Apr 3, 2020

emmenko Apr 3, 2020

emmenko Apr 3, 2020

emmenko Apr 3, 2020

emmenko Apr 3, 2020

emmenko Apr 3, 2020

emmenko Apr 3, 2020

emmenko Apr 3, 2020

emmenko Apr 3, 2020

emmenko Apr 3, 2020

emmenko Apr 3, 2020

emmenko Apr 3, 2020

emmenko Apr 3, 2020

emmenko Apr 3, 2020

emmenko Apr 3, 2020

emmenko Apr 3, 2020

nkuehn Apr 6, 2020

emmenko Apr 7, 2020

emmenko Apr 7, 2020

emmenko Apr 7, 2020

emmenko Apr 7, 2020

emmenko Apr 7, 2020

emmenko Apr 7, 2020

nkuehn left a comment

emmenko Apr 7, 2020

emmenko commented Apr 8, 2020

		@@ -0,0 +1,5 @@
		import React from 'react';

		const ReleaseNotesSubscribeLinks = () => <div>{'TODO subscribe links'}</div>;

		@@ -0,0 +1,51 @@
		import React from 'react';

		const useLayoutState = () => {

feat(theme): implement release notes page layout #336

feat(theme): implement release notes page layout #336

Conversation

emmenko commented Apr 2, 2020 • edited Loading

vercel bot commented Apr 2, 2020 • edited Loading

This comment has been minimized.

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nkuehn left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

emmenko commented Apr 8, 2020

emmenko commented Apr 2, 2020 •

edited

Loading

vercel bot commented Apr 2, 2020 •

edited

Loading