[polaris.shopify.com] Update markdown file structure

.changeset/fast-cooks-whisper.md

@@ -0,0 +1,5 @@
+---
+'polaris.shopify.com': minor
+---
+
+Update markdown file structure to not require folders for each markdown page. Now you can simply create a markdown.md file and it will be rendered as a page.

polaris.shopify.com/content/getting-started/Design/index.md → polaris.shopify.com/content/getting-started/design.md

@@ -6,11 +6,11 @@ keywords:
 order: 2
 ---
 
-If you’re starting out designing for the Shopify admin, here are a few things you need to get going. 
-Learn  more about [patterns, components, and tokens](/getting-started/patterns-components-and-tokens).
+If you’re starting out designing for the Shopify admin, here are a few things you need to get going.
+Learn more about [patterns, components, and tokens](/getting-started/patterns-components-and-tokens).
 
 ## Resources
 
-| Components                                                                                                                                                                                                                                                       | Tokens                                                                                                                                                                                                                                                  | Icons                                                                                                                                                                                                                               | Documentation                                                                                                                                                                                                                        |
-| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Components                                                                                                                                                                                                                                                        | Tokens                                                                                                                                                                                                                                                   | Icons                                                                                                                                                                                                                                | Documentation                                                                                                                                                                                              |
+| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Reusable elements and styles, packaged through code, for building admin interfaces.</li><ul><li>[React component library](https://polaris.shopify.com/components)</li><ul><li>[Component Figma library](https://www.figma.com/community/file/1111360433678236702) | Coded names that represent design decisions for color, spacing, typography, and more.</li><ul><li>[Token library](https://polaris.shopify.com/tokens/colors)</li><ul><li>[Token Figma library](https://www.figma.com/community/file/1111359207966840858) | Over 400 carefully designed icons focused on commerce and entrepreneurship.</li><ul><li>[Icon library](https://polaris.shopify.com/icons)</li><ul><li>[Icon Figma library](https://www.figma.com/community/file/1110993965108325096) | Fundamental guidance for creating quality admin experiences.</li><ul><li>[Design principles](https://polaris.shopify.com//design/design)</li><ul><li>[Shared resources](/getting-started/shared-resources) |

polaris.shopify.com/pages/[...slug].tsx

@@ -43,7 +43,12 @@ export const getStaticProps: GetStaticProps<Props, {slug: string[]}> = async ({
   const slug = params?.slug;
   if (!slug)
     throw new Error('Expected params.slug to be defined (as string[])');
-  const mdRelativePath = `${contentDir}/${params.slug.join('/')}/index.md`;
+
+  const slugPath = `${contentDir}/${params.slug.join('/')}`;
+  const pathIsDirectory = fs.existsSync(slugPath) && fs.lstatSync(slugPath).isDirectory();
+  const mdRelativePath = pathIsDirectory
+    ? `${contentDir}/${params.slug.join('/')}/index.md`
+    : `${contentDir}/${params.slug.join('/')}.md`;
   const mdFilePath = path.resolve(process.cwd(), mdRelativePath);
   const editPageLinkPath = `/polaris.shopify.com/${mdRelativePath}`;
 
@@ -82,13 +87,17 @@ function fileShouldNotBeRenderedWithCatchAllTemplate(path: string): boolean {
 }
 
 export const getStaticPaths: GetStaticPaths = async () => {
-  const globPath = path.resolve(process.cwd(), 'content/**/*.md');
+  const globPath = [
+    path.resolve(process.cwd(), 'content/*.md'),
+    path.resolve(process.cwd(), 'content/**/*.md'),
+  ];
   const paths = globby
     .sync(globPath)
     .map((fileName: string) => {
       return fileName
         .replace(`${process.cwd()}/content`, '')
-        .replace('/index.md', '');
+        .replace('/index.md', '')
+        .replace('.md', '');
     })
     .filter(fileShouldNotBeRenderedWithCatchAllTemplate);
 

polaris.shopify.com/pages/api/search/v0/index.tsx

@@ -118,7 +118,7 @@ const getSearchResults = (query: string) => {
       id: slugify(`foundations ${title}`),
       category: 'foundations',
       score: 0,
-      url: slug,
+      url: `/${slug}`,
       meta: {
         foundations: {
           title,

polaris.shopify.com/pages/components/[component].tsx

@@ -74,7 +74,7 @@ export const getStaticProps: GetStaticProps<
   {component: string}
 > = async (context) => {
   const componentSlug = context.params?.component;
-  const relativeMdPath = `content/components/${componentSlug}/index.md`;
+  const relativeMdPath = `content/components/${componentSlug}.md`;
   const mdFilePath = path.resolve(process.cwd(), relativeMdPath);
   const editPageLinkPath = `polaris.shopify.com/${relativeMdPath}`;
 
@@ -136,12 +136,13 @@ export const getStaticProps: GetStaticProps<
 };
 
 export const getStaticPaths: GetStaticPaths = async () => {
-  const globPath = path.resolve(process.cwd(), 'content/components/*/*.md');
-  const paths = globby.sync(globPath).map((fileName: string) => {
-    return fileName
-      .replace(`${process.cwd()}/content`, '')
-      .replace('/index.md', '');
-  });
+  const globPath = path.resolve(process.cwd(), 'content/components/*.md');
+  const paths = globby
+    .sync(globPath)
+    .filter((path) => !path.endsWith('index.md'))
+    .map((path) =>
+      path.replace(`${process.cwd()}/content`, '').replace('.md', ''),
+    );
 
   return {
     paths,

polaris.shopify.com/pages/whats-new.tsx

@@ -38,14 +38,16 @@ export const getStaticProps: GetStaticProps<
     frontMatter: {title, description},
   }: MarkdownFile = parseMarkdown(mdFile);
 
-  const globPath = path.resolve(process.cwd(), 'content/whats-new/*/index.md');
-  const paths = globby.sync(globPath);
+  const globPath = path.resolve(process.cwd(), 'content/whats-new/*.md');
+  const paths = globby
+    .sync(globPath)
+    .filter((path) => !path.endsWith('index.md'));
 
   const posts: Props['posts'] = paths.map((path) => {
     const markdown = fs.readFileSync(path, 'utf-8');
     const {frontMatter}: MarkdownFile = parseMarkdown(markdown);
     const {title, description, imageUrl} = frontMatter;
-    const slug = path.replace(contentDir, '').replace('index.md', '');
+    const slug = path.replace(contentDir, '').replace('.md', '');
     return {title, description, slug, imageUrl};
   });
 

polaris.shopify.com/scripts/change-file-structure.mjs

@@ -0,0 +1,20 @@
+import path from 'path';
+import fs from 'fs';
+import globby from 'globby';
+
+const pathGlob = path.join(process.cwd(), 'content/**/index.md');
+
+const filePaths = globby.sync(pathGlob);
+
+filePaths.forEach((filePath) => {
+  const segments = filePath.split('/');
+  const folderPath = segments.slice(0, segments.length - 1).join('/');
+  const newPath = `${segments.slice(0, segments.length - 2).join('/')}/${
+    segments[segments.length - 2]
+  }.md`;
+  const folderContent = fs.readdirSync(folderPath);
+  if (folderContent.length === 1) {
+    fs.copyFileSync(filePath, newPath);
+    fs.rmSync(folderPath, {recursive: true, force: true});
+  }
+});

polaris.shopify.com/scripts/gen-cache-json.mjs

@@ -56,14 +56,18 @@ const getMdContent = (filePath) => {
   const {data} = matter(fileContent);
   const slug = filePath
     .replace(`${process.cwd()}/content/`, '')
-    .replace('/index.md', '');
+    .replace('/index.md', '')
+    .replace('.md', '');
 
   return {frontMatter: data, slug};
 };
 
 const genCacheJson = () => {
   if (!existsSync(cacheDir)) mkdirSync(cacheDir, {recursive: true});
-  const pathGlob = path.join(process.cwd(), 'content/**/*.md');
+  const pathGlob = [
+    path.join(process.cwd(), 'content/*.md'),
+    path.join(process.cwd(), 'content/**/*.md'),
+  ];
 
   const mdFiles = globby.sync(pathGlob);
 

polaris.shopify.com/scripts/gen-og-images.mjs

@@ -53,7 +53,7 @@ const generateHTML = async (url, slug) => {
     url.startsWith('/content/') ||
     url.startsWith('/patterns/')
   ) {
-    const mdFilePath = path.join(process.cwd(), `content${url}/index.md`);
+    const mdFilePath = path.join(process.cwd(), `content${url}.md`);
     const markdownContent = await readFile(mdFilePath, 'utf-8');
     const {data} = matter(markdownContent);
     if (!data.icon) return;

polaris.shopify.com/src/components/ComponentsPage/ComponentsPage.tsx

@@ -1,9 +1,5 @@
 import siteJson from '../../../.cache/site.json';
-import {
-  getComponentCategories,
-  stripMarkdownLinks,
-  slugify,
-} from '../../utils/various';
+import {getComponentCategories, stripMarkdownLinks} from '../../utils/various';
 import {Status, SiteJSON} from '../../types';
 import styles from './ComponentsPage.module.scss';
 import PageMeta from '../PageMeta';
@@ -43,13 +39,12 @@ export default function ComponentsPage() {
                       status,
                       description = '',
                     } = pages[slug].frontMatter;
-                    const url = `/components/${slugify(title)}`;
                     return (
                       <Grid.Item
                         key={title}
                         title={title}
                         description={stripMarkdownLinks(description)}
-                        url={url}
+                        url={`/${slug}`}
                         status={status as Status}
                         renderPreview={() => (
                           <ComponentThumbnail title={title} />

polaris.shopify.com/src/utils/foundations.ts

@@ -18,16 +18,13 @@ export const getStaticPropsForFoundations = (category: string) => {
       frontMatter: {description},
     }: MarkdownFile = parseMarkdown(markdown);
 
-    const filePattern = path.resolve(
-      process.cwd(),
-      `content/${category}/**/index.md`,
-    );
+    const filePattern = path.resolve(process.cwd(), `content/${category}/*.md`);
 
     let items: FoundationsProps['items'] = [];
     const markdownFilePaths = await globby(filePattern);
 
     markdownFilePaths
-      .filter((path) => !path.endsWith(`content/${category}/index.md`))
+      .filter((path) => !path.endsWith(`index.md`))
       .forEach((markdownFilePath) => {
         if (fs.existsSync(markdownFilePath)) {
           const markdown = fs.readFileSync(markdownFilePath, 'utf-8');
@@ -36,7 +33,7 @@ export const getStaticPropsForFoundations = (category: string) => {
 
           const url = markdownFilePath
             .replace(`${process.cwd()}/content`, '')
-            .replace('index.md', '');
+            .replace(/\.md$/, '');
 
           const headings = (readme.match(/\n## [^\n]+/gi) || []).map(
             (heading) => heading.replace(/^\n## /, '').trim(),