[WIP] Update IA and summary

components/Shell/SideNav.js

@@ -13,37 +13,35 @@ const items = [
     ]
   },
   {
-    title: 'Core concepts',
+    title: 'Core features',
     links: [
       { href: '/docs/syntax', children: 'Syntax and schema' },
       { href: '/docs/nodes', children: 'Nodes' },
       { href: '/docs/tags', children: 'Tags' },
       { href: '/docs/attributes', children: 'Attributes' },
       { href: '/docs/variables', children: 'Variables' },
       { href: '/docs/functions', children: 'Functions' },
-      {
-        href: '/docs/render',
-        children: 'Rendering'
-      },
+      { href: '/docs/configs', children: 'Configuration'},
+    ]
+  },
+  {
+    title: 'Techniques',
+    links: [
+      { href: '/docs/render',  children: 'Rendering' },
+      { href: '/docs/customization', children: 'Customization examples' },
+      { href: '/docs/frontmatter', children: 'Frontmatter' },
+      { href: '/docs/partials', children: 'Partials' },
       { href: '/docs/validation', children: 'Validation' }
     ]
   },
   {
     title: 'Integration guides',
     links: [
-      { href: '/docs/examples', children: 'Common examples' },
       { href: '/docs/examples/html', children: 'Using with HTML' },
       { href: '/docs/nextjs', children: 'Using with Next.js' },
       { href: '/docs/examples/react', children: 'Using with React' }
     ]
   },
