@patternfly/documentation-framework 1.0.0

package/scripts/webpack/getHtmlWebpackPlugins.js

@@ -0,0 +1,78 @@
+const path = require('path');
+const HtmlWebpackPlugin = require('html-webpack-plugin');
+const { prerender } = require('./prerender');
+const { getTitle } = require('../../helpers/getTitle');
+
+const templateDir = path.join(__dirname, '../../templates');
+
+async function getHtmlWebpackPlugin({
+  isProd,
+  googleAnalyticsID,
+  algolia,
+  pathPrefix = '',
+  url,
+  title,
+  isFullscreen
+}) {
+  return new HtmlWebpackPlugin({
+    template: path.join(templateDir, 'html.ejs'),
+    filename: `${url}/index.html`.replace(/^\/+/, ''),
+    templateParameters: {
+      title: getTitle(title),
+      // Don't prerender fullscreen pages (expensive!)
+      prerendering: (isProd && !isFullscreen && !url.includes('extensions')) ? await prerender(url, pathPrefix) : 'Loading...',
+      // Don't use GA in dev mode
+      googleAnalyticsID: isProd ? googleAnalyticsID : false,
+      algolia
+    },
+    scriptLoading: 'defer',
+    inject: false,
+    minify: false
+  })
+}
+
+async function getHtmlWebpackPlugins(options) {
+  const { isProd } = options;
+  const { routes, fullscreenRoutes } = require('../../routes');
+  const res = [
+    // Sitemap
+    new HtmlWebpackPlugin({
+      template: path.join(templateDir, 'sitemap.ejs'),
+      filename: 'sitemap.xml',
+      templateParameters: {
+        urls: Object.entries(routes)
+          .map(([path, { sources }]) => [path, ...(sources || []).slice(1).map(source => source.slug)])
+          .flat()
+      },
+      inject: false,
+      minify: false,
+    })
+  ];
+
+  if (!isProd) {
+    // Only render the index page in dev mode and rely on historyApiFallback
+    res.push(await getHtmlWebpackPlugin({ isProd, url: '', title: 'Dev', ...options }));
+    return res;
+  }
+
+  const titledRoutes = Object.entries(routes)
+    .concat(Object.entries(fullscreenRoutes))
+    .map(([url, { sources = [], title, isFullscreen }]) => [
+      [url, { title, isFullscreen }],
+      // Add pages for sources
+      ...sources.slice(1).map(source => [source.slug, source])
+    ])
+    .flat()
+    .sort();
+
+  for (const [url, { title, isFullscreen }] of titledRoutes) {
+    res.push(await getHtmlWebpackPlugin({ url, title, isFullscreen, ...options }));
+  }
+
+  console.log('done prerendering');
+  return res;
+};
+
+module.exports = {
+  getHtmlWebpackPlugins
+};

package/scripts/webpack/prerender.js

@@ -0,0 +1,59 @@
+const React = require('react');
+const ReactDOMServer = require('react-dom/server');
+const { ServerLocation } = require('@reach/router');
+const ssrPrepass = require('react-ssr-prepass');
+// react, react-dom, and @reach/router are all EXCLUDED from the ssr-bundle.js
+// The versions imported above are used instead, which allows us to use <ServerLocation>
+// const ssrPrepass = require('react-ssr-prepass');
+
+// This function is effectively synchronous because it mutates global.setTimeout
+// Only allow one copy at a time to run
+async function prerender(url, pathPrefix) {
+  url = `${pathPrefix}${url}`;
+  const location = { pathname: url };
+  // For @reach/router
+  global.history = {};
+  global.location = location 
+  global.window = {
+    location,
+    // For virtualized-edit-extension
+    getBoundingClientRect: () => ({
+      height: 0,
+      width: 0
+    })
+  };
+  // For monaco
+  global.navigator = {
+    userAgent: '',
+    maxTouchPoints: 1
+  };
+  global.document = {
+    queryCommandSupported: () => true,
+    // For react-consoles
+    createElementNS: () => ({
+      download: {}
+    })
+  };
+  global.self = {
+    // For react-console
+    document: global.document
+  };
+
+  console.log('prender', url);
+  const { App } = require(`${process.cwd()}/.cache/ssr-build/main`);
+  const WrappedApp = React.createElement(ServerLocation, { url },
+    React.createElement(App)
+  );
+  await ssrPrepass(WrappedApp, element => {
+    if (element.type.name === 'AsyncComponent') {
+      return element.type.preload();
+    }
+  });
+  const string = ReactDOMServer.renderToString(WrappedApp);
+
+  return string;
+}
+
+module.exports = {
+  prerender
+};

