markdoc partials (#7743)

* new: partials

* chore: content reshuffling

* Revert "chore: content reshuffling"

This reverts commit 3d3864d.

* edit: Markdoc Partials naming

Co-authored-by: Sarah Rainsberger <[email protected]>

* edit: reorg partial example

Co-authored-by: Sarah Rainsberger <[email protected]>

* edit: footer file attribute

* nit: extra space

Co-authored-by: Sarah Rainsberger <[email protected]>

* edit: add ./ and mention import aliases

---------

Co-authored-by: Sarah Rainsberger <[email protected]>

src/content/docs/en/guides/integrations-guide/markdoc.mdx

@@ -209,6 +209,34 @@ All Markdown headings will render the `Heading.astro` component and pass the fol
 
 For example, the heading `### Level 3 heading!` will pass `level: 3` and `id: 'level-3-heading'` as component props.
 
+### Markdoc Partials
+
+The `{% partial %}` tag allows you to render other `.mdoc` files inside your Markdoc content.
+
+This is useful for reusing content across multiple documents, and allows you to have `.mdoc` content files that do not follow your collection schema.
+
+:::tip
+Use an underscore `_` prefix for partial files or directories. This excludes partials from content collection queries.
+:::
+
+This example shows a Markdoc partial for a footer to be used inside blog collection entries:
+
+```md title="src/content/blog/_footer.mdoc"
+Social links:
+
+- [Twitter / X](https://twitter.com/astrodotbuild)
+- [Discord](https://astro.build/chat)
+- [GitHub](https://github.com/withastro/astro)
+```
+
+Use the `{% partial %}` tag with to render the footer at the bottom of a blog post entry. Apply the `file` attribute with the path to the file, using either a relative path or an import alias:
+
+```md title="src/content/blog/post.mdoc" ins='file="_footer.mdoc"'
+# My Blog Post
+
+{% partial file="./_footer.mdoc" %}
+```
+
 ### Syntax highlighting
 
 `@astrojs/markdoc` provides [Shiki](https://shiki.style) and [Prism](https://github.com/PrismJS) extensions to highlight your code blocks.