docs: add script to fetch design system pages for storybook

.gitignore

@@ -39,6 +39,9 @@ locales/
 # storybook
 storybook/storybook-static
 
+# pages fetched from design system for storybook
+docs/design-system
+
 # Intermediate icons build directory. Our build tooling
 # currently only supports building from code in ./src
 # So we generate the react components in the src

docs/fetch-design-system-pages.js

@@ -0,0 +1,89 @@
+const fs = require('fs').promises
+const path = require('path')
+const { URL } = require('url')
+const { startCase } = require('lodash')
+const fetch = require('node-fetch')
+
+/**
+ * This regex matches relative links in markdown, like '![link](../images/image.png)'
+ *
+ * This will be used to transform relative links (and images) in the design system
+ * pages into external links to the github repo so these pages don't need to serve
+ * images and to enable linking to other design system pages.
+ *
+ * There is a negative lookahead assertion to exclude external links that include 'http'
+ * or same-page links that start with '#'
+ *
+ * It also checks if the link is for an image or not, because they need different handling
+ * The capture groups for the above link would be 1. '!' 2. 'link' and 3. '../images/image.png'
+ *
+ * Check it out here: https://regex101.com/r/y5o9Tf/6
+ *
+ */
+const mdRelativeLinkRegex = /(!)?\[(.*?)\]\((?!http|#)(.*?)\)/g
+const rawGithubUrl =
+    'https://raw.githubusercontent.com/dhis2/design-system/master/principles/'
+const regularGithubUrl =
+    'https://github.com/dhis2/design-system/tree/master/principles/'
+
+// eslint-disable-next-line max-params
+const linkReplacer = (_, imageBang, text, linkPath) => {
+    // Different links for images or markdown pages
+    const githubUrl = imageBang ? rawGithubUrl : regularGithubUrl
+    const prefix = imageBang || '' // '!' or ''
+    const url = new URL(linkPath, githubUrl).href
+    return `${prefix}[${text}](${url})`
+}
+
+const replaceRelativeLinksWithGithubLinks = text =>
+    text.replace(mdRelativeLinkRegex, linkReplacer)
+
+// Template for creating .stories.mdx file for storybook that imports from regular markdown file
+const mdxTemplate = basename => `import { Meta, Description } from '@storybook/addon-docs/blocks'
+import ${startCase(basename).replace(/ /g, '')} from './${basename}.md'
+
+<Meta title="Design System Principles/${startCase(basename)}" />
+
+<Description>{${startCase(basename).replace(/ /g, '')}}</Description>
+`
+
+const outputDir = path.join('docs', 'design-system')
+
+const downloadAndProcessFiles = async filteredFiles => {
+    // Create output dir if one doesn't exist yet
+    await fs.mkdir(outputDir, { recursive: true })
+    return Promise.all(
+        filteredFiles.map(async ({ name, download_url }) => {
+            // Get file contents
+            const text = await fetch(download_url).then(res => res.text())
+            // Transform relative links (see comments above)
+            const processedText = replaceRelativeLinksWithGithubLinks(text)
+            // Make a regular markdown file from contents
+            await fs.writeFile(path.join(outputDir, name), processedText)
+            // Make an MDX stories file that imports regular markdown
+            const basename = path.basename(name, '.md')
+            await fs.writeFile(
+                path.join(outputDir, `${basename}.stories.mdx`),
+                mdxTemplate(basename)
+            )
+        })
+    )
+}
+
+// Fetch design system 'principles' directory info from github
+fetch(
+    'https://api.github.com/repos/dhis2/design-system/contents/principles?ref=master'
+)
+    .then(res => res.json())
+    // Filter out non-markdown files
+    .then(fileInfo =>
+        fileInfo.filter(
+            ({ name, type }) => type === 'file' && name.endsWith('.md')
+        )
+    )
+    // Fetch files and create local ones for storybook
+    .then(downloadAndProcessFiles)
+    .then(() =>
+        console.log('Design system files downloaded & processed for storybook')
+    )
+    .catch(console.error)

docs/for-readers.stories.mdx

@@ -16,6 +16,12 @@ In the **Using UI** section in the menu on the left, there are a few pages descr
 
 These pages are the same as you would find on the previous doc site.
 
+## Design System Principles
+
+These are guiding principles from the [DHIS2 Design System](https://github.com/dhis2/design-system) about how to design an app that is visually consistent with the DHIS2 appearance and functionally effective. You should understand these principles and refer back to these pages and the Design System homepage as you build an app.
+
+These pages are from the 'Principles' section of the Design System. For more design guidance and detailed guidelines for individual interface components, see the [Design System homepage](https://github.com/dhis2/design-system)
+
 ## Components
 
 The other sections in the menu on the left describe the components available for use in the UI library.

storybook/config/preview.js

@@ -57,6 +57,7 @@ export const parameters = {
                     'Useful Constants',
                     'Recipes',
                 ],
+                'Design System Principles',
             ],
             // Then sort the rest alphabetically
             method: 'alphabetical',

yarn.lock

@@ -13043,6 +13043,11 @@ lodash.uniq@4.5.0, lodash.uniq@^4.5.0:
   resolved "https://registry.yarnpkg.com/lodash/-/lodash-4.17.21.tgz#679591c564c3bffaae8454cf0b3df370c3d6911c"
   integrity sha512-v2kDEe57lecTulaDIuNTPy3Ry4gLGJ6Z1O3vE1krgXZNrsQ+LFTGHVxVjcXPs17LhbZVGedAJv8XZ1tvj5FvSg==
 
+lodash@^4.17.21:
+  version "4.17.21"
+  resolved "https://registry.yarnpkg.com/lodash/-/lodash-4.17.21.tgz#679591c564c3bffaae8454cf0b3df370c3d6911c"
+  integrity sha512-v2kDEe57lecTulaDIuNTPy3Ry4gLGJ6Z1O3vE1krgXZNrsQ+LFTGHVxVjcXPs17LhbZVGedAJv8XZ1tvj5FvSg==
+
 log-symbols@^1.0.2:
   version "1.0.2"
   resolved "https://registry.yarnpkg.com/log-symbols/-/log-symbols-1.0.2.tgz#376ff7b58ea3086a0f09facc74617eca501e1a18"