Skip to content

Commit

Permalink
docs: better code highlight with Prism - take 2 (#429)
Browse files Browse the repository at this point in the history 
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

- **Documentation**
- Enhanced code snippets with syntax highlighting in documentation for
Dark Mode, Quick Start, and Typography sections.
	- Improved visual presentation and readability of code blocks.
- Updated content layout in Typography documentation for better user
experience.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->
  • Loading branch information
@aversini
aversini authored Mar 18, 2024
1 parent b6a8fd9 commit 4d35f42
Show file tree
Hide file tree
Showing 3 changed files with 168 additions and 63 deletions.
34 changes: 24 additions & 10 deletions packages/documentation/src/Styles/DarkMode.stories.tsx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@ import {
IconRestore,
IconSettings,
} from "@versini/ui-icons";
import { Highlight, themes } from "prism-react-renderer";

export default { title: "Styles/Components" };

Expand All @@ -48,6 +49,16 @@ const data = [
},
];

const codeBlock = `// tailwind.config.js
/** @type {import('tailwindcss').Config} */
import { twPlugin } from "@versini/ui-styles";
export default twPlugin.merge({
darkMode: "selector",
...
});`;

const CommonTemplate = () => {
return (
<>
Expand All @@ -68,15 +79,19 @@ const CommonTemplate = () => {
If you want to toggle dark mode manually instead of relying on the
operating system preference, use the Tailwind selector strategy:
</p>
<pre className="my-0">
<code>
{`// tailwind.config.js
module.exports = {
darkMode: 'selector',
// ...
}`}
</code>
</pre>
<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>
Now instead of dark classes being applied based on{" "}
<code>prefers-color-scheme</code>, they will be applied whenever the
Expand Down Expand Up @@ -122,7 +137,6 @@ module.exports = {
<TextInput
name="question"
label="Type your question here"
helperText="Powered by the sun"
rightElement={
<Button mode="light" noBorder>
Send
Expand Down
142 changes: 107 additions & 35 deletions packages/documentation/src/Styles/QuickStart.stories.tsx
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,14 @@
/* eslint-disable @typescript-eslint/ban-ts-comment */

import { Story } from "@ladle/react";
import { Highlight, Prism, themes } from "prism-react-renderer";

export default { title: "Styles" };

(typeof global !== "undefined" ? global : window).Prism = Prism;
// @ts-ignore
await import("prismjs/components/prism-bash");

export const QuickStart: Story<any> = () => (
<div className="prose prose-dark dark:prose-lighter">
<h1>Styles</h1>
Expand All @@ -17,18 +24,32 @@ export const QuickStart: Story<any> = () => (
You have to install the <code>@versini/ui-styles</code> package which
provides our TailwindCSS plugin:
</p>
<pre>
<code>$ npm install --save-dev @versini/ui-styles</code>
</pre>
<Highlight
theme={themes.vsDark}
code={`$ npm install --save-dev @versini/ui-styles`}
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>

<h2>Configuration</h2>
<p>
You then need to configure your application to use TailwindCSS and our
TailwindCSS plugin:
</p>
<pre>
<code>
{`// tailwind.config.js
<Highlight
theme={themes.vsDark}
code={`// tailwind.config.js
/** @type {import('tailwindcss').Config} */
import { twPlugin } from "@versini/ui-styles";
Expand All @@ -37,46 +58,83 @@ export default twPlugin.merge({
// this is an example, you can change the path to your files
content: ["./src/**/*.{js,ts,jsx,tsx}"],
});`}
</code>
</pre>
language="tsx"
>
{({ 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>
Finally, while our Typography styles could be used as is, some styles are
taking advantage of the Open Sans font if it is available. To add it to
your project, simply copy the following lines in your index.html{" "}
<code>head</code>:
</p>
<pre>
<code>
{`<link rel="preconnect" href="https://fonts.googleapis.com">
<Highlight
theme={themes.vsDark}
code={`<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Open+Sans&display=swap" rel="stylesheet">`}
</code>
</pre>
language="markup"
>
{({ 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>

<h2>Usage</h2>
<p>
Now you can use the <code>prose-dark</code>,<code>prose-light</code> and{" "}
<code>prose-lighter</code> classes to add our typography styles to any
vanilla HTML:
</p>
<pre>
<code>
{`<article class="prose prose-dark">
<Highlight
theme={themes.vsDark}
code={`<article class="prose prose-dark">
<h1>Garlic bread with cheese: What the science tells us</h1>
<p>
For years parents have espoused the health benefits of eating garlic bread with cheese to their
children, with the food earning such an iconic status in our culture that kids will often dress
up as warm, cheesy loaf for Halloween.
For years parents have espoused the health benefits of eating
garlic bread with cheese to their children, with the food
earning such an iconic status in our culture that kids will
often dress up as warm, cheesy loaf for Halloween.
</p>
<p>
But a recent study shows that the celebrated appetizer may be linked to a series of rabies cases
springing up around the country.
But a recent study shows that the celebrated appetizer may be
linked to a series of rabies cases springing up around the country.
</p>
<!-- ... -->
</article>`}
</code>
</pre>
language="markup"
>
{({ 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>
<strong>NOTE:</strong> always include the <code>prose</code> class when
Expand All @@ -85,26 +143,40 @@ export default twPlugin.merge({

<h2>Dark mode</h2>
<p>
Our typography styles are designed to work in dark mode, too. Just add the
<code>dark:</code> prefix to the classes:
Our typography styles are designed to automatically work in dark mode,
too. Just add the <code>dark:</code> prefix to the classes:
</p>
<pre>
<code>
{`<article class="prose prose-dark dark:prose-light">
<Highlight
theme={themes.vsDark}
code={`<article class="prose prose-dark dark:prose-light">
<h1>Garlic bread with cheese: What the science tells us</h1>
<p>
For years parents have espoused the health benefits of eating garlic bread with cheese to their
children, with the food earning such an iconic status in our culture that kids will often dress
up as warm, cheesy loaf for Halloween.
For years parents have espoused the health benefits of eating
garlic bread with cheese to their children, with the food
earning such an iconic status in our culture that kids will
often dress up as warm, cheesy loaf for Halloween.
</p>
<p>
But a recent study shows that the celebrated appetizer may be linked to a series of rabies cases
springing up around the country.
But a recent study shows that the celebrated appetizer may be
linked to a series of rabies cases springing up around the country.
</p>
<!-- ... -->
</article>`}
</code>
</pre>
language="markup"
>
{({ 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>
<strong>NOTE:</strong> please refer to the Styles {"->"} Components {"->"}{" "}
Dark mode section in the navigation bar for more information.
Expand Down
55 changes: 37 additions & 18 deletions packages/documentation/src/Styles/Typography.stories.tsx
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
/* eslint-disable react/no-unescaped-entities */

import type { Story } from "@ladle/react";
import { Highlight, themes } from "prism-react-renderer";

export default { title: "Styles/Typography" };

Expand All @@ -14,9 +15,23 @@ const CommonTemplate = ({
return (
<>
{intro}
<pre>
<code>{`<div className="prose prose-${type}>...</div>`}</code>
</pre>
<Highlight
theme={type === "light" ? themes.vsLight : themes.vsDark}
code={`<div className="prose prose-${type}>...</div>`}
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>
By default, Tailwind removes all of the default browser styling from
paragraphs, headings, lists and more. This ends up being really useful
Expand Down Expand Up @@ -54,7 +69,9 @@ const CommonTemplate = ({
that you can slap on any block of vanilla HTML content and turn it into
a beautiful, well-formatted document:
</p>
<pre>{`<article className="prose prose-${type}">
<Highlight
theme={type === "light" ? themes.vsLight : themes.vsDark}
code={`<article class="prose prose-dark">
<h1>Garlic bread with cheese: What the science tells us</h1>
<p>
For years parents have espoused the health benefits of eating
Expand All @@ -64,11 +81,24 @@ const CommonTemplate = ({
</p>
<p>
But a recent study shows that the celebrated appetizer may be
linked to a series of rabies cases springing up around the
country.
linked to a series of rabies cases springing up around the country.
</p>
<!-- ... -->
</article>`}</pre>
</article>`}
language="markup"
>
{({ 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>
<h2>What to expect from here on out</h2>
<p>
What follows from here is just a bunch of absolute nonsense I've written
Expand Down Expand Up @@ -101,17 +131,6 @@ const CommonTemplate = ({
like trash. Make it good then it won't be bad.
</p>
</blockquote>
<p>
It's probably important that images look okay here by default as well:
</p>
<figure>
<img src="hero-14.jpg" alt="" />
<figcaption>
Contrary to popular belief, Lorem Ipsum is not simply random text. It
has roots in a piece of classical Latin literature from 45 BC, making
it over 2000 years old.
</figcaption>
</figure>
<p>
Now I'm going to show you an example of an unordered list to make sure
that looks good, too:
Expand Down

0 comments on commit 4d35f42

Please sign in to comment.