package/scripts/webpack/webpack.base.config.js

@@ -0,0 +1,159 @@
+const path = require('path');
+const webpack = require('webpack');
+const { CleanWebpackPlugin } = require('clean-webpack-plugin');
+const CopyWebpackPlugin = require('copy-webpack-plugin');
+const MonacoWebpackPlugin = require('monaco-editor-webpack-plugin');
+
+module.exports = (_env, argv) => {
+  const {
+    pathPrefix = '',
+    mode,
+    algolia = {},
+    hasGdprBanner = false,
+    hasFooter = false,
+    hasVersionSwitcher = false,
+    hasDesignGuidelines = false,
+    sideNavItems = [],
+    topNavItems = [],
+    includePaths = []
+  } = argv;
+
+  const isProd = mode === 'production';
+
+  return {
+    entry: path.resolve(__dirname, '../../app.js'),
+    output: {
+      publicPath: isProd ? `${pathPrefix}/` : '/',
+      pathinfo: false, // https://webpack.js.org/guides/build-performance/#output-without-path-info,
+      hashDigestLength: 8
+    },
+    amd: false, // We don't use any AMD modules, helps performance
+    mode: isProd ? 'production' : 'development',
+    devtool: isProd ? false : 'cheap-module-source-map',
+    module: {
+      rules: [
+        {
+          test: /\.[tj]sx?$/,
+          include: [
+            path.resolve(process.cwd(), 'src'),
+            path.resolve(process.cwd(), 'patternfly-docs'),
+            path.resolve(__dirname, '../..'), // Temporarily compile theme using webpack for development
+            /react-[\w-]+\/src\/.*\/examples/,
+            /react-[\w-]+\\src\\.*\\examples/, // fix for Windows
+          ].concat(includePaths.map(path => new RegExp(path))),
+          exclude: [
+            path.resolve(__dirname, '../../node_modules'), // Temporarily compile theme using webpack for development
+          ],
+          use: {
+            loader: 'babel-loader',
+            options: {
+              cacheDirectory: '.cache/babel',
+              cacheCompression: false,
+              presets: [['@babel/preset-env', {
+                loose: true,
+                corejs: 3,
+                useBuiltIns: 'entry',
+                exclude: ['transform-regenerator', 'transform-async-to-generator'],
+                modules: false,
+                targets: "> 0.25%, not dead"
+              }]],
+              plugins: [
+                '@babel/plugin-transform-react-jsx',
+                '@babel/plugin-proposal-class-properties',
+                ["@babel/plugin-proposal-private-methods", { "loose": false }],
+                ["@babel/plugin-proposal-private-property-in-object", { "loose": false }]
+              ],
+            }
+          },
+        },
+        {
+          test: /\.(png|jpe?g|webp)$/,
+          use: {
+            loader: 'responsive-loader',
+            options: {
+              adapter: require('responsive-loader/sharp'),
+              name: '[name].[contenthash].[ext]',
+              outputPath: 'images/'
+            },
+          }
+        },
+        {
+          test: /\.(gif|svg)$/,
+          use: {
+            loader: 'file-loader',
+            options: {
+              name: '[name].[contenthash].[ext]',
+              outputPath: 'images/'
+            },
+          }
+        },
+        {
+          test: /\.(pdf)$/,
+          use: {
+            loader: 'file-loader',
+            options: {
+              name: '[name].[contenthash].[ext]',
+            }
+          }
+        },
+        {
+          test: /.(woff(2)?|ttf|eot)(\?v=\d+\.\d+\.\d+)?$/,
+          use: [
+            {
+              loader: 'file-loader',
+              options: {
+                name: '[name].[ext]',
+                outputPath: 'fonts/'
+              }
+            }
+          ]
+        }
+      ]
+    },
+    resolve: {
+      // Allow importing client routes
+      alias: {
+        'client-styles': path.resolve(process.cwd(), 'patternfly-docs/patternfly-docs.css.js'),
+        './routes-client': path.resolve(process.cwd(), 'patternfly-docs/patternfly-docs.routes.js'),
+        './routes-generated': path.resolve(process.cwd(), 'patternfly-docs/generated/index.js'),
+        'lodash': 'lodash-es' // Sanely bundle react-charts.
+      },
+      modules: [
+        'node_modules',
+        ...module.paths,
+      ]
+    },
+    // Use this module's node_modules first (for use in Core/React workspaces)
+    resolveLoader: {
+      modules: module.paths,
+    },
+    plugins: [
+      new webpack.DefinePlugin({
+        'process.env.NODE_ENV': JSON.stringify(mode),
+        'process.env.pathPrefix': JSON.stringify(isProd ? pathPrefix : ''),
+        'process.env.algolia': JSON.stringify(algolia),
+        'process.env.hasGdprBanner': JSON.stringify(hasGdprBanner),
+        'process.env.hasFooter': JSON.stringify(hasFooter),
+        'process.env.hasVersionSwitcher': JSON.stringify(hasVersionSwitcher),
+        'process.env.hasDesignGuidelines': JSON.stringify(hasDesignGuidelines),
+        'process.env.sideNavItems': JSON.stringify(sideNavItems),
+        'process.env.topNavItems': JSON.stringify(topNavItems),
+        'process.env.prnum': JSON.stringify(process.env.CIRCLE_PR_NUMBER || process.env.PR_NUMBER || ''),
+        'process.env.prurl': JSON.stringify(process.env.CIRCLE_PULL_REQUEST || ''),
+      }),
+      new CopyWebpackPlugin({
+        patterns: [
+          { from: path.join(__dirname, '../../assets'), to: 'assets' }
+        ]
+      }),
+      new MonacoWebpackPlugin(),
+      ...(isProd
+        ? [
+          new CleanWebpackPlugin()
+        ]
+        : []
+      )
+    ],
+    stats: 'minimal'
+  };
+}

