Improve code blocks docs (#2047)

Co-authored-by: endigo9740 <gundamx9740@gmail.com>
skeletonlabs · Sep 22, 2023 · 9545045 · 9545045
1 parent 0b27cf4
commit 9545045
Show file tree

Hide file tree

Showing 13 changed files with 79 additions and 23 deletions.
diff --git a/packages/skeleton/src/lib/utilities/CodeBlock/CodeBlock.svelte b/packages/skeleton/src/lib/utilities/CodeBlock/CodeBlock.svelte
@@ -56,6 +56,7 @@
 	function languageFormatter(lang: string): string {
 		if (lang === 'js') return 'javascript';
 		if (lang === 'ts') return 'typescript';
+		if (lang === 'shell') return 'terminal';
 		return lang;
 	}
 

diff --git a/sites/skeleton.dev/src/routes/(inner)/docs/contributing/requirements/+page.svelte b/sites/skeleton.dev/src/routes/(inner)/docs/contributing/requirements/+page.svelte
@@ -190,17 +190,17 @@
 		<p>
 			To check for linting issues via <a class="anchor" href="https://prettier.io/" target="_blank" rel="noreferrer">Prettier</a>, run:
 		</p>
-		<CodeBlock language="console" code={`pnpm lint`} />
+		<CodeBlock language="shell" code={`pnpm lint`} />
 		<p>To automatically apply suggested linting changes, run:</p>
-		<CodeBlock language="console" code={`pnpm format`} />
+		<CodeBlock language="shell" code={`pnpm format`} />
 
 		<!-- Automated Tests -->
 		<h3 class="h3">Automated Tests</h3>
 		<p>
 			Tests are handled via <a class="anchor" href="https://vitest.dev/" target="_blank" rel="noreferrer">Vitest</a>, which is similar to
 			Jest. Make sure to run all tests before submitting new pull requests.
 		</p>
-		<CodeBlock language="console" code={`pnpm test`} />
+		<CodeBlock language="shell" code={`pnpm test`} />
 
 		<!-- Spell Checking -->
 		<h3 class="h3">Spell Checking</h3>
@@ -218,7 +218,7 @@
 			extension for VS Code. You can add words to the dictionary using this extension, or by editing <code class="code">cspell.json</code> at
 			the root of the repository.
 		</p>
-		<CodeBlock language="console" code={`pnpm cspell "**" --no-progress`} />
+		<CodeBlock language="shell" code={`pnpm cspell "**" --no-progress`} />
 	</section>
 
 	<!-- Dependencies -->

diff --git a/sites/skeleton.dev/src/routes/(inner)/docs/get-started/SectionInstall.svelte b/sites/skeleton.dev/src/routes/(inner)/docs/get-started/SectionInstall.svelte
@@ -18,7 +18,7 @@
 					install Tailwind, configure Skeleton, and more.
 				</p>
 				<CodeBlock
-					language="console"
+					language="shell"
 					code={`
 npm create skeleton-app@latest my-skeleton-app
 	- Enable Typescript when prompted (recommended)
@@ -31,7 +31,7 @@ cd my-skeleton-app
 					First we'll generate a new <a class="anchor" href="https://kit.svelte.dev/docs/creating-a-project" target="_blank" rel="noreferrer">SvelteKit project</a>. If you already have a SvelteKit project, skip to the next step.
 				</p>
 				<CodeBlock
-					language="console"
+					language="shell"
 					code={`
 npm create svelte@latest my-skeleton-app
 	- Enable Typescript when prompted (recommended)

diff --git a/sites/skeleton.dev/src/routes/(inner)/docs/get-started/SectionSkeleton.svelte b/sites/skeleton.dev/src/routes/(inner)/docs/get-started/SectionSkeleton.svelte
@@ -24,7 +24,7 @@
 				<p>
 					Install the packages for <a class="anchor" href="https://www.npmjs.com/package/@skeletonlabs/skeleton" target="_blank" rel="noreferrer">Skeleton</a> and the <a class="anchor" href="https://www.npmjs.com/package/@skeletonlabs/tw-plugin" target="_blank" rel="noreferrer">Skeleton Tailwind plugin</a>.
 				</p>
-				<CodeBlock language="console" code={`npm i -D @skeletonlabs/skeleton @skeletonlabs/tw-plugin`} />
+				<CodeBlock language="shell" code={`npm i -D @skeletonlabs/skeleton @skeletonlabs/tw-plugin`} />
 			{/if}
 		</svelte:fragment>
 	</TabGroup>

diff --git a/sites/skeleton.dev/src/routes/(inner)/docs/get-started/SectionTailwind.svelte b/sites/skeleton.dev/src/routes/(inner)/docs/get-started/SectionTailwind.svelte
@@ -29,7 +29,7 @@
 					<p>
 						<a class="anchor" href="https://github.com/svelte-add/tailwindcss" target="_blank" rel="noreferrer">Svelte-Add</a> automates the process of installing Tailwind in SvelteKit.
 					</p>
-					<CodeBlock language="console" code={`npx svelte-add@latest tailwindcss\nnpm install`} />
+					<CodeBlock language="shell" code={`npx svelte-add@latest tailwindcss\nnpm install`} />
 				</div>
 				<h3 class="h3">Tailwind Configuration</h3>
 				<p>
@@ -44,7 +44,7 @@
 					<svelte:fragment slot="panel">
 						{#if tabConfigFormat === 'ts'}
 							<p>For SvelteKit projects using Typescript, install the standard node type definitions.</p>
-							<CodeBlock language="console" code={`npm add -D @types/node`} />
+							<CodeBlock language="shell" code={`npm add -D @types/node`} />
 							<p>Then, setup your Tailwind configuration using the <code class="code">.ts</code> file extension.</p>
 							<CodeBlock
 								language="ts"

diff --git a/sites/skeleton.dev/src/routes/(inner)/docs/purgecss/+page.svelte b/sites/skeleton.dev/src/routes/(inner)/docs/purgecss/+page.svelte
@@ -55,7 +55,7 @@
             </p>
         </aside>
 		<h3 class="h3">Installation</h3>
-		<CodeBlock language="console" code={`npm i -D vite-plugin-tailwind-purgecss`} />
+		<CodeBlock language="shell" code={`npm i -D vite-plugin-tailwind-purgecss`} />
 		<h3 class="h3">Add to Vite</h3>
 		<p>Implement the following in <code class="code">vite.config.ts</code>, found in the root of your project.</p>
 		<CodeBlock

diff --git a/sites/skeleton.dev/src/routes/(inner)/docs/quickstart/+page.svelte b/sites/skeleton.dev/src/routes/(inner)/docs/quickstart/+page.svelte
@@ -17,7 +17,7 @@
 		<h2 class="h2">Get Started</h2>
 		<p>To begin, let's scaffold our project using the Skeleton CLI. Note that we've listed a couple required options for this guide.</p>
 		<CodeBlock
-			language="console"
+			language="shell"
 			code={`
 npm create skeleton-app@latest my-skeleton-app
 	- Enable SvelteKit's Typescript syntax

diff --git a/sites/skeleton.dev/src/routes/(inner)/docs/themes/+page.svelte b/sites/skeleton.dev/src/routes/(inner)/docs/themes/+page.svelte
@@ -269,7 +269,7 @@ body {
 						static font file assets to the <code class="code">/static/fonts</code> directory.
 					</p>
 					{#each activeFonts as f}
-						<CodeBlock language="plaintext" code={`/static/fonts/${f.file}`} />
+						<CodeBlock language="shell" code={`/static/fonts/${f.file}`} />
 					{/each}
 					<!-- 3 -->
 					<h3 class="h3" data-toc-ignore>3. Apply @font-face</h3>

diff --git a/sites/skeleton.dev/src/routes/(inner)/elements/forms/+page.svelte b/sites/skeleton.dev/src/routes/(inner)/elements/forms/+page.svelte
@@ -124,7 +124,7 @@
 			</p>
 			<!-- Written -->
 			<div class="flex-auto space-y-4">
-				<CodeBlock language="console" code={`npm install -D @tailwindcss/forms`} />
+				<CodeBlock language="shell" code={`npm install -D @tailwindcss/forms`} />
 				<p>
 					Prepend the <a class="anchor" href="https://github.com/tailwindlabs/tailwindcss-forms" target="_blank" rel="noreferrer"
 						>Tailwind Forms plugin</a

diff --git a/sites/skeleton.dev/src/routes/(inner)/utilities/codeblocks/+page.svelte b/sites/skeleton.dev/src/routes/(inner)/utilities/codeblocks/+page.svelte
@@ -48,12 +48,34 @@
 				<a class="anchor" href="https://highlightjs.org/" target="_blank" rel="noreferrer">Highlight.js</a> is a required dependency to enable
 				syntax highlighting.
 			</p>
-			<CodeBlock language="console" code={`npm install highlight.js`} />
+			<CodeBlock language="shell" code={`npm install highlight.js`} />
 		</section>
 		<section class="space-y-4">
 			<h2 class="h2">Configure Your Project</h2>
-			<p>Apply the following changes to your app's root component in <code class="code">/src/routes/+layout.svelte</code>.</p>
-			<CodeBlock language="ts" code={`import hljs from 'highlight.js';`} />
+			<p>
+				To reduce your bundle size, we'll only import and register select languages for (ex: HTML, CSS, JS, TS). Please refer to the
+				<a href="https://highlightjs.org/#usage" class="anchor" target="_blank">Highlight.js usage guide</a> for more instruction.
+			</p>
+			<CodeBlock
+				language="ts"
+				code={`
+import hljs from 'highlight.js/lib/core';\n
+// Import each language module you require
+import xml from 'highlight.js/lib/languages/xml'; // for HTML
+import css from 'highlight.js/lib/languages/css';
+import json from 'highlight.js/lib/languages/json';
+import javascript from 'highlight.js/lib/languages/javascript';
+import typescript from 'highlight.js/lib/languages/typescript';
+import shell from 'highlight.js/lib/languages/shell';\n
+// Register each imported language module
+hljs.registerLanguage('xml', xml); // for HTML
+hljs.registerLanguage('css', css);
+hljs.registerLanguage('json', json);
+hljs.registerLanguage('javascript', javascript);
+hljs.registerLanguage('typescript', typescript);
+hljs.registerLanguage('shell', shell);
+			`}
+			/>
 			<p>
 				Import any <a
 					class="anchor"
@@ -65,6 +87,27 @@
 			<CodeBlock language="ts" code={`import 'highlight.js/styles/github-dark.css';`} />
 			<p>Finally, import the CodeBlock's writable store and pass a referenced to Highlight.js.</p>
 			<CodeBlock language="ts" code={`import { storeHighlightJs } from '@skeletonlabs/skeleton';\n\nstoreHighlightJs.set(hljs);`} />
+			<p>
+				If you are using <a class="anchor" href="/docs/purgecss" target="_blank">PurgeCSS</a>, safelist the imported classes in
+				<code class="code">vite.config.ts</code> so that they will not be removed during the build.
+			</p>
+			<CodeBlock
+				language="ts"
+				code={`
+import { purgeCss } from 'vite-plugin-tailwind-purgecss';\n
+const config: UserConfig = {
+	plugins: [
+		sveltekit(),
+		purgeCss({
+			safelist: {
+				// any selectors that begin with "hljs-" will not be purged
+				greedy: [/^hljs-/],
+			},
+		}),
+	],
+};
+			`}
+			/>
 		</section>
 		<section class="space-y-4">
 			<h2 class="h2">Line Numbers</h2>
@@ -75,17 +118,17 @@
 			<CodeBlock lineNumbers language="html" code={`<p>\n\tThe quick brown fox jumped over the lazy dog.\n</p>`} />
 		</section>
 		<section class="space-y-4">
-			<h2 class="h2">Supported Languages</h2>
+			<h2 class="h2">Language</h2>
 			<!-- prettier-ignore -->
 			<p>
-				Syntax highlighting will appear when a valid <a class="anchor" href="https://github.com/highlightjs/highlight.js/blob/main/SUPPORTED_LANGUAGES.md" target="_blank" rel="noreferrer">language alias</a> is provided to the CodeBlock's <code class="code">language</code> prop.
+				Syntax highlighting will appear when a valid <a class="anchor" href="https://github.com/highlightjs/highlight.js/blob/main/SUPPORTED_LANGUAGES.md" target="_blank" rel="noreferrer">language alias</a> is provided to the Code Block's <code class="code">language</code> property. For common web languages we recommend the shorthand values: <code class="code">html</code>, <code class="code">css</code>, <code class="code">js</code>, <code class="code">ts</code>, and <code class="code">shell</code>.
 			</p>
 		</section>
 		<section class="space-y-4">
 			<h2 class="h2">Accessibility</h2>
 			<p>
-				Uses <code class="code">pre-wrap</code> by default to support keyboard-only navigation. Please be mindful of color contrast when customizing
-				the design.
+				Uses <code class="code">pre-wrap</code> by default to support keyboard-only navigation. Please be mindful of color contrast ratios when
+				customizing the design of your Code Block components.
 			</p>
 		</section>
 	</svelte:fragment>

diff --git a/sites/skeleton.dev/src/routes/(inner)/utilities/popups/+page.svelte b/sites/skeleton.dev/src/routes/(inner)/utilities/popups/+page.svelte
@@ -187,7 +187,7 @@ const popupFeatured: PopupSettings = {
 				To begin, install <a class="anchor" href="https://floating-ui.com/" target="_blank" rel="noreferrer">Floating UI</a> from NPM. This
 				is <u>required</u> for popups to function.
 			</p>
-			<CodeBlock language="console" code={`npm install @floating-ui/dom`} />
+			<CodeBlock language="shell" code={`npm install @floating-ui/dom`} />
 			<p>Import Floating UI into your application's root layout <code class="code">/src/routes/+layout.svelte</code>.</p>
 			<CodeBlock language="ts" code={`import { computePosition, autoUpdate, offset, shift, flip, arrow } from '@floating-ui/dom';`} />
 			<p>

diff --git a/sites/skeleton.dev/src/routes/+layout.svelte b/sites/skeleton.dev/src/routes/+layout.svelte
@@ -1,7 +1,19 @@
 <!-- Layout: (root) -->
 <script lang="ts">
 	// Dependency: Highlight JS
-	import hljs from 'highlight.js';
+	import hljs from 'highlight.js/lib/core';
+	import xml from 'highlight.js/lib/languages/xml';
+	import css from 'highlight.js/lib/languages/css';
+	import json from 'highlight.js/lib/languages/json';
+	import javascript from 'highlight.js/lib/languages/javascript';
+	import typescript from 'highlight.js/lib/languages/typescript';
+	import shell from 'highlight.js/lib/languages/shell';
+	hljs.registerLanguage('xml', xml);
+	hljs.registerLanguage('css', css);
+	hljs.registerLanguage('json', json);
+	hljs.registerLanguage('javascript', javascript);
+	hljs.registerLanguage('typescript', typescript);
+	hljs.registerLanguage('shell', shell);
 	import '$lib/styles/highlight-js.css';
 	import { storeHighlightJs } from '@skeletonlabs/skeleton';
 	storeHighlightJs.set(hljs);

diff --git a/sites/skeleton.dev/src/routes/blog/[slug]/+page.svelte b/sites/skeleton.dev/src/routes/blog/[slug]/+page.svelte
@@ -1,5 +1,5 @@
 <script lang="ts">
-	import hljs from 'highlight.js';
+	import hljs from 'highlight.js/lib/core';
 	import { onMount } from 'svelte';
 
 	// +page.ts