-  {
-    title: 'Advanced concepts',
-    links: [
-      { href: '/docs/frontmatter', children: 'Frontmatter' },
-      { href: '/docs/partials', children: 'Partials' }
-    ]
-  }
 ];
 
 export function SideNav() {

pages/docs/attributes.md

@@ -7,6 +7,71 @@ description: Attributes are used to pass data to tags in Markdoc.
 
 Attributes let you pass data to Markdoc tags, similar to [HTML attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes) or [React props](https://reactjs.org/docs/components-and-props.html).
 
+You can pass values of type: `number`, `string`, `boolean`, JSON `array`, or JSON `object`, either directly or using [variables](/docs/variables). With a tag, you can use HTML-like syntax.
+
+{% markdoc-example %}
+
+```
+{% city
+   index=0
+   name="San Francisco"
+   deleted=false
+   coordinates=[1, 4, 9]
+   meta={id: "id_123"}
+   color=$color /%}
+```
+
+{% /markdoc-example %}
+
+To pass attributes to a node, you can't use the HTML-like syntax. Instead, use _annotation_ syntax. Put the attributes after the node, in their own set of `{%` and `%}`.
+
+{% markdoc-example %}
+
+```
+{% table %}
+
+- Function {% width="25%" %}
+- Returns  {% colspan=2 %}
+- Example  {% align=$side %}
+
+{% /table %}
+```
+
+{% /markdoc-example %}
+
+(Annotation syntax also works with tags. But it's required with nodes.)
+
+Strings within attributes must be double-quoted. If you want to include a literal double-quote in a string you can escape it with using \\".
+
+{% markdoc-example %}
+
+``` {% process=false %}
+{% data delimiter="\"" %}
+```
+
+{% /markdoc-example %}
+
+
+## Attribute shorthand 
+
+
+In either syntax, you can use `.my-class-name` and `#my-id` as shorthand for `class=my-class-name` and `id=my-id`.
+
+{% markdoc-example %}
+
+``` {% process=false %}
+# Examples {% #examples %}
+
+{% table .striped #exampletable %}
+- One 
+- Two
+- Three
+{% /table %}
+```
+
+{% /markdoc-example %}
+
+
 ## Defining attributes
 
 Markdoc lets you configure custom attribute types for each [tag](/docs/tags). Assigning a type to an attribute limits which values an attribute can pass to a tag and, as a result, which values create errors during [validation](/docs/validation).

pages/docs/configs.md

@@ -0,0 +1,94 @@
+---
+title: Configuration
+description: Config objects let you pass options to Markdoc.transform.
+---
+
+# {% $markdoc.frontmatter.title %}
+
+This table outlines the various options you can pass to `Markdoc.transform`. Each option adjusts how a document is [transformed](/docs/render#transform) and [rendered](/docs/render#render).
+
+{% table %}
+
+- Key
+- Type
+- Description
+
+---
+
+- [`nodes`](/docs/nodes)
+- {% code %}{ [nodeType: [NodeType](/docs/nodes#built-in-nodes)]: [Schema](https://github.com/markdoc/markdoc/blob/6bcb8a0c48a181ca9df577534d841280646cea09/src/types.ts#L94-L101) }{% /code%}
+- Register [custom nodes](/docs/nodes) in your schema
+
+---
+
+- [`tags`](/docs/tags)
+- {% code %}{ [tagName: string]: [Schema](https://github.com/markdoc/markdoc/blob/6bcb8a0c48a181ca9df577534d841280646cea09/src/types.ts#L94-L101) }{% /code%}
+- Register [custom tags](/docs/tags) in your schema
+
+---
+
+- [`variables`](/docs/variables)
+- `{ [variableName: string]: any }`
+- Register [variables](/docs/variables) to use in your document
+
+---
+
+- [`functions`](/docs/functions)
+- {% code %}{ [functionName: string]: [ConfigFunction](https://github.com/markdoc/markdoc/blob/6bcb8a0c48a181ca9df577534d841280646cea09/src/types.ts#L31-L36) }{% /code %}
+- Register [custom functions](/docs/functions) to use in your document
+
+---
+
+- [`partials`](/docs/partials)
+- `{ [partialPath: string]: Ast.Node }`
+- Register reusable pieces of content to used by the [`partial` tag](/docs/partials)
+
+{% /table %}
+
+### Full example
+
+Here's an example of what a Markdoc config would look like:
+
+```js
+const config = {
+  nodes: {
+    heading: {
+      render: 'Heading',
+      attributes: {
+        id: { type: String },
+        level: { type: Number }
+      }
+    }
+  },
+  tags: {
+    callout: {
+      render: 'Callout',
+      attributes: {
+        title: {
+          type: String
+        }
+      }
+    }
+  },
+  variables: {
+    name: 'Dr. Mark',
+    frontmatter: {
+      title: 'Configuration options'
+    }
+  },
+  functions: {
+    includes: {
+      transform(parameters, config) {
+        const [array, value] = Object.values(parameters);
+
+        return Array.isArray(array) ? array.includes(value) : false;
+      }
+    }
+  },
+  partials: {
+    'header.md': Markdoc.parse(`# My header`)
+  }
+};
+
+const content = Markdoc.transform(ast, config);
+```

pages/docs/examples/index.md → pages/docs/customization.md

@@ -1,5 +1,5 @@
 ---
-title: Common examples
+title: Customization examples
 description:
 ---
 

pages/docs/functions.md

@@ -7,55 +7,6 @@ description: Functions let you extend Markdoc to run custom code.
 
 Functions enable you extend Markdoc with custom utilities, which let you transform your content and [variables](/docs/syntax#variables) at runtime.
 
-## Creating a custom function
-
-To extend Markdoc with your own functions, first create custom function definitions:
-
-```js
-const includes = {
-  transform(parameters) {
-    const [array, value] = Object.values(parameters);
-
-    return Array.isArray(array) ? array.includes(value) : false;
-  }
-};
-
-const uppercase = {
-  transform(parameters) {
-    const string = parameters[0];
-
-    return typeof string === 'string' ? string.toUpperCase() : string;
-  }
-};
-```
-
-Then, pass the functions to your [`Config` object](/docs/syntax#config)
-
-```js
-const config = {
-  functions: {
-    includes,
-    uppercase
-  }
-};
-
-const content = Markdoc.transform(ast, config);
-```
-
-Finally, call the functions within your Markdoc content
-
-{% markdoc-example %}
-
-```md
-{% if includes($countries, "AR") %} 🇦🇷 {% /if %}
-{% if includes($countries, "AU") %} 🇦🇺 {% /if %}
-{% if includes($countries, "ES") %} 🇪🇸 {% /if %}
-{% if includes($countries, "JP") %} 🇯🇵 {% /if %}
-{% if includes($countries, "NG") %} 🇳🇬 {% /if %}
-{% if includes($countries, "US") %} 🇺🇸 {% /if %}
-```
-
-{% /markdoc-example %}
 
 ## Built-in functions
 
@@ -171,6 +122,57 @@ This function simply renders the value as a serialized JSON value in the documen
 
 {% /markdoc-example %}
 
+
+## Creating a custom function
+
+To extend Markdoc with your own functions, first create custom function definitions:
+
+```js
+const includes = {
+  transform(parameters) {
+    const [array, value] = Object.values(parameters);
+
+    return Array.isArray(array) ? array.includes(value) : false;
+  }
+};
+
+const uppercase = {
+  transform(parameters) {
+    const string = parameters[0];
+
+    return typeof string === 'string' ? string.toUpperCase() : string;
+  }
+};
+```
+
+Then, pass the functions to your [`Config` object](/docs/syntax#config)
+
+```js
+const config = {
+  functions: {
+    includes,
+    uppercase
+  }
+};
+
+const content = Markdoc.transform(ast, config);
+```
+
+Finally, call the functions within your Markdoc content
+
+{% markdoc-example %}
+
+```md
+{% if includes($countries, "AR") %} 🇦🇷 {% /if %}
+{% if includes($countries, "AU") %} 🇦🇺 {% /if %}
+{% if includes($countries, "ES") %} 🇪🇸 {% /if %}
+{% if includes($countries, "JP") %} 🇯🇵 {% /if %}
+{% if includes($countries, "NG") %} 🇳🇬 {% /if %}
+{% if includes($countries, "US") %} 🇺🇸 {% /if %}
+```
+
+{% /markdoc-example %}
+
 ## Next steps
 
 - [Validate your content](/docs/validation)