package/scripts/webpack/webpack.client.config.js

@@ -0,0 +1,146 @@
+const path = require('path');
+const fs = require('fs');
+const { merge } = require('webpack-merge');
+const BundleAnalyzerPlugin = require('webpack-bundle-analyzer').BundleAnalyzerPlugin;
+const MiniCssExtractPlugin = require('mini-css-extract-plugin');
+const TerserPlugin = require('terser-webpack-plugin');
+const CopyPlugin = require('copy-webpack-plugin');
+const baseConfig = require('./webpack.base.config');
+const { getHtmlWebpackPlugins } = require('./getHtmlWebpackPlugins');
+
+let pfDir;
+try {
+  pfDir = path.dirname(require.resolve('@patternfly/patternfly/package.json'));
+}
+catch {
+  // Inside core workspace
+  pfDir = path.join(process.cwd(), 'dist');
+}
+const staticDir = path.join(process.cwd(), 'static/');
+// Don't include PatternFly styles twice
+const reactCSSRegex = /(react-[\w-]+\/dist|react-styles\/css)\/.*\.css$/;
+const reactJSRegex = /react-([^\\/]*)[\\/]dist[\\/].*\.js$/
+
+const clientConfig = async (env, argv) => {
+  const isProd = argv.mode === 'production';
+
+  return {
+    output: {
+      path: argv.output ? path.resolve(argv.output) : path.resolve('public'),
+      filename: '[name].[hash].bundle.js'
+    },
+    devServer: {
+      hot: true,
+      historyApiFallback: true,
+      port: argv.port,
+      clientLogLevel: 'info',
+      stats: 'minimal'
+    },
+    optimization: {
+      splitChunks: {
+        chunks: 'all',
+        // https://webpack.js.org/plugins/mini-css-extract-plugin/#extracting-all-css-in-a-single-file
+        cacheGroups: {
+          vendorStyles: {
+            test: /[\\/]node_modules[\\/].*\.css$/,
+            priority: 9
+          },
+          mainStyles: {
+            test: /\.css$/,
+            priority: 10
+          },
+          // This speeds up reloads 2x in React and doesn't affect org's reload times
+          ...(!isProd && {
+            reactPackage: {
+              test: reactJSRegex,
+              name(module, _chunks, cacheGroupKey) {
+                const package = module.identifier().match(reactJSRegex)[1];
+                return `${cacheGroupKey}-${package}`;
+              },
+              reuseExistingChunk: true,
+              priority: 5
+            },
+          }),
+          defaultVendors: {
+            test: /[\\/]node_modules[\\/]/,
+            enforce: true,
+            reuseExistingChunk: true,
+            priority: 3
+          },
+        },
+      },
+      minimize: isProd ? true : false,
+      minimizer: [
+        new TerserPlugin({
+          cache: path.join(process.cwd(), '.cache/terser'),
+          ...(process.env.CI ? { parallel: 2 } : {})
+        }),
+      ],
+      runtimeChunk: 'single',
+    },
+    module: {
+      rules: [
+        {
+          test: /\.css$/,
+          exclude: reactCSSRegex,
+          use: [
+            {
+              loader: MiniCssExtractPlugin.loader,
+            },
+            {
+              loader: 'css-loader'
+            },
+            {
+              loader: 'postcss-loader',
+              options: {
+                postcssOptions: {
+                  plugins: [
+                    require('autoprefixer')({
+                      env: '>0.25%, not ie 11, not op_mini all',
+                      flexbox: false,
+                      grid: false
+                    })
+                  ]
+                }
+              }
+            }
+          ]
+        },
+        {
+          test: reactCSSRegex,
+          use: 'null-loader'
+        },
+      ]
+    },
+    plugins: [
+      new MiniCssExtractPlugin(!isProd ? {} : {
+        filename: '[name].[contenthash].css',
+        chunkFilename: '[name].[contenthash].css',
+      }),
+      new CopyPlugin({
+        patterns: [
+          // versions.json will later be copied to the root www dir
+          { from: path.join(__dirname, '../../versions.json'), to: 'versions.json' },
+          { from: path.join(pfDir, 'assets/images/'), to: 'assets/images/' },
+          { from: path.join(pfDir, 'assets/fonts/'), to: 'assets/fonts/' },
+          ...(fs.existsSync(staticDir) ? [{ from: staticDir, to: '' }] : [])
+        ]
+      }),
+      ...await getHtmlWebpackPlugins({ isProd, ...argv }), // Create an HTML page per route
+      ...(env === 'analyze'
+        ? [
+          new BundleAnalyzerPlugin({
+            generateStatsFile: true,
+            statsFilename: 'webpack.stats.json'
+          })
+        ]
+        : [])
+    ]
+  };
+}
+
+// https://webpack.js.org/configuration/configuration-types/#exporting-a-promise
+module.exports = async (env = {}, argv) => merge(
+  baseConfig(env, argv),
+  await clientConfig(env, argv)
+);

