From c03c63e7e1e23ae51eca6f54323aae721156793b Mon Sep 17 00:00:00 2001
From: Mike Fix <mfix@stripe.com>
Date: Thu, 29 Aug 2024 09:35:15 -0700
Subject: [PATCH 1/2] document format

---
 components/Shell/SideNav.js |  3 +-
 pages/docs/format.md        | 60 +++++++++++++++++++++++++++++++++++++
 2 files changed, 62 insertions(+), 1 deletion(-)
 create mode 100644 pages/docs/format.md

diff --git a/components/Shell/SideNav.js b/components/Shell/SideNav.js
index fc7bb744..d0746b24 100644
--- a/components/Shell/SideNav.js
+++ b/components/Shell/SideNav.js
@@ -45,7 +45,8 @@ const items = [
     title: 'Advanced concepts',
     links: [
       { href: '/docs/frontmatter', children: 'Frontmatter' },
-      { href: '/docs/partials', children: 'Partials' }
+      { href: '/docs/partials', children: 'Partials' },
+      { href: '/docs/format', children: 'Formatting' }
     ]
   }
 ];
diff --git a/pages/docs/format.md b/pages/docs/format.md
new file mode 100644
index 00000000..8000cde0
--- /dev/null
+++ b/pages/docs/format.md
@@ -0,0 +1,60 @@
+---
+title: Formatting
+description:
+---
+
+# {% $markdoc.frontmatter.title %}
+
+Markdoc comes with the ability to take a Markdoc abstract syntax tree (AST) and generate the source content. This is useful for generating Markdoc files from data, or prettifying documents.
+
+## Examples
+
+Take for example you want to generate a Markdoc file from from some JSON:
+
+```json
+// ./data.json
+[
+  [34.0522, -118.2437],
+  [40.7128, -74.0060],
+  [48.8566, 2.3522]
+]
+```
+
+You can call `Markdoc.format` with an AST `Node` to generate the source content:
+
+{% sideBySide %}
+
+```js
+const Markdoc = require('@markdoc/markdoc')
+const DATA = require('./data.json')
+
+const list = new Markdoc.Ast.Node(
+  'list',
+  {ordered: false},
+  DATA.map(point => new Markdoc.Ast.Node(
+    'item',
+    {},
+    [
+      new Markdoc.Ast.Node('inline', {}, [
+        new Markdoc.Ast.Node(
+          'text', 
+          {content: point.join(', ')}, 
+          []
+        )
+      ])
+    ]
+  ))
+)
+
+Markdoc.format(list)
+```
+
+```md
+- 34.0522, -118.2437
+- 40.7128, -74.006
+- 48.8566, 2.3522
+```
+
+{% /sideBySide %}
+
+

From 211c6973d40fc6a7b3232bbfd529146730c859a6 Mon Sep 17 00:00:00 2001
From: Mike Fix <62121649+mfix-stripe@users.noreply.github.com>
Date: Thu, 29 Aug 2024 10:02:33 -0700
Subject: [PATCH 2/2] Update pages/docs/format.md

Co-authored-by: matv-stripe <55463370+matv-stripe@users.noreply.github.com>
---
 pages/docs/format.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/pages/docs/format.md b/pages/docs/format.md
index 8000cde0..a72c1f4f 100644
--- a/pages/docs/format.md
+++ b/pages/docs/format.md
@@ -1,6 +1,6 @@
 ---
 title: Formatting
-description:
+description: Use Markdoc.format to prettify documents or generate source content
 ---
 
 # {% $markdoc.frontmatter.title %}