feat HDS 2352 enable versioned documentation

CHANGELOG.md

@@ -125,6 +125,7 @@ Changes that are not related to specific components
 
 #### Added
 
+- Documentation of older versions (3.11 & 2.17) of HDS is also available on the documentation site.
 - [StatusLabel] Documentation about SCSS usage.
 - [Breadcrumbs] Documentation about SCSS usage.
 - [Checkbox] Documentation about SCSS usage.

packages/react/src/components/header/Header.stories.tsx

@@ -761,3 +761,38 @@ export const WithUserMenu = (args: HeaderProps) => {
     </>
   );
 };
+
+export const WithCustomMenu = (args: HeaderProps) => {
+  const lang = 'fi';
+  const I18n = translations[lang];
+  const versions = ['Version 4.0.0', 'Version 3.11.0', 'Version 2.17.1'];
+  const selectedVersion = 'Version 3.11.0';
+
+  return (
+    <>
+      <Header {...args}>
+        <Header.SkipLink skipTo="#content" label={I18n.skipToContent} />
+        <Header.ActionBar
+          frontPageLabel={I18n.frontPage}
+          title={translations[lang].headerTitle}
+          titleAriaLabel={translations[lang].headerAriaLabel}
+          titleHref="https://hel.fi"
+          logo={
+            <Logo
+              src={logoSrcFromLanguageAndTheme(lang, args.theme as HeaderTheme)}
+              alt={translations[lang].headerTitle}
+            />
+          }
+          logoAriaLabel={I18n.ariaLogo}
+        >
+          <Header.ActionBarItem id="VersionMenu" label={selectedVersion} fixedRightPosition>
+            {versions.map((version) => (
+              <Header.ActionBarSubItem label={version} selected={version === selectedVersion} href="/" />
+            ))}
+          </Header.ActionBarItem>
+        </Header.ActionBar>
+      </Header>
+      <div id="content" />
+    </>
+  );
+};

packages/react/src/components/header/components/headerActionBarItem/HeaderActionBarItem.module.scss

@@ -151,6 +151,10 @@
     & > h4 {
       padding: 0 !important;
     }