package/scripts/webpack/webpack.server.config.js

@@ -0,0 +1,55 @@
+const path = require('path');
+const webpack = require('webpack');
+const { merge } = require('webpack-merge');
+const baseConfig = require('./webpack.base.config');
+
+const serverConfig = () => {
+  return {
+    output: {
+      path: path.resolve('.cache/ssr-build'), // Don't bloat `public` dir
+			libraryTarget: 'commonjs2' // Use module.exports
+    },
+    target: 'node', // Load chunks using require
+    plugins: [
+      new webpack.DefinePlugin({
+        'process.env.PRERENDER': true // In app.js don't call ReactDOM.render
+      }),
+    ],
+    optimization: {
+      removeAvailableModules: false,
+      removeEmptyChunks: false,
+      splitChunks: false,
+      minimize: false // Faster build, easier debugging
+    },
+    module: {
+      rules: [
+        {
+          test: /\.css$/,
+          use: 'null-loader'
+        },
+        // This does weird things to document
+        {
+          test: /(novnc-core|@novnc\/novnc)\/.*\.js/,
+          use: 'null-loader'
+        }
+      ]
+    },
+    resolve: {
+      alias: {
+        // This stops prerender from hanging in `yarn build:client`
+        'd3-timer': '@patternfly/documentation-framework/helpers/d3-timer',
+        // The maintainer will not allow his bundle to be required from a node context
+        // https://github.com/xtermjs/xterm.js/pull/3134
+        'xterm':  '@patternfly/documentation-framework/helpers/xterm',
+        'xterm-addon-fit':  '@patternfly/documentation-framework/helpers/xterm-addon-fit'
+      },
+    },
+    // Load in prerender.js instead
+    externals: ['react', 'react-dom', '@reach/router']
+  };
+}
+
+module.exports = (env = {}, argv) => merge(
+  baseConfig(env, argv),
+  serverConfig(env, argv)
+);

package/scripts/writeScreenshots.js

