docs: better code highlight with Prism (#428)

## Summary by CodeRabbit - **New Features** - Enhanced code presentation in the documentation with syntax highlighting using `prism-react-renderer`. - Added a new story in the "Getting Started" section, demonstrating the usage of UI components with highlighted code blocks. - **Documentation** - Updated the `Getting Started` documentation to include syntax-highlighted code blocks for installation, configuration, and usage sections. - **Dependencies** - Updated `@ladle/react` to version `4.0.3`. - Added `prism-react-renderer` version `2.3.1` to improve documentation readability.
versini-org · Mar 18, 2024 · b6a8fd9 · b6a8fd9
1 parent 421b11d
commit b6a8fd9
Show file tree

Hide file tree

Showing 6 changed files with 278 additions and 315 deletions.
diff --git a/packages/documentation/package.json b/packages/documentation/package.json
@@ -17,7 +17,7 @@
 		"test": "echo \"WARNING: no test specified\" && exit 0"
 	},
 	"devDependencies": {
-		"@ladle/react": "4.0.2"
+		"@ladle/react": "4.0.3"
 	},
 	"dependencies": {
 		"@tailwindcss/typography": "0.5.10",
@@ -27,6 +27,8 @@
 		"@versini/ui-styles": "workspace:../ui-styles",
 		"@versini/ui-system": "workspace:../ui-system",
 		"clsx": "2.1.0",
+		"prismjs": "1.29.0",
+		"prism-react-renderer": "2.3.1",
 		"react": "18.2.0",
 		"react-dom": "18.2.0",
 		"tailwindcss": "3.4.1"

diff --git a/packages/documentation/src/GettingStarted/2-Installation.stories.tsx b/packages/documentation/src/GettingStarted/2-Installation.stories.tsx
@@ -1,3 +1,5 @@
+/* eslint-disable @typescript-eslint/ban-ts-comment */
+
 import { linkTo, Story } from "@ladle/react";
 import {
 	ButtonIcon,
@@ -9,11 +11,16 @@ import {
 } from "@versini/ui-components";
 import { IconNext, IconPrevious } from "@versini/ui-icons";
 import { Flexgrid, FlexgridItem } from "@versini/ui-system";
+import { Highlight, Prism, themes } from "prism-react-renderer";
 
 export default {
 	title: "Getting Started",
 };
 
+(typeof global !== "undefined" ? global : window).Prism = Prism;
+// @ts-ignore
+await import("prismjs/components/prism-bash");
+
 const data = [
 	{
 		id: 1,
@@ -83,19 +90,45 @@ export const Installation: Story<any> = () => (
 			If you only need some core components and of course the CSS styles
 			associated<sup>1</sup>, use the following command:
 		</p>
-		<pre>
-			<code>
-				{`$ npm install --save-dev @versini/ui-styles
-$ npm install --save @versini/ui-components
-`}
-			</code>
-		</pre>
+		<Highlight
+			theme={themes.vsDark}
+			code={`$ npm install --save-dev @versini/ui-styles
+$ npm install --save @versini/ui-components`}
+			language="bash"
+		>
+			{({ style, tokens, getLineProps, getTokenProps }) => (
+				<pre style={style}>
+					{tokens.map((line, i) => (
+						<div key={i} {...getLineProps({ line })}>
+							{line.map((token, key) => (
+								<span key={key} {...getTokenProps({ token })} />
+							))}
+						</div>
+					))}
+				</pre>
+			)}
+		</Highlight>
+
 		<p>
 			You also need to install React and React-DOM (at least 18.0.0 or above).
 		</p>
-		<pre>
-			<code>$ npm install --save react react-dom</code>
-		</pre>
+		<Highlight
+			theme={themes.vsDark}
+			code={`$ npm install --save react react-dom`}
+			language="bash"
+		>
+			{({ style, tokens, getLineProps, getTokenProps }) => (
+				<pre style={style}>
+					{tokens.map((line, i) => (
+						<div key={i} {...getLineProps({ line })}>
+							{line.map((token, key) => (
+								<span key={key} {...getTokenProps({ token })} />
+							))}
+						</div>
+					))}
+				</pre>
+			)}
+		</Highlight>
 
 		<p>
 			<sup>1</sup>{" "}

diff --git a/packages/documentation/src/GettingStarted/3-configuration.stories.tsx b/packages/documentation/src/GettingStarted/3-configuration.stories.tsx
@@ -2,11 +2,22 @@ import { linkTo, Story } from "@ladle/react";
 import { ButtonIcon } from "@versini/ui-components";
 import { IconNext, IconPrevious } from "@versini/ui-icons";
 import { Flexgrid, FlexgridItem } from "@versini/ui-system";
+import { Highlight, themes } from "prism-react-renderer";
 
 export default {
 	title: "Getting Started",
 };
 
+const codeBlock = `// tailwind.config.js
+/** @type {import('tailwindcss').Config} */
+
+import { twPlugin } from "@versini/ui-styles";
+
+export default twPlugin.merge({
+  // this is an example, you can change the path to your files
+  content: ["./src/**/*.{js,ts,jsx,tsx}"],
+});`;
+
 export const Configuration: Story<any> = () => (
 	<>
 		<h1>Configuration</h1>
@@ -44,19 +55,21 @@ export const Configuration: Story<any> = () => (
 			you can take advantage of tree-shaking unused styles:
 		</p>
 
-		<pre>
-			<code>
-				{`// tailwind.config.js
-/** @type {import('tailwindcss').Config} */
-
-import { twPlugin } from "@versini/ui-styles";
-
-export default twPlugin.merge({
-  // this is an example, you can change the path to your files
-  content: ["./src/**/*.{js,ts,jsx,tsx}"],
-});`}
-			</code>
-		</pre>
+		<div>
+			<Highlight theme={themes.vsDark} code={codeBlock} language="jsx">
+				{({ style, tokens, getLineProps, getTokenProps }) => (
+					<pre style={style}>
+						{tokens.map((line, i) => (
+							<div key={i} {...getLineProps({ line })}>
+								{line.map((token, key) => (
+									<span key={key} {...getTokenProps({ token })} />
+								))}
+							</div>
+						))}
+					</pre>
+				)}
+			</Highlight>
+		</div>
 
 		<Flexgrid alignHorizontal="space-between">
 			<FlexgridItem>

diff --git a/packages/documentation/src/GettingStarted/4-usage.stories.mdx b/packages/documentation/src/GettingStarted/4-usage.stories.mdx
diff --git a/packages/documentation/src/GettingStarted/4-usage.stories.tsx b/packages/documentation/src/GettingStarted/4-usage.stories.tsx
@@ -0,0 +1,89 @@
+import { linkTo, Story } from "@ladle/react";
+import { Button, ButtonIcon, Card } from "@versini/ui-components";
+import { IconNext, IconPrevious } from "@versini/ui-icons";
+import { Flexgrid, FlexgridItem } from "@versini/ui-system";
+import { Highlight, themes } from "prism-react-renderer";
+
+export default {
+	title: "Getting Started",
+};
+
+const codeBlock = `// App.tsx
+import { Button, Card } from "@versini/ui-components";
+
+/**
+ * Now that the required components are
+ * available in the scope, you can use them
+ * in your return method in JSX:
+ */
+function App() {
+  return (
+    <Card
+      header="Welcome to UI Components"
+      footer={
+        <Button mode="light" noBorder>
+          Hooray
+        </Button>
+      }
+    >
+      <p>Hello World</p>
+    </Card>
+  );
+}`;
+
+export const Usage: Story<any> = () => (
+	<>
+		<h1>Usage</h1>
+
+		<h2>Example</h2>
+
+		<Highlight theme={themes.vsDark} code={codeBlock} language="jsx">
+			{({ style, tokens, getLineProps, getTokenProps }) => (
+				<pre style={style}>
+					{tokens.map((line, i) => (
+						<div key={i} {...getLineProps({ line })}>
+							{line.map((token, key) => (
+								<span key={key} {...getTokenProps({ token })} />
+							))}
+						</div>
+					))}
+				</pre>
+			)}
+		</Highlight>
+
+		<p className="mb-4">
+			{"If everything works well, this is what you should see in your page:"}
+		</p>
+		<Card
+			header="Welcome to UI Components"
+			footer={
+				<Button mode="light" noBorder>
+					Hooray
+				</Button>
+			}
+		>
+			<p>Hello World</p>
+		</Card>
+
+		<div className="mt-8">
+			<Flexgrid alignHorizontal="space-between">
+				<FlexgridItem>
+					<ButtonIcon
+						labelRight="Configuration"
+						onClick={linkTo("getting-started--configuration")}
+					>
+						<IconPrevious monotone />
+					</ButtonIcon>
+				</FlexgridItem>
+				<FlexgridItem>
+					<ButtonIcon
+						labelLeft="Release tags"
+						onClick={linkTo("getting-started--release-tags")}
+					>
+						<IconNext monotone />
+					</ButtonIcon>
+				</FlexgridItem>
+			</Flexgrid>
+		</div>
+	</>
+);