chore: better docs

.vscode/settings.json

@@ -1,3 +1,12 @@
 {
-	"typescript.tsdk": "node_modules/typescript/lib"
+	"typescript.tsdk": "node_modules/typescript/lib",
+	// This is the greatest improvement in your editing experience.
+	// If your vscode isn't already formatting on save, you're missing out.
+	"editor.formatOnSave": true,
+
+	"tailwindCSS.experimental.classRegex": [
+		["clsx\\(([^)]*)\\)", "(?:'|\"|`)([^']*)(?:'|\"|`)"],
+		["cn\\(([^)]*)\\)", "(?:'|\"|`)([^']*)(?:'|\"|`)"],
+		["tw`([^`]*)"]
+	]
 }

apps/docs/app/README.mdx

@@ -1,4 +1,5 @@
 import { Hx, HxBoundary } from "uberschrift";
+import { Clipboardable } from "./components/Clipboardable";
 
 <Hx>🧢 uberschrift</Hx>
 
@@ -26,22 +27,13 @@ Zero-dependeny magic heading levels for React
 
 ---
 
-<div className="text-center">
-
-Sponsors <br/>
-[<img alt="Peerigon logo" src="https://assets.peerigon.com/peerigon/logo/peerigon-logo-flat-spinat.png" width="150" />](https://peerigon.com)
-
-</div>
-
----
-
 <HxBoundary>
 
 <Hx>🤸 Motivation</Hx>
 
 <HxBoundary>
 
-<Hx>👀 Why chosing the right heading level (h1, h2, …) matters</Hx>
+<Hx>👀 Why heading levels (h1, h2, …) matter</Hx>
 
 Grouping text sections underneath headings adds a logical hierarchy to the contents of a page, contributing to both accessibility and search engine optimization (SEO). Heading elements, ranging from `<h1>` to `<h6>`, represent different levels of importance and organization.
 
@@ -52,18 +44,18 @@ Properly nesting these elements ensures that screen readers and other assistive
 Here's an example of a DOM structure with incorrect heading order:
 
 ```html
-<h1>This is the page's main heading</h1>
+<h1>This is the page's main heading ✅</h1>
 
-<h2>This is also fine</h2>
+<h2>This is also fine ✅</h2>
 
-<h4>⚠️ UH-OH! This should have been preceded by an h3!</h4>
+<h4>This should have been preceded by an h3! ❌</h4>
 ```
 
 <Hx>🤷 Why is dealing with heading levels difficult?</Hx>
 
 In React projects, component encapsulation often makes chosing the right heading level within these components hard. They are often nested in an unforeseeable way, so the heading you chose to be an `<h3>` could now be used outside of the boundary of an `<h2>`, messing up the order.
 
-<Hx>🧢 What does uberschrift do?</Hx>
+<Hx>🧢 How does uberschrift help?</Hx>
 
 uberschrift provides you with two components: one we call `<Hx>` (as in "heading level x") that you should use for your headings; and one `<HxBoundary>` that you use to structure your document. Within these boundaries, `<Hx>` always choses the correct heading level. If you need to structure your document one level deeper, you wrap your component in a new `<HxBoundary>`.
 
@@ -75,16 +67,35 @@ uberschrift provides you with two components: one we call `<Hx>` (as in "heading
 
 <Hx>🛠️ Usage</Hx>
 
+<Clipboardable content="npm install uberschrift">
 ```sh
 npm install uberschrift
 ```
+</Clipboardable>
 
 <HxBoundary>
 
 <Hx>📇 Example</Hx>
 
 `page.tsx`:
 
+<Clipboardable content={`import { Hx, HxBoundary } from "uberschrift";
+
+<Hx>Outside of the top level: this will be an h1</Hx>
+
+<HxBoundary>
+  <Hx>Within the top level: this will be an h2</Hx>
+
+  <HxBoundary>
+    <Hx>Within the 2nd level: this will be an h3</Hx>
+
+    <HxBoundary>
+      <Hx>Within the 3rd level: this will be an h4</Hx>
+    </HxBoundary>
+
+    <Hx>Again within the 2nd level: this will be an h3</Hx>
+  </HxBoundary>
+</HxBoundary>`}>
 ```tsx
 import { Hx, HxBoundary } from "uberschrift";
 
@@ -104,6 +115,7 @@ import { Hx, HxBoundary } from "uberschrift";
   </HxBoundary>
 </HxBoundary>
 ```
+</Clipboardable>
 
 renders as:
 
@@ -129,15 +141,30 @@ That being said: if you find yourself nesting deeper, you can make that possible
 
 If you want to style these elements, you can do it like this:
 
+<Clipboardable content={`[aria-level="7"] {
+	font-weight: bold;
+}`}>
 ```css
 [aria-level="7"] {
 	font-weight: bold;
 }
 ```
+</Clipboardable>
 
 <Hx>🚗 How does it work under the hood?</Hx>
 
 It's a simple case of [React Context](https://react.dev/learn/passing-data-deeply-with-context): `HxBoundary` is merely a nestable context provider, that increments the heading level.
 
 </HxBoundary>
+
+---
+
+<Hx>❤️ Sponsors</Hx>
+
+[<img className="inline" alt="Peerigon GmbH" src="https://assets.peerigon.com/peerigon/logo/peerigon-logo-flat-spinat.png" width="150" />](https://peerigon.com)
+
 </HxBoundary>
+
+---
+
+[Legal Notice](https://www.peerigon.com/en/legal/)

apps/docs/app/components/clipboardable.tsx

@@ -0,0 +1,46 @@
+import React, { ReactNode, useEffect } from "react";
+import { SvgSprite } from "./svg-sprite";
+
+export const Clipboardable: React.FC<{
+	children?: ReactNode;
+	content: string;
+}> = ({ children, content }) => {
+	const [copied, setCopied] = React.useState(false);
+	// eslint-disable-next-line consistent-return
+	useEffect(() => {
+		if (copied) {
+			const timer = setTimeout(() => {
+				setCopied(false);
+			}, 3000);
+			return () => clearTimeout(timer);
+		}
+	}, [copied]);
+
+	return (
+		<div className="relative">
+			<button
+				type="button"
+				className="absolute right-2 top-[0.75rem] w-7 aspect-square rounded-md flex justify-center items-center bg-slate-600"
+				onClick={() => {
+					navigator.clipboard.writeText(content);
+					setCopied(true);
+				}}
+			>
+				{copied ? (
+					<SvgSprite
+						className="w-4 h-auto text-green-400"
+						aria-hidden="true"
+						name="check"
+					/>
+				) : (
+					<SvgSprite
+						className="w-4 h-auto text-white"
+						aria-hidden="true"
+						name="copy"
+					/>
+				)}
+			</button>
+			{children}
+		</div>
+	);
+};

apps/docs/app/components/ribbon.tsx

@@ -0,0 +1,24 @@
+import { cn, tw } from "../utils/tailwind";
+import { SvgSprite } from "./svg-sprite";
+
+const className = cn(
+	tw`bg-black text-sm font-bold text-white fixed top-0 right-0 p-2 z-50 w-[16rem] flex no-underline leading-normal justify-center rotate-45 transform translate-x-1/4 translate-y-full`,
+	tw`hover:bg-gray-900 hover:text-white hover:scale-110 transition-transform`,
+);
+
+export const Ribbon = () => {
+	return (
+		<a
+			href="https://github.com/peerigon/uberschrift/"
+			className={className}
+			aria-label="View source on GitHub"
+		>
+			<SvgSprite
+				className="w-5 h-5 mr-3"
+				aria-hidden="true"
+				name="github"
+			/>
+			GitHub
+		</a>
+	);
+};

apps/docs/app/components/svg-sprite.tsx

@@ -0,0 +1,17 @@
+import { SVGProps } from "react";
+
+type Props = {
+	name: string;
+};
+
+export const SvgSprite: React.FC<Props & SVGProps<SVGSVGElement>> = ({
+	name,
+	className,
+	...props
+}) => {
+	return (
+		<svg className={className} {...props}>
+			<use href={`/sprite.svg#${name}`} />
+		</svg>
+	);
+};

apps/docs/app/routes/_index.tsx

@@ -1,7 +1,9 @@
 import type { MetaFunction, LinksFunction } from "@remix-run/node";
 
+import highlightCss from "highlight.js/styles/github-dark.css";
 import ReadMe from "../README.mdx";
 import stylesheet from "../tailwind.css";
+import { Ribbon } from "../components/ribbon";
 
 export const meta: MetaFunction = () => {
 	return [
@@ -16,6 +18,7 @@ export const meta: MetaFunction = () => {
 export const links: LinksFunction = () => {
 	return [
 		{ rel: "stylesheet", href: stylesheet },
+		{ rel: "stylesheet", href: highlightCss },
 		{
 			rel: "icon",
 			href: "data:image/svg+xml,<svg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 100 100%22><text y=%22.9em%22 font-size=%2290%22>🧢</text></svg>",
@@ -25,8 +28,9 @@ export const links: LinksFunction = () => {
 
 const Index = () => {
 	return (
-		<main className="flex gap-4 flex-col py-4 lg:py-12 max-w-screen-sm m-auto">
+		<main className="prose lg:prose-xl py-4 lg:py-12 max-w-screen-md m-auto">
 			<ReadMe />
+			<Ribbon />
 		</main>
 	);
 };

apps/docs/app/tailwind.css

@@ -2,37 +2,6 @@
 @tailwind components;
 @tailwind utilities;
 
-h1,
-h2,
-h3 {
-	font-weight: 700;
-}
-
-h1 {
-	font-size: 2rem;
-}
-h2 {
-	font-size: 1.5rem;
-}
-h3 {
-	font-size: 1.25rem;
-}
-
-code {
-	font-size: 0.9em;
-	color: #333;
-}
-
-code[class^="language-"] {
-	display: block;
-	padding: 1rem;
-	border-radius: 1rem;
-	background-color: rgba(0, 0, 0, 0.05);
-}
-
-hr {
-	border: 0;
-	border-top: 1px solid rgba(0, 0, 0, 0.1);
-	border-bottom: 1px solid rgba(0, 0, 0, 0.25);
-	margin: 2rem 0;
+code.hljs {
+	background: transparent !important;
 }

apps/docs/app/utils/tailwind.ts

@@ -0,0 +1,5 @@
+import clsx from "clsx";
+
+export const tw = String.raw;
+
+export const cn = clsx;

apps/docs/package.json

@@ -16,10 +16,13 @@
 		"@remix-run/node": "^2.4.1",
 		"@remix-run/react": "^2.4.1",
 		"@remix-run/serve": "^2.4.1",
-		"uberschrift": "*",
+		"@tailwindcss/typography": "^0.5.10",
+		"clsx": "^2.1.0",
 		"isbot": "^3.8.0",
 		"react": "^18.2.0",
-		"react-dom": "^18.2.0"
+		"react-dom": "^18.2.0",
+		"rehype-highlight": "^7.0.0",
+		"uberschrift": "*"
 	},
 	"devDependencies": {
 		"@remix-run/dev": "^2.4.1",

apps/docs/remix.config.js

@@ -1,5 +1,14 @@
 /** @type {import('@remix-run/dev').AppConfig} */
+
 export default {
 	ignoredRouteFiles: ["**/.*"],
 	serverDependenciesToBundle: [/@uberschrift\/.*/, "uberschrift"],
+	mdx: async (filename) => {
+		const [rehypeHighlight] = await Promise.all([
+			import("rehype-highlight").then((mod) => mod.default),
+		]);
+		return {
+			rehypePlugins: [rehypeHighlight],
+		};
+	},
 };

apps/docs/tailwind.config.ts

@@ -1,9 +1,7 @@
 import type { Config } from "tailwindcss";
+import typography from "@tailwindcss/typography";
 
 export default {
-	content: ["./app/**/*.{js,jsx,ts,tsx}"],
-	theme: {
-		extend: {},
-	},
-	plugins: [],
+	content: ["./app/**/*.{js,jsx,ts,tsx,mdx}"],
+	plugins: [typography],
 } satisfies Config;