Add Markdoc preset and example (#2249)

Co-authored-by: Chris Swithinbank <[email protected]>
Co-authored-by: Chris Swithinbank <[email protected]>

.changeset/selfish-chefs-tie.md

@@ -0,0 +1,7 @@
+---
+'@astrojs/starlight-markdoc': minor
+---
+
+Adds Starlight Markdoc preset.
+
+See the [“Markdoc”](https://starlight.astro.build/guides/authoring-content/#markdoc) guide to learn more on how to use this preset in a new or existing project.

.github/labeler.yml

@@ -26,5 +26,8 @@ i18n:
 '🌟 tailwind':
   - packages/tailwind/**
 
+'🌟 markdoc':
+  - packages/markdoc/**
+
 '📚 docs':
   - docs/**

docs/src/content/docs/guides/authoring-content.md → docs/src/content/docs/guides/authoring-content.mdx

@@ -203,17 +203,17 @@ A code block is indicated by a block with three backticks <code>```</code> at th
 ```js
 // Javascript code with syntax highlighting.
 var fun = function lang(l) {
-  dateformat.i18n = require('./lang/' + l);
-  return true;
+	dateformat.i18n = require('./lang/' + l);
+	return true;
 };
 ```
 
 ````md
 ```js
 // Javascript code with syntax highlighting.
 var fun = function lang(l) {
-  dateformat.i18n = require('./lang/' + l);
-  return true;
+	dateformat.i18n = require('./lang/' + l);
+	return true;
 };
 ```
 ````
@@ -241,16 +241,16 @@ Some of the most common examples are shown below:
 
   ```js {2-3}
   function demo() {
-    // This line (#2) and the next one are highlighted
-    return 'This is line #3 of this snippet';
+  	// This line (#2) and the next one are highlighted
+  	return 'This is line #3 of this snippet';
   }
   ```
 
   ````md
   ```js {2-3}
   function demo() {
-    // This line (#2) and the next one are highlighted
-    return 'This is line #3 of this snippet';
+  	// This line (#2) and the next one are highlighted
+  	return 'This is line #3 of this snippet';
   }
   ```
   ````
@@ -260,15 +260,15 @@ Some of the most common examples are shown below:
   ```js "Individual terms" /Even.*supported/
   // Individual terms can be highlighted, too
   function demo() {
-    return 'Even regular expressions are supported';
+  	return 'Even regular expressions are supported';
   }
   ```
 
   ````md
   ```js "Individual terms" /Even.*supported/
   // Individual terms can be highlighted, too
   function demo() {
-    return 'Even regular expressions are supported';
+  	return 'Even regular expressions are supported';
   }
   ```
   ````
@@ -277,18 +277,18 @@ Some of the most common examples are shown below:
 
   ```js "return true;" ins="inserted" del="deleted"
   function demo() {
-    console.log('These are inserted and deleted marker types');
-    // The return statement uses the default marker type
-    return true;
+  	console.log('These are inserted and deleted marker types');
+  	// The return statement uses the default marker type
+  	return true;
   }
   ```
 
   ````md
   ```js "return true;" ins="inserted" del="deleted"
   function demo() {
-    console.log('These are inserted and deleted marker types');
-    // The return statement uses the default marker type
-    return true;
+  	console.log('These are inserted and deleted marker types');
+  	// The return statement uses the default marker type
+  	return true;
   }
   ```
   ````
@@ -393,3 +393,118 @@ Starlight supports all other Markdown authoring syntax, such as lists and tables
 ## Advanced Markdown and MDX configuration
 
 Starlight uses Astro’s Markdown and MDX renderer built on remark and rehype. You can add support for custom syntax and behavior by adding `remarkPlugins` or `rehypePlugins` in your Astro config file. See [“Configuring Markdown and MDX”](https://docs.astro.build/en/guides/markdown-content/#configuring-markdown-and-mdx) in the Astro docs to learn more.
+
+## Markdoc
+
+Starlight supports authoring content in Markdoc using the experimental [Astro Markdoc integration](https://docs.astro.build/en/guides/integrations-guide/markdoc/) and the Starlight Markdoc preset.
+
+### Create a new project with Markdoc
+
+Start a new Starlight project with Markdoc pre-configured using `create astro`:
+
+import { Tabs, TabItem, Steps } from '@astrojs/starlight/components';
+
+<Tabs syncKey="pkg">
+<TabItem label="npm">
+
+```sh
+npm create astro@latest -- --template starlight/markdoc
+```
+
+</TabItem>
+<TabItem label="pnpm">
+
+```sh
+pnpm create astro --template starlight/markdoc
+```
+
+</TabItem>
+<TabItem label="Yarn">
+
+```sh
+yarn create astro --template starlight/markdoc
+```
+
+</TabItem>
+</Tabs>
+
+### Add Markdoc to an existing project
+
+If you already have a Starlight site and want to add Markdoc, follow these steps.
+
+<Steps>
+
+1.  Add Astro’s Markdoc integration:
+
+    <Tabs syncKey="pkg">
+
+    <TabItem label="npm">
+
+    ```sh
+    npx astro add markdoc
+    ```
+
+    </TabItem>
+
+    <TabItem label="pnpm">
+
+    ```sh
+    pnpm astro add markdoc
+    ```
+
+    </TabItem>
+
+    <TabItem label="Yarn">
+
+    ```sh
+    yarn astro add markdoc
+    ```
+
+    </TabItem>
+
+    </Tabs>
+
+2.  Install the Starlight Markdoc preset:
+
+    <Tabs syncKey="pkg">
+
+    <TabItem label="npm">
+
+    ```sh
+    npm install @astrojs/starlight-markdoc
+    ```
+
+    </TabItem>
+
+    <TabItem label="pnpm">
+
+    ```sh
+    pnpm add @astrojs/starlight-markdoc
+    ```
+
+    </TabItem>
+
+    <TabItem label="Yarn">
+
+    ```sh
+    yarn add @astrojs/starlight-markdoc
+    ```
+
+    </TabItem>
+
+    </Tabs>
+
+3.  Create a Markdoc configuration file at `markdoc.config.mjs` and use the Starlight Markdoc preset:
+
+    ```js
+    import { defineMarkdocConfig } from '@astrojs/markdoc/config';
+    import starlightMarkdoc from '@astrojs/starlight-markdoc';
+
+    export default defineMarkdocConfig({
+    	extends: [starlightMarkdoc()],
+    });
+    ```
+
+</Steps>
+
+To learn more about the Markdoc syntax and features, see the [Markdoc documentation](https://markdoc.dev/docs/syntax) or the [Astro Markdoc integration guide](https://docs.astro.build/en/guides/integrations-guide/markdoc/).

docs/src/content/docs/guides/pages.mdx

@@ -14,7 +14,7 @@ This guide shows how page generation works in Starlight.
 ### File formats
 
 Starlight supports authoring content in Markdown and MDX with no configuration required.
-You can add support for Markdoc by installing the experimental [Astro Markdoc integration](https://docs.astro.build/en/guides/integrations-guide/markdoc/).
+You can add support for Markdoc by following the [“Markdoc” guide](/guides/authoring-content/#markdoc).
 
 ### Add pages
 

examples/markdoc/.gitignore

@@ -0,0 +1,21 @@
+# build output
+dist/
+# generated types
+.astro/
+
+# dependencies
+node_modules/
+
+# logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+
+# environment variables
+.env
+.env.production
+
+# macOS-specific files
+.DS_Store

examples/markdoc/.vscode/extensions.json

@@ -0,0 +1,4 @@
+{
+  "recommendations": ["astro-build.astro-vscode", "stripe.markdoc-language-support"],
+  "unwantedRecommendations": []
+}

examples/markdoc/.vscode/launch.json

@@ -0,0 +1,11 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "command": "./node_modules/.bin/astro dev",
+      "name": "Development server",
+      "request": "launch",
+      "type": "node-terminal"
+    }
+  ]
+}

examples/markdoc/README.md

@@ -0,0 +1,56 @@
+# Starlight Starter Kit: Markdoc
+
+[![Built with Starlight](https://astro.badg.es/v2/built-with-starlight/tiny.svg)](https://starlight.astro.build)
+
+```
+npm create astro@latest -- --template starlight/markdoc
+```
+
+[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/withastro/starlight/tree/main/examples/markdoc)
+[![Open with CodeSandbox](https://assets.codesandbox.io/github/button-edit-lime.svg)](https://codesandbox.io/p/sandbox/github/withastro/starlight/tree/main/examples/markdoc)
+[![Deploy to Netlify](https://www.netlify.com/img/deploy/button.svg)](https://app.netlify.com/start/deploy?repository=https://github.com/withastro/starlight&create_from_path=examples/markdoc)
+[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fwithastro%2Fstarlight%2Ftree%2Fmain%2Fexamples%2Fmarkdoc&project-name=my-starlight-docs&repository-name=my-starlight-docs)
+
+> 🧑‍🚀 **Seasoned astronaut?** Delete this file. Have fun!
+
+## 🚀 Project Structure
+
+Inside of your Astro + Starlight project, you'll see the following folders and files:
+
+```
+.
+├── public/
+├── src/
+│   ├── assets/
+│   ├── content/
+│   │   ├── docs/
+│   │   └── config.ts
+│   └── env.d.ts
+├── astro.config.mjs
+├── markdoc.config.mjs
+├── package.json
+└── tsconfig.json
+```
+
+Starlight looks for `.md`, `.mdx` or `.mdoc` files in the `src/content/docs/` directory. Each file is exposed as a route based on its file name.
+
+Images can be added to `src/assets/` and embedded in Markdown with a relative link.
+
+Static assets, like favicons, can be placed in the `public/` directory.
+
+## 🧞 Commands
+
+All commands are run from the root of the project, from a terminal:
+
+| Command                   | Action                                           |
+| :------------------------ | :----------------------------------------------- |
+| `npm install`             | Installs dependencies                            |
+| `npm run dev`             | Starts local dev server at `localhost:4321`      |
+| `npm run build`           | Build your production site to `./dist/`          |
+| `npm run preview`         | Preview your build locally, before deploying     |
+| `npm run astro ...`       | Run CLI commands like `astro add`, `astro check` |
+| `npm run astro -- --help` | Get help using the Astro CLI                     |
+
+## 👀 Want to learn more?
+
+Check out [Starlight’s docs](https://starlight.astro.build/), read [the Astro documentation](https://docs.astro.build), or jump into the [Astro Discord server](https://astro.build/chat).

examples/markdoc/astro.config.mjs

@@ -0,0 +1,29 @@
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+import markdoc from '@astrojs/markdoc';
+
+// https://astro.build/config
+export default defineConfig({
+	integrations: [
+		markdoc(),
+		starlight({
+			title: 'My Docs',
+			social: {
+				github: 'https://github.com/withastro/starlight',
+			},
+			sidebar: [
+				{
+					label: 'Guides',
+					items: [
+						// Each item here is one entry in the navigation menu.
+						{ label: 'Example Guide', slug: 'guides/example' },
+					],
+				},
+				{
+					label: 'Reference',
+					autogenerate: { directory: 'reference' },
+				},
+			],
+		}),
+	],
+});

examples/markdoc/markdoc.config.mjs

@@ -0,0 +1,7 @@
+import { defineMarkdocConfig } from '@astrojs/markdoc/config';
+import starlightMarkdoc from '@astrojs/starlight-markdoc';
+
+// https://docs.astro.build/en/guides/integrations-guide/markdoc/
+export default defineMarkdocConfig({
+	extends: [starlightMarkdoc()],
+});

examples/markdoc/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@example/starlight-markdoc",
+  "type": "module",
+  "version": "0.0.1",
+  "private": true,
+  "scripts": {
+    "dev": "astro dev",
+    "start": "astro dev",
+    "build": "astro build",
+    "preview": "astro preview",
+    "astro": "astro"
+  },
+  "dependencies": {
+    "@astrojs/markdoc": "^0.11.4",
+    "@astrojs/starlight": "^0.26.1",
+    "@astrojs/starlight-markdoc": "^0.0.1",
+    "astro": "^4.15.3",
+    "sharp": "^0.32.5"
+  }
+}

examples/markdoc/src/content/config.ts

@@ -0,0 +1,6 @@
+import { defineCollection } from 'astro:content';
+import { docsSchema } from '@astrojs/starlight/schema';
+
+export const collections = {
+	docs: defineCollection({ schema: docsSchema() }),
+};