diff --git a/pages/docs/attributes.md b/pages/docs/attributes.md
index a93b6e08..32ca00d4 100644
--- a/pages/docs/attributes.md
+++ b/pages/docs/attributes.md
@@ -5,8 +5,74 @@ description: Attributes are used to pass data to tags in Markdoc.
 
 # {% $markdoc.frontmatter.title %}
 
+
 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).
@@ -125,4 +191,4 @@ const config = {
 
 ## Next steps
 
-- [Pass variables to attributes](/docs/variables)
+- [Pass variables to attributes](/docs/variables)
\ No newline at end of file
diff --git a/pages/docs/syntax.md b/pages/docs/syntax.md
index 87c3b562..6d406393 100644
--- a/pages/docs/syntax.md
+++ b/pages/docs/syntax.md
@@ -114,48 +114,27 @@ If your tag doesn't contain any new lines, then it's treated as an inline tag. I
 \
 For more information, check out the [Tags docs](/docs/tags).
 
-## Annotations
-
-Customize how individual nodes are rendered with annotations. Annotations are useful when passing properties to customize the output, such as an `id` or `class`. You can also use annotations to apply [attributes](#attributes) to HTML and React elements.
-
-You can access annotation values as [attributes](/docs/attributes) within your schema [`transform`](/docs/nodes#customizing-markdoc-nodes) functions.
-
-\
-To add an `id`, you can use this syntax:
-
-{% markdoc-example %}
-
-```
-# Header {% #custom-id %}
-```
+## Attributes
 
-{% /markdoc-example %}
+Pass attributes to nodes and tags to customize their behavior. You can pass values of type: `number`, `string`, `boolean`, JSON `array`, or JSON `object`, either directly or using [variables](#variables). 
 
-To set a `class`, use class syntax:
+With tags, you can use an HTML-like syntax:
 
 {% markdoc-example %}
 
 ```
-# Heading {% .custom-class-name-here %}
-```
-
-{% /markdoc-example %}
-
-which also works within your tags.
-
-{% markdoc-example %}
-
-```md
-{% section #id .class %}
-
-My section
-
-{% /section  %}
+{% city
+   index=0
+   name="San Francisco"
+   deleted=false
+   coordinates=[1, 4, 9]
+   meta={id: "id_123"} 
+   color=$color /%}
 ```
 
 {% /markdoc-example %}
 
-You can also set [attributes](#attributes) on a node, such as `width` or `colspan`.
+Because the HTML-like syntax doesn't work with nodes, we offer another option: write the attributes after the tag or node you're passing them to, in a separate set of `{%` and `%}`. 
 
 {% markdoc-example %}
 
@@ -171,29 +150,8 @@ You can also set [attributes](#attributes) on a node, such as `width` or `colspa
 
 {% /markdoc-example %}
 
-## Attributes
-
-Pass attributes to tags to customize their behavior. You can pass values of type: `number`, `string`, `boolean`, JSON `array`, or JSON `object`.
-
-{% markdoc-example %}
-
-```
-{% city
-   index=0
-   name="San Francisco"
-   deleted=false
-   coordinates=[1, 4, 9]
-   meta={id: "id_123"} /%}
-```
-
-{% /markdoc-example %}
-
-All Markdoc strings use double-quotes. This includes when passing a string as an attribute or as a [function](#functions) parameter.  
-If you want to include a double-quote in a string you can escape it with using `\"`.
-
 \
 For more information, check out the [Attributes docs](/docs/attributes).
-
 ## Variables
 
 Markdoc variables let you customize your Markdoc documents at runtime. Variables all have a `$` prefix.
@@ -362,4 +320,4 @@ const content = Markdoc.transform(ast, config);
 ## Next steps
 
 - [Render Markdoc](/docs/render)
-- [Validate your content](/docs/validation)
+- [Validate your content](/docs/validation)
\ No newline at end of file