@@ -0,0 +1,66 @@
+const path = require('path');
+const os = require('os');
+const fs = require('fs-extra');
+const { Cluster } = require('puppeteer-cluster');
+const sharp = require('sharp');
+const { fullscreenRoutes } = require('../routes.js');
+
+const screenshotBase = path.join(process.cwd(), 'patternfly-docs/generated');
+sharp.cache(false);
+
+async function writeScreenshot({ page, data: { url, urlPrefix } }) {
+  // Default viewport is 800x600
+  await page.setViewport({
+    width: 1920,
+    height: 1080,
+  });
+  await page.goto(url);
+  await page.waitForSelector('.pf-u-h-100');
+  // Wait extra 300ms
+  await new Promise(resolve => {
+    setTimeout(resolve, 300);
+  });
+  const outfile = path.join(
+    screenshotBase,
+    url.replace(`${urlPrefix}/`, '') + '.png'
+  );
+  fs.ensureDirSync(path.dirname(outfile));
+  await page.screenshot({ path: outfile });
+  console.log(path.relative(process.cwd(), outfile));
+  // Resize since max-width allowed for thumbnails in CSS is 800px
+  let buffer = await sharp(outfile)
+    .resize(800, 450)
+    .toBuffer();
+  // Overwrite old file
+  await sharp(buffer).toFile(outfile);
+}
+
+async function writeScreenshots({ urlPrefix }) {
+  const cluster = await Cluster.launch({
+    concurrency: Cluster.CONCURRENCY_CONTEXT,
+    maxConcurrency: os.cpus().length,
+    puppeteerOptions: {
+      headless: true, // set to false for testing...
+      args: ["--no-sandbox", "--disable-setuid-sandbox"]
+    }
+  });
+
+  // Define a task (in this case: screenshot of page)
+  await cluster.task(writeScreenshot);
+
+  // Add some pages to queue
+  Object.entries(fullscreenRoutes)
+    .filter(([, { isFullscreenOnly }]) => isFullscreenOnly)
+    .forEach(([url,]) => cluster.queue({
+      url: `${urlPrefix}${url}`,
+      urlPrefix
+    }));
+
+  // Shutdown after everything is done
+  await cluster.idle();
+  await cluster.close();
+}
+
+module.exports = {
+  writeScreenshots
+}

package/templates/design-guidelines.js

@@ -0,0 +1,13 @@
+import React from 'react';
+import { Link } from '@patternfly/documentation-framework/components/link/link';
+
+export const DesignGuidelineTemplate = (
+  <React.Fragment>
+    We’re working on some guidelines for this component.
+    {' '}If you have any questions in the meantime, feel free to
+    {' '}
+    <Link to="/community#get-in-touch">
+      get in touch with us.
+    </Link>
+  </React.Fragment>
+);

package/templates/html.ejs

@@ -0,0 +1,52 @@
+<!DOCTYPE html>
+<html lang="en-US">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width,initial-scale=1,shrink-to-fit=no">
+    <meta name="description" content="PatternFly is Red Hat's open source design system. It consists of components, documentation, and code for building enterprise applications at scale.">
+    <title><%= title %></title>
+    <link rel="shortcut icon" href="/assets/favicon.ico">
+    <link rel="icon" type="image/png" sizes="16x16" href="/assets/favicon-16x16.png">
+    <link rel="icon" type="image/png" sizes="32x32" href="/assets/favicon-32x32.png">
+    <link rel="icon" type="image/png" sizes="48x48" href="/assets/favicon-48x48.png">
+    <link rel="manifest" href="/assets/manifest.json">
+    <meta name="mobile-web-app-capable" content="yes">
+    <meta name="theme-color" content="#151515">
+    <meta name="application-name" content="PatternFly docs">
+    <%= htmlWebpackPlugin.tags.headTags %>
+  </head>
+  <body class="pf-m-redhat-updated-font pf-m-redhatmono-font">
+    <div id="root">
+      <%= prerendering %>
+    </div>
+    <%= htmlWebpackPlugin.tags.bodyTags %>
+    <% if (algolia) { %>
+    <script
+      async
+      crossorigin
+      type="module"
+      src="https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.js"
+    ></script>
+    <link
+      href="https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.css"
+      crossorigin
+      rel="stylesheet"
+      media="print"
+      onload="this.media='all'; this.onload=null;"
+    >
+    <% } %>
+    <% if (googleAnalyticsID) { %>
+      <!-- Global site tag (gtag.js) - Google Analytics -->
+      <script async src="https://www.googletagmanager.com/gtag/js?id=<%= googleAnalyticsID %>"></script>
+      <script>
+        if(!(parseInt(navigator.doNotTrack) === 1 || parseInt(window.doNotTrack) === 1 || parseInt(navigator.msDoNotTrack) === 1 || navigator.doNotTrack === "yes")) {
+          window.dataLayer = window.dataLayer || [];
+          function gtag(){dataLayer.push(arguments);}
+          gtag('js', new Date());
+
+          gtag('config', '<%= googleAnalyticsID %>');
+        }
+      </script>
+    <% } %>
+  </body>
+</html>