+
+    &.selected {
+      border-left: 4px solid var(--color-black);
+    }
   }
 
   & .dropdownItem button {

packages/react/src/components/header/components/headerActionBarItem/HeaderActionBarItem.tsx

@@ -141,6 +141,7 @@ export const HeaderActionBarItem = (properties: HeaderActionBarItemProps) => {
           activeStateLabel: closeLabel,
         }
       : {};
+  const heading = visible && !fullWidth && label && avatar;
 
   /* eslint-disable jsx-a11y/no-noninteractive-tabindex */
   return (
@@ -165,7 +166,7 @@ export const HeaderActionBarItem = (properties: HeaderActionBarItemProps) => {
       {hasSubItems && (
         <div className={classes.dropdownWrapper}>
           <div id={`${id}-dropdown`} className={dropdownClassName} ref={dropdownContentElementRef}>
-            {visible && !fullWidth && label && <h3>{label}</h3>}
+            {heading && <h3>{label}</h3>}
             <ul>{children}</ul>
           </div>
         </div>

packages/react/src/components/header/components/headerActionBarSubItem/HeaderActionBarSubItem.module.scss

@@ -24,6 +24,10 @@ h4.actionBarSubItem {
     font-weight: bold;
   }
 
+  &.selected {
+    text-decoration: underline;
+  }
+
   &:focus-visible {
     border: none;
     outline: 0;

packages/react/src/components/header/components/headerActionBarSubItem/HeaderActionBarSubItem.tsx

@@ -47,6 +47,10 @@ export interface HeaderActionBarSubItemProps extends ElementProps {
    * If bold
    */
   bold?: boolean;
+  /**
+   * If selected
+   */
+  selected?: boolean;
   /**
    * Hypertext Reference of the link.
    */
@@ -75,6 +79,7 @@ export const HeaderActionBarSubItem = forwardRef<HTMLButtonElement | HTMLAnchorE
       onClick,
       className,
       bold,
+      selected,
       external,
       openInExternalDomainAriaLabel,
       ...rest
@@ -85,6 +90,7 @@ export const HeaderActionBarSubItem = forwardRef<HTMLButtonElement | HTMLAnchorE
       [classes.actionBarSubItem]: true,
       ...(className && { [className]: true }),
       [classes.bold]: bold,
+      [classes.selected]: selected,
     });
 
     const composeAriaLabel = () => {
@@ -151,7 +157,14 @@ export const HeaderActionBarSubItem = forwardRef<HTMLButtonElement | HTMLAnchorE
         return isHeading ? (
           <h4 className={itemClassName}>{children}</h4>
         ) : (
-          <li className={actionBarItemClasses.dropdownItem}>{children}</li>
+          <li
+            className={classNames({
+              [actionBarItemClasses.dropdownItem]: true,
+              [actionBarItemClasses.selected]: selected,
+            })}
+          >
+            {children}
+          </li>
         );
       },
       [isHeading, itemClassName],

site/gatsby-browser.js

@@ -9,6 +9,6 @@ const Layout = require('./src/components/layout').default;
 
 // Wraps every page in a component
 exports.wrapPageElement = ({ element, props }) => {
-  if (props.location.pathname.includes("this-is-hds")) return <React.Fragment {...props}>{element}</React.Fragment>
+  if (props.location.pathname.includes('this-is-hds')) return <React.Fragment {...props}>{element}</React.Fragment>;
   return <Layout {...props}>{element}</Layout>;
 };

site/gatsby-config.js

@@ -1,6 +1,17 @@
 require("dotenv").config({
   path: `.env.${process.env.NODE_ENV}`,
 })
+const latestVersion = process.env.npm_package_version;
+const versionsFromGit = require('./src/data/versions.json').filter(v => v !== latestVersion);
+const gitSources = versionsFromGit.map(version => ({
+  resolve: 'gatsby-source-git',
+  options: {
+    name: `docs-release-${version}`,
+    remote: `https://github.com/City-of-Helsinki/helsinki-design-system`,
+    branch: `release-${version}`,
+    patterns: 'site/src/docs/**',
+  },
+}));
 
 module.exports = {
   pathPrefix: process.env.PATH_PREFIX,
@@ -147,16 +158,10 @@ module.exports = {
       resolve: `gatsby-source-filesystem`,
       options: {
         name: `docs`,
-        path: `${__dirname}/src/docs/`,
-      },
-    },
-    // This config is needed when pages are somewhere else than in the pages folder.
-    {
-      resolve: 'gatsby-plugin-page-creator',
-      options: {
         path: `${__dirname}/src/docs`,
       },
     },
+    ...gitSources,
     {
       resolve: `gatsby-plugin-mdx`,
       options: {

site/gatsby-node.js

@@ -1,23 +1,121 @@
 const webpack = require('webpack');
 const path = require('path');
 
-exports.onCreateWebpackConfig = ({ actions }) => {
+exports.onCreateWebpackConfig = ({ actions, getConfig }) => {
+  const config = getConfig();
+
+  config.plugins.push(
+    new webpack.NormalModuleReplacementPlugin(
+      /hds-core|hds-react/,
+      resource => {
+        if (resource.context.includes('.cache/gatsby-source-git/docs-release-2.17.1/site')) {
+          resource.request = resource.request.replace('hds-core', 'hds-2-core');
+          resource.request = resource.request.replace('hds-react', 'hds-2-react');
+        }
+        if (resource.context.includes('.cache/gatsby-source-git/docs-release-3.11.0/site')) {
+          resource.request = resource.request.replace('hds-core', 'hds-3-core');
+          resource.request = resource.request.replace('hds-react', 'hds-3-react');
+        }
+      }
+    )
+  );
+
   actions.setWebpackConfig({
     plugins: [
       // We need to provide a polyfill for react-live library to make it work with the latest Gatsby: https://webpack.js.org/blog/2020-10-10-webpack-5-release/#automatic-nodejs-polyfills-removed
       new webpack.ProvidePlugin({
         process: 'process/browser',
       }),
+      ...config.plugins,
     ],
     resolve: {
       alias: {
         fs$: path.resolve(__dirname, 'src/fs.js'),
+        '~hds-core': 'hds-2-core',
         'hds-react': 'hds-react/lib',
         stream: false,
       },
       fallback: {
         crypto: require.resolve('crypto-browserify'),
       },
     },
+    /*
+    optimization: {
+      splitChunks: {
+        chunks: 'initial',
+        minChunks: 2,
+        minSize: 10000000,
+        maxSize: 0,
+        cacheGroups: {
+          default: false,
+          vendors: false,
+        },
+      },
+    },
+    */
+  });
+};
+
+exports.createPages = async ({ actions, graphql }) => {
+  const { createPage } = actions;
+
+  // GraphQL query to fetch frontmatter and rendered MDX content
+  const result = await graphql(`
+    query SiteDataQuery {
+      allMdx {
+        edges {
+          node {
+            id
+            frontmatter {
+              title
+              slug
+              navTitle
+              customLayout
+            }
+            parent {
+              ... on File {
+                relativePath
+                gitRemote {
+                  ref
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  `);
+
+  if (result.errors) {
+    console.error(result.errors);
+    throw new Error('Failed to fetch MDX data');
+  }
+
+  // Create pages dynamically
+  result.data.allMdx.edges.forEach(({ node }) => {
+    const gitRemote = node.parent?.gitRemote?.ref;
+    const pathWithVersion = path.join('/', gitRemote || '', node.frontmatter.slug);
+
+    try {
+      const pageTemplate = require.resolve('./src/components/ContentLayoutWrapper.js');
+      const contentPath = './src/docs/' + node.parent.relativePath.replace('site/src/docs/', '');
+
+      console.log('createPage() ' + gitRemote + ' ' + contentPath);
+
+      const pageContent = gitRemote
+        ? require.resolve(`./.cache/gatsby-source-git/docs-${gitRemote}/${node.parent.relativePath}`)
+        : require.resolve(contentPath);
+
+      createPage({
+        component: `${pageTemplate}?__contentFilePath=${pageContent}`,
+        path: pathWithVersion,
+        context: {
+          id: node.id,
+          frontmatter: { ...node.frontmatter, slug: pathWithVersion },
+        },
+      });
+    } catch (e) {
+      console.error(e);
+    }
   });
 };

site/package.json

@@ -2,7 +2,7 @@
   "name": "site",
   "private": true,
   "description": "Documentation for Helsinki Design System",
-  "version": "3.11.0",
+  "version": "4.0.0",
   "workspaces": {
     "nohoist": [
       "gatsby",
@@ -14,22 +14,24 @@
   "dependencies": {
     "@mdx-js/mdx": "2.3.0",
     "@mdx-js/react": "2.3.0",
-    "gatsby": "5.11.0",
-    "gatsby-plugin-image": "^3.0.0",
-    "gatsby-plugin-manifest": "^5.12.0",
-    "gatsby-plugin-matomo": "^0.13.0",
-    "gatsby-plugin-mdx": "5.11.0",
-    "gatsby-plugin-no-sourcemaps": "4.24.0",
-    "gatsby-plugin-offline": "^6.12.0",
-    "gatsby-plugin-react-helmet": "^5.17.0",
-    "gatsby-plugin-robots-txt": "^1.7.1",
-    "gatsby-plugin-sass": "^5.17.0",
-    "gatsby-plugin-sharp": "^5.10.0",
-    "gatsby-remark-autolink-headers": "^5.17.0",
-    "gatsby-source-filesystem": "^4.17.0",
-    "gatsby-transformer-remark": "6.10.0",
-    "gatsby-transformer-sharp": "5.11.0",
+    "gatsby": "5.13.7",
+    "gatsby-plugin-image": "^3.13.1",
+    "gatsby-plugin-manifest": "^5.13.1",
+    "gatsby-plugin-matomo": "^0.16.3",
+    "gatsby-plugin-mdx": "5.13.1",
+    "gatsby-plugin-no-sourcemaps": "5.13.0",
+    "gatsby-plugin-offline": "^6.13.3",
+    "gatsby-plugin-react-helmet": "^6.13.1",
+    "gatsby-plugin-robots-txt": "^1.8.0",
+    "gatsby-plugin-sass": "^6.13.1",
+    "gatsby-plugin-sharp": "^5.13.1",
+    "gatsby-remark-autolink-headers": "^6.13.1",
+    "gatsby-source-filesystem": "^5.13.1",
+    "gatsby-source-git": "2.0.0-beta.0",
+    "gatsby-transformer-remark": "6.13.1",
+    "gatsby-transformer-sharp": "5.13.1",
     "html-validate": "6.5.0",
+    "json5": "^2.2.3",
     "prism-react-renderer": "^1.3.1",
     "process-top": "^1.2.0",
     "prop-types": "^15.8.1",
@@ -39,7 +41,9 @@
     "react-live": "2.4.1",
     "remark-gfm": "^1",
     "sanitize-html": "2.10.0",
-    "sass": "^1.49.9"
+    "sass": "^1.49.9",
+    "body-parser": "1.20.3",
+    "path-to-regexp": "0.1.10"
   },
   "devDependencies": {
     "@babel/core": "^7.0.0",
@@ -53,6 +57,10 @@
     "hds-core": "3.11.0",
     "hds-design-tokens": "3.11.0",
     "hds-react": "3.11.0",
+    "hds-3-core": "npm:[email protected]",
+    "hds-3-react": "npm:[email protected]",
+    "hds-2-core": "npm:[email protected]",
+    "hds-2-react": "npm:[email protected]",
     "inquirer": "7.1.0",
     "postcss": "8",
     "prettier": "2.5.1",

site/src/components/ContentLayoutWrapper.js

@@ -0,0 +1,6 @@
+import React from "react";
+
+export default function ContentLayoutWrapper({ children }) {
+  return (<>{children}</>)
+}
+

site/src/components/LinkboxList.scss

@@ -4,7 +4,7 @@
   column-gap: var(--spacing-layout-xs);
   display: grid;
   grid-template-columns: repeat(auto-fit, minmax(216px, 1fr));
-  margin-top: var(--spacing-layout-m);
+  margin-top: var(--spacing-layout-m) !important;
   row-gap: var(--spacing-layout-xs);
   width: 100%;
 }