docs: DRY things up a bit by swizzling (#2149)

Signed-off-by: Kent Rancourt <[email protected]>

docs/STYLE_GUIDE.md

@@ -329,8 +329,6 @@ API.
 In these cases, please make use of _tabs_ to prevent mutually exclusive options
 from taking up space and becoming a "wall of text."
 
-> ⚠️ **To use tabs, your file extension must be `.mdx` instead of `.md`.**
-
 Here is an example of using tabs correctly:
 
 ```markdown
@@ -383,7 +381,7 @@ The following tree illustrates the approach:
 │   ├── 10-create-argo-cd-instance.md
 │   ├── 20-connect-kubernetes-cluster.md
 │   ├── 30-configure-admin-user.md
-│   ├── 40-access-argo-cd-instance.mdx
+│   ├── 40-access-argo-cd-instance.md
 │   └── _category_.json
 ├── 30-how-to-guides
 │   ├── 10-changing-contexts.md
@@ -394,7 +392,7 @@ The following tree illustrates the approach:
 │   ├── 60-managing-system-accounts.md
 │   └── _category_.json
 ├── 40-changelog.md
-└── 50-faq.mdx
+└── 50-faq.md
 ```
 
 🟢 Also avoid using consecutive numbers as weights. The doc tree was initially

docs/docs/20-quickstart.mdx → docs/docs/20-quickstart.md

@@ -3,9 +3,6 @@ description: Learn about Kargo by progressing a change through multiple stages i
 sidebar_label: Quickstart
 ---
 
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-
 # Kargo Quickstart
 
 This guide presents a basic introduction to Kargo. Together, we will:

docs/docs/30-how-to-guides/20-managing-credentials.mdx → docs/docs/30-how-to-guides/20-managing-credentials.md

@@ -3,8 +3,6 @@ description: Find out how to manage repository credentials for use by Kargo
 sidebar_label: Managing credentials
 ---
 
-import Hlt from '@site/src/components/Highlight';
-
 # Managing Credentials
 
 To manage the progression of freight from stage to stage, Kargo will often

docs/docs/40-contributor-guide/10-hacking-on-kargo.mdx → docs/docs/40-contributor-guide/10-hacking-on-kargo.md

@@ -3,9 +3,6 @@ description: Learn how to set up a development environment to begin contributing
 sidebar_label: Hacking on Kargo
 ---
 
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-
 # Hacking on Kargo
 
 Kargo is implemented in Go. For maximum productivity in your text editor or IDE,

docs/docs/40-contributor-guide/index.md

@@ -11,6 +11,6 @@ Kargo project.
 
 This guide is decomposed into the following, high-level topics:
 
-* [Hacking on Kargo](./10-hacking-on-kargo.mdx)
+* [Hacking on Kargo](./10-hacking-on-kargo.md)
 * [Signing commits](./20-signing-commits.md)
 * [Code of conduct](./30-code-of-conduct.md)

docs/src/theme/MDXComponents/A.js

@@ -0,0 +1,5 @@
+import React from 'react';
+import Link from '@docusaurus/Link';
+export default function MDXA(props) {
+  return <Link {...props} />;
+}

docs/src/theme/MDXComponents/Code.js

@@ -0,0 +1,8 @@
+import React from 'react';
+import CodeBlock from '@theme/CodeBlock';
+export default function MDXCode(props) {
+  const shouldBeInline = React.Children.toArray(props.children).every(
+    (el) => typeof el === 'string' && !el.includes('\n'),
+  );
+  return shouldBeInline ? <code {...props} /> : <CodeBlock {...props} />;
+}

docs/src/theme/MDXComponents/Details.js

@@ -0,0 +1,16 @@
+import React from 'react';
+import Details from '@theme/Details';
+export default function MDXDetails(props) {
+  const items = React.Children.toArray(props.children);
+  // Split summary item from the rest to pass it as a separate prop to the
+  // Details theme component
+  const summary = items.find(
+    (item) => React.isValidElement(item) && item.type === 'summary',
+  );
+  const children = <>{items.filter((item) => item !== summary)}</>;
+  return (
+    <Details {...props} summary={summary}>
+      {children}
+    </Details>
+  );
+}

docs/src/theme/MDXComponents/Heading.js

@@ -0,0 +1,5 @@
+import React from 'react';
+import Heading from '@theme/Heading';
+export default function MDXHeading(props) {
+  return <Heading {...props} />;
+}

docs/src/theme/MDXComponents/Img/index.js

@@ -0,0 +1,16 @@
+import React from 'react';
+import clsx from 'clsx';
+import styles from './styles.module.css';
+function transformImgClassName(className) {
+  return clsx(className, styles.img);
+}
+export default function MDXImg(props) {
+  return (
+    // eslint-disable-next-line jsx-a11y/alt-text
+    <img
+      loading="lazy"
+      {...props}
+      className={transformImgClassName(props.className)}
+    />
+  );
+}

docs/src/theme/MDXComponents/Img/styles.module.css

@@ -0,0 +1,3 @@
+.img {
+  height: auto;
+}

docs/src/theme/MDXComponents/Pre.js

@@ -0,0 +1,6 @@
+import React from 'react';
+export default function MDXPre(props) {
+  // With MDX 2, this element is only used for fenced code blocks
+  // It always receives a MDXComponents/Code as children
+  return <>{props.children}</>;
+}

docs/src/theme/MDXComponents/Ul/index.js

@@ -0,0 +1,19 @@
+import React from 'react';
+import clsx from 'clsx';
+import styles from './styles.module.css';
+function transformUlClassName(className) {
+  // Fix https://github.com/facebook/docusaurus/issues/9098
+  if (typeof className === 'undefined') {
+    return undefined;
+  }
+  return clsx(
+    className,
+    // This class is set globally by GitHub/MDX. We keep the global class, and
+    // add another class to get a task list without the default ul styling
+    // See https://github.com/syntax-tree/mdast-util-to-hast/issues/28
+    className?.includes('contains-task-list') && styles.containsTaskList,
+  );
+}
+export default function MDXUl(props) {
+  return <ul {...props} className={transformUlClassName(props.className)} />;
+}

docs/src/theme/MDXComponents/Ul/styles.module.css

@@ -0,0 +1,7 @@
+.containsTaskList {
+  list-style: none;
+}
+
+:not(.containsTaskList > li) > .containsTaskList {
+  padding-left: 0;
+}

docs/src/theme/MDXComponents/index.js

@@ -0,0 +1,46 @@
+import React from 'react';
+import Head from '@docusaurus/Head';
+import MDXCode from '@theme/MDXComponents/Code';
+import MDXA from '@theme/MDXComponents/A';
+import MDXPre from '@theme/MDXComponents/Pre';
+import MDXDetails from '@theme/MDXComponents/Details';
+import MDXHeading from '@theme/MDXComponents/Heading';
+import MDXUl from '@theme/MDXComponents/Ul';
+import MDXImg from '@theme/MDXComponents/Img';
+import Admonition from '@theme/Admonition';
+import Mermaid from '@theme/Mermaid';
+
+// We use these a lot. Let's make them available globally.
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+// Custom highlight component
+import Highlight from '@site/src/components/Highlight';
+
+const MDXComponents = {
+  Head,
+  details: MDXDetails,
+  Details: MDXDetails,
+  code: MDXCode,
+  a: MDXA,
+  pre: MDXPre,
+  ul: MDXUl,
+  img: MDXImg,
+  h1: (props) => <MDXHeading as="h1" {...props} />,
+  h2: (props) => <MDXHeading as="h2" {...props} />,
+  h3: (props) => <MDXHeading as="h3" {...props} />,
+  h4: (props) => <MDXHeading as="h4" {...props} />,
+  h5: (props) => <MDXHeading as="h5" {...props} />,
+  h6: (props) => <MDXHeading as="h6" {...props} />,
+  admonition: Admonition,
+  mermaid: Mermaid,
+
+  // We use these a lot. Let's make them available globally.
+  Tabs,
+  TabItem,
+
+  // Custom highlight component
+  Hlt: Highlight,
+};
+
+export default MDXComponents;