Components documentation improvements (#2121)

Co-authored-by: Chris Swithinbank <357379+delucis@users.noreply.github.com>
Co-authored-by: Yan <61414485+yanthomasdev@users.noreply.github.com>
Co-authored-by: Lorenzo Lewis <lorenzo_lewis@icloud.com>
Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>

@lunaria-ignore:src/content/docs/pt-pt/getting-started.mdx;src/content/docs/uk/getting-started.mdx;src/content/docs/es/getting-started.mdx;src/content/docs/fr/getting-started.mdx;src/content/docs/hi/getting-started.mdx;src/content/docs/id/getting-started.mdx;src/content/docs/it/getting-started.mdx;src/content/docs/ja/getting-started.mdx;src/content/docs/ko/getting-started.mdx;src/content/docs/pt-br/getting-started.mdx;src/content/docs/ru/getting-started.mdx;src/content/docs/tr/getting-started.mdx;src/content/docs/zh-cn/getting-started.mdx

docs/astro.config.mjs

@@ -1,6 +1,7 @@
 import { defineConfig } from 'astro/config';
 import starlight from '@astrojs/starlight';
 import starlightLinksValidator from 'starlight-links-validator';
+import markdocGrammar from './grammars/markdoc.tmLanguage.json';
 
 export const locales = {
 	root: { label: 'English', lang: 'en' },
@@ -130,6 +131,13 @@ export default defineConfig({
 					},
 					autogenerate: { directory: 'guides' },
 				},
+				{
+					label: 'Components',
+					translations: {
+						fr: 'Composants',
+					},
+					autogenerate: { directory: 'components' },
+				},
 				{
 					label: 'Reference',
 					translations: {
@@ -162,6 +170,7 @@ export default defineConfig({
 					autogenerate: { directory: 'resources' },
 				},
 			],
+			expressiveCode: { shiki: { langs: [markdocGrammar] } },
 			plugins: process.env.CHECK_LINKS
 				? [
 						starlightLinksValidator({

docs/grammars/README.md

@@ -0,0 +1,34 @@
+# Starlight Docs Grammars
+
+This directory contains additional grammars for the Starlight documentation website.
+
+## Grammars
+
+The following additional grammars are generated and available for use:
+
+- [Markdoc](https://github.com/markdoc/language-server)
+
+## Usage
+
+To generate the grammars from their source files, run:
+
+```sh
+pnpm grammars
+```
+
+To include the grammars in the Starlight documentation website, update the `expressiveCode.shiki.langs` array in the `astro.config.mjs` file:
+
+```diff
+starlight({
+  expressiveCode: {
+    shiki: {
+      langs: [
+        JSON.parse(
+          fs.readFileSync('./grammars/existing.tmLanguage.json', 'utf-8'),
++         fs.readFileSync('./grammars/new.tmLanguage.json', 'utf-8'),
+        ),
+      ],
+    },
+  },
+});
+```

docs/grammars/generate.mjs

@@ -0,0 +1,74 @@
+// @ts-check
+
+import fs from 'node:fs/promises';
+
+const markdown = {
+	repo: 'shikijs/textmate-grammars-themes',
+	tmLanguagePath: 'packages/tm-grammars/grammars/markdown.json',
+};
+
+const markdoc = {
+	repo: 'markdoc/language-server',
+	// We don't need the Markdoc grammar, only the Markdoc Markdown grammar.
+	// tmLanguagePath: 'syntaxes/markdoc.tmLanguage.json',
+	markdownTmLanguagePath: 'syntaxes/markdoc.markdown.tmLanguage.json',
+};
+
+/**
+ * Download a TextMate grammar file from a GitHub repository.
+ * @param {string} repo
+ * @param {string} path
+ */
+async function fetchTmLanguage(repo, path) {
+	const url = `https://raw.githubusercontent.com/${repo}/main/${path}`;
+	const response = await fetch(url);
+	const data = await response.json();
+	return data;
+}
+
+// Download the TextMate grammar files for Markdown.
+const markdownTmLanguage = await fetchTmLanguage(markdown.repo, markdown.tmLanguagePath);
+
+// Download the TextMate grammar files for Markdoc Markdown.
+const markdocMarkdownTmLanguage = await fetchTmLanguage(
+	markdoc.repo,
+	markdoc.markdownTmLanguagePath
+);
+
+// Reference: https://macromates.com/manual/en/language_grammars
+
+// Update the name and scope name for the Markdoc grammar.
+markdownTmLanguage.name = 'markdoc';
+markdownTmLanguage.scopeName = 'text.html.markdoc';
+
+// Merge the Markdown and Markdoc Markdown grammar repositories.
+markdownTmLanguage.repository = {
+	...markdownTmLanguage.repository,
+	...markdocMarkdownTmLanguage.repository,
+};
+
+// Include the Markdoc Markdown grammar rules at the beginning of the Markdown grammar.
+for (const rule of Object.keys(markdocMarkdownTmLanguage.repository)) {
+	// Skip shortcut rules as they break syntax highlighting of child content that includes dots in
+	// words and we don't ever use them.
+	if (rule === 'shortcut') continue;
+
+	markdownTmLanguage.repository.block.patterns.unshift({ include: `#${rule}` });
+	markdownTmLanguage.repository.inline.patterns.unshift({ include: `#${rule}` });
+}
+
+// Write the grammar to a file.
+await fs.writeFile(
+	'./grammars/markdoc.tmLanguage.json',
+	JSON.stringify(
+		markdownTmLanguage,
+		(key, value) => {
+			// The `applyEndPatternLast` property should be a boolean and not a number.
+			if (key === 'applyEndPatternLast') return Boolean(value);
+			return value;
+		},
+		2
+	)
+);
+
+console.log('Markdoc grammar generated successfully.');