From a4a7f994356d69eefdbd5e9b94067ae1553e13d6 Mon Sep 17 00:00:00 2001
From: bholmesdev <hey@bholmes.dev>
Date: Mon, 13 Feb 2023 18:29:10 -0500
Subject: [PATCH] docs: add usage and examples to Markdoc README

---
 packages/integrations/markdoc/README.md | 81 ++++++++++++++++++++++++-
 1 file changed, 78 insertions(+), 3 deletions(-)

diff --git a/packages/integrations/markdoc/README.md b/packages/integrations/markdoc/README.md
index 5ce034d09..5077d81bf 100644
--- a/packages/integrations/markdoc/README.md
+++ b/packages/integrations/markdoc/README.md
@@ -56,15 +56,88 @@ export default defineConfig({
 
 ## Usage
 
-TODO
+Markdoc files can be used within content collections. Add entries to any content collection using the `.mdoc` extension:
+
+```sh
+src/content/docs/
+  why-markdoc.mdoc
+  quick-start.mdoc
+```
+
+Then, query for these files using the [Content Collection APIs](https://docs.astro.build/en/guides/content-collections/#querying-collections):
+
+```astro
+---
+import { getEntryBySlug } from 'astro:content';
+
+const entry = await getEntryBySlug('docs', 'why-markdoc');
+const { Content } = await entry.render();
+---
+
+<!--Access frontmatter properties with `data`-->
+<h1>{entry.data.title}</h1>
+<!--Render Markdoc contents with the Content component-->
+<Content />
+```
+
+📚 See the [Astro Content Collection docs][astro-content-collections] for more information.
 
 ## Configuration
 
-TODO
+You can configure how your Markdoc content is rendered using props via the `Content` component. This component is returned by [a content collection `render()` result](https://docs.astro.build/en/guides/content-collections/#rendering-content-to-html).
+
+### `config` prop
+
+The `config` prop accepts all [Markdoc configuration options](https://markdoc.dev/docs/config#full-example), including tags and variables.
+
+This example defines a `version` variable to use within a `why-markdoc.mdoc` entry:
+
+```astro
+---
+import { getEntryBySlug } from 'astro:content';
+
+const entry = await getEntryBySlug('docs', 'why-markdoc');
+const { Content } = await entry.render();
+---
+
+<Content
+  config={{
+    variables: {
+      version: '0.0.1',
+    }
+  }}
+/>
+```
+
+### `components` prop
+
+The `components` prop defines mappings from an HTML element name to an Astro or UI framework component (React, Vue, Svelte, etc).
+
+:::note
+`components` does not support the `client:` directive for hydrating components. To embed client-side components, create a wrapper `.astro` file to import your component and apply a `client:` directive manually.
+:::
+
+This example renders all `h1` headings using a `Title` component:
+
+```astro
+---
+import { getEntryBySlug } from 'astro:content';
+import Title from '../components/Title.astro';
+
+const entry = await getEntryBySlug('docs', 'why-markdoc');
+const { Content } = await entry.render();
+---
+
+<Content
+  components={{
+    h1: Title,
+  }}
+/>
+```
 
 ## Examples
 
-TODO
+*   The [Astro Markdoc starter template](https://github.com/withastro/astro/tree/latest/examples/with-mdx) shows how to use Markdoc files in your Astro project.
 
 ## Troubleshooting
 
@@ -83,3 +156,5 @@ See [CHANGELOG.md](https://github.com/withastro/astro/tree/main/packages/integra
 [astro-integration]: https://docs.astro.build/en/guides/integrations-guide/
 
 [astro-ui-frameworks]: https://docs.astro.build/en/core-concepts/framework-components/#using-framework-components
+
+[astro-content-collections]: https://docs.astro.build/en/guides/content-collections/