{"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"write-with-markdoc","__idx":0},"children":["Write with Markdoc"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This guide will teach you how use Markdoc syntax in your technical writing to unlock powerful features for building documentation."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"markdown-refresher","__idx":1},"children":["Markdown refresher"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before diving into Markdoc, let's revisit our shared understanding of Markdown. This section provides a quick refresher on Markdown basics."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://daringfireball.net/projects/markdown/basics"},"children":["Markdown"]}," is a markup language used to format text documents. Markdown forms the foundational syntax that Markdoc builds upon. You should be comfortable writing in Markdown before using Markdoc."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"basic-syntax","__idx":2},"children":["Basic syntax"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The basic syntax for Markdown comes from the original ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://daringfireball.net/projects/markdown/syntax"},"children":["design document"]},". These elements are widely supported by modern Markdown tooling."]},{"$$mdtype":"Tag","name":"details","attributes":{},"children":[{"$$mdtype":"Tag","name":"summary","attributes":{},"children":["See Basic Syntax examples"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Element"},"children":["Element"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Syntax"},"children":["Syntax"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Heading (6 header levels)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdown","header":{"controls":{"copy":{}}},"source":"# H1\n## H2\n","lang":"markdown"},"children":[]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Bold"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdown","header":{"controls":{"copy":{}}},"source":"This text is **bold**.\n","lang":"markdown"},"children":[]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Italic"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdown","header":{"controls":{"copy":{}}},"source":"This text uses _italic_.\n","lang":"markdown"},"children":[]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Link"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdown","header":{"controls":{"copy":{}}},"source":"[link text](https://redocly.com)\n","lang":"markdown"},"children":[]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Image"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdown","header":{"controls":{"copy":{}}},"source":"![Image alt text](cat_with_glasses.png)\n","lang":"markdown"},"children":[]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Inline code"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdown","header":{"controls":{"copy":{}}},"source":"This text has `inline_code`.\n","lang":"markdown"},"children":[]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Blockquote"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdown","header":{"controls":{"copy":{}}},"source":"> This text is a quote.\n","lang":"markdown"},"children":[]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Horizontal rule"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdown","header":{"controls":{"copy":{}}},"source":"---\n","lang":"markdown"},"children":[]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Unordered list"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdown","header":{"controls":{"copy":{}}},"source":"- First bullet\n- Second bullet\n","lang":"markdown"},"children":[]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Ordered list"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdown","header":{"controls":{"copy":{}}},"source":"1. First thing on list\n2. Second thing on list\n","lang":"markdown"},"children":[]}]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"extended-syntax","__idx":3},"children":["Extended syntax"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Support for additional elements is added to Markdown using extended syntax. Some extended elements, like code block, are widely supported while others are tool-specific, like ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://github.github.com/gfm/"},"children":["GitHub Flavored Markdown"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Ever created a table in Markdown? You've used extended syntax."]},{"$$mdtype":"Tag","name":"details","attributes":{},"children":[{"$$mdtype":"Tag","name":"summary","attributes":{},"children":["See Extended Syntax examples"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Element"},"children":["Element"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Syntax"},"children":["Syntax"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Code block (aka \"fence\")"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"text","header":{"controls":{"copy":{}}},"source":"```javascript\nconsole.log('hello world');\n```\n","lang":"text"},"children":[]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Table"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdown","header":{"controls":{"copy":{}}},"source":"| Header 1 | Header 2 |\n| -------- | -------- |\n| Hello    | World    |\n| Foo      | Bar      |\n\n","lang":"markdown"},"children":[]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Strikethrough"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdown","header":{"controls":{"copy":{}}},"source":"This text has a <del>strikethrough</del>.</code>\n","lang":"markdown"},"children":[]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Task list"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdown","header":{"controls":{"copy":{}}},"source":"- [x] Completed task\n- [ ] Task to do\n","lang":"markdown"},"children":[]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Footnote"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdown","header":{"controls":{"copy":{}}},"source":"This text has a footnote. <sup>[4]</sup>\n\n[4] ... the footnote.\n","lang":"markdown"},"children":[]}]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Attention"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["not"]}," a comprehensive list of extended syntax. For more examples and information, try this resource: ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://www.markdownguide.org/extended-syntax/"},"children":["Extended Syntax"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["There's ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["a lot"]}," of different extended syntax out there. This resource compares syntax for the most common extensions: ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://gist.github.com/vimtaai/99f8c89e7d3d02a362117284684baa0f"},"children":["Extended syntax comparison by Markdown flavor"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"learn-markdoc-syntax","__idx":4},"children":["Learn Markdoc syntax"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Markdoc is a \"superset\", which means it builds on top of Markdown to provide enhanced features and capabilities. That means you're still writing using Markdown syntax, but can reach for Markdoc when you need a more complex feature."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This section introduces Markdoc syntax and provides examples. Please keep the following in mind:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Markdoc features are optional. Only use what adds value."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You don't need to be a developer to use Markdoc in your writing."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"markdown-plus-markdoc","__idx":5},"children":["Markdown plus Markdoc"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Markdoc extends Markdown by adding support for a custom syntax that wraps text with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{%"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["%}"]},". You'll write using a combination of Markdown and Markdoc syntax."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdown","header":{"controls":{"copy":{}}},"source":"# Example guide\n\nContent with _Markdown elements_.\n\n{% markdoc-tag %}\nMore **Markdown** content.\n{% markdoc-tag %}\n","lang":"markdown"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"tags-add-elements","__idx":6},"children":["Tags add elements"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Markdoc tags add new elements and capabilities to your document. Use tags to enhance your writing experience with pre-built elements and tools."]},{"$$mdtype":"Tag","name":"details","attributes":{},"children":[{"$$mdtype":"Tag","name":"summary","attributes":{},"children":["Learn more about tags"]},"\nMarkdoc includes some [built-in tags](index.md#built-in-markdoc-features), but teams can [define custom tags](index.md#build-your-own-writing-tools) tailored to the needs of their authors and users.\n",{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Official Markdoc docs: ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://markdoc.dev/docs/tags"},"children":["Tags"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Tags are composable, flexible, and play nicely with Markdown syntax. The table below contains common patterns for using Markdoc tags that you'll see in your writing."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"width":"30%","data-label":"Example"},"children":["Example "]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Syntax"},"children":["Syntax"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Markdown inside tag"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdocExample","attributes":{"renderDemo":false,"title":null,"language":"markdoc","demoContent":[{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Markdown"]}," syntax stays the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["same"]},"."]}]}],"rawContent":"{% admonition type=\"info\" %}\n  _Markdown_ syntax stays the **same**.\n{% /admonition %}\n"},"children":[]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Nested Markdoc tags"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdocExample","attributes":{"renderDemo":false,"language":"markdoc","demoContent":[{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"First tab","disable":false},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Content in the first tab"]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Second tab","disable":false},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Second tab content"]}]}]}],"rawContent":"{% tabs %}\n  {% tab label=\"First tab\"%}\n    Content in the first tab\n  {% /tab %}\n  {% tab label=\"Second tab\"%}\n    Second tab content\n  {% /tab %}\n{% /tabs %}\n"},"children":[]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Self-closing tag"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdocExample","attributes":{"renderDemo":false,"language":"markdoc","demoContent":[{"$$mdtype":"Tag","name":"code-snippet","attributes":{"file":"/some-file.md"},"children":[]}],"rawContent":"{% code-snippet file=\"/some-file.md\" /%}\n"},"children":[]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"attributes-control-tags","__idx":7},"children":["Attributes control tags"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Attributes allow you to pass values to tags. Use attributes to control the behavior or appearance of an element added by a tag."]},{"$$mdtype":"Tag","name":"details","attributes":{},"children":[{"$$mdtype":"Tag","name":"summary","attributes":{},"children":["Learn more about attributes"]},"\nAttributes are defined in a tag's schema. Custom tags can define custom attributes that control how authors are able to interact with or modify a tag.\n",{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Official Markdoc docs: ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://markdoc.dev/docs/attributes"},"children":["Attributes"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The attributes available for each Markdoc tag are defined as part of the tag's schema. Consider the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["admonition"]}," tag below:"]},{"$$mdtype":"Tag","name":"SplitView","attributes":{},"children":[{"$$mdtype":"Tag","name":"LeftView","attributes":{"title":"Syntax"},"children":[{"$$mdtype":"Tag","name":"MarkdocExample","attributes":{"renderDemo":false,"language":"markdoc","demoContent":[{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Hello, friends!"]}]}],"rawContent":"{% admonition type=\"info\" %}\n  Hello, friends!\n{% /admonition %}\n"},"children":[]}]},{"$$mdtype":"Tag","name":"RightView","attributes":{"title":"Output"},"children":[{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Hello, friends!"]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Passing a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["name"]}," attribute adds a header to the admonition."]},{"$$mdtype":"Tag","name":"SplitView","attributes":{},"children":[{"$$mdtype":"Tag","name":"LeftView","attributes":{"title":"Syntax"},"children":[{"$$mdtype":"Tag","name":"MarkdocExample","attributes":{"renderDemo":false,"language":"markdoc","demoContent":[{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Header"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Hello, friends!"]}]}],"rawContent":"{% admonition type=\"info\" name=\"Header\" %}\n  Hello, friends!\n{% /admonition %}\n"},"children":[]}]},{"$$mdtype":"Tag","name":"RightView","attributes":{"title":"Output"},"children":[{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Header"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Hello, friends!"]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Passing a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]}," attribute changes to a different pre-defined admonition."]},{"$$mdtype":"Tag","name":"SplitView","attributes":{},"children":[{"$$mdtype":"Tag","name":"LeftView","attributes":{"title":"Syntax"},"children":[{"$$mdtype":"Tag","name":"MarkdocExample","attributes":{"renderDemo":false,"language":"markdoc","demoContent":[{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"success"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Hello, friends!"]}]}],"rawContent":"{% admonition type=\"success\" %}\n  Hello, friends!\n{% /admonition %}\n"},"children":[]}]},{"$$mdtype":"Tag","name":"RightView","attributes":{"title":"Output"},"children":[{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"success"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Hello, friends!"]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"variables-resolve-at-runtime","__idx":8},"children":["Variables resolve at runtime"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Variables define values that resolve when the page loads. Use variables to customize the page with dynamic values accessible at runtime."]},{"$$mdtype":"Tag","name":"details","attributes":{},"children":[{"$$mdtype":"Tag","name":"summary","attributes":{},"children":["Learn more about variables"]},"\nVariables resolve when the page renders. If a variable changes on the server after the page renders, then the page needs to reload for it to be visible.\n",{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Official Markdoc docs: ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://markdoc.dev/docs/variables"},"children":["Variables"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In this guide's Markdown file, I've added the following values to the front matter:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"example:\n  value: world\n  days:\n    - Monday\n    - Tuesday\n    - Wednesday\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["I can pass those values to elements using Markdoc variables."]},{"$$mdtype":"Tag","name":"SplitView","attributes":{},"children":[{"$$mdtype":"Tag","name":"LeftView","attributes":{"title":"Syntax"},"children":[{"$$mdtype":"Tag","name":"MarkdocExample","attributes":{"renderDemo":false,"language":"markdoc","demoContent":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Hello ","world"]}],"rawContent":"Hello {% $frontmatter.example.value %}\n"},"children":[]}]},{"$$mdtype":"Tag","name":"RightView","attributes":{"title":"Output"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Hello ","world"]}]}]},{"$$mdtype":"Tag","name":"SplitView","attributes":{},"children":[{"$$mdtype":"Tag","name":"LeftView","attributes":{"title":"Syntax"},"children":[{"$$mdtype":"Tag","name":"MarkdocExample","attributes":{"renderDemo":false,"language":"markdoc","demoContent":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Today is ","Monday","."]}],"rawContent":"Today is {% $frontmatter.example.days[0] %}.\n"},"children":[]}]},{"$$mdtype":"Tag","name":"RightView","attributes":{"title":"Output"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Today is ","Monday","."]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Variables can be used to pass values to partials. They're especially useful when combined with function syntax."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"functions-provide-logic","__idx":9},"children":["Functions provide logic"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Functions are a tool for building \"runtime logic\" into your content. Use functions and variables to control or transform the content rendered by your document."]},{"$$mdtype":"Tag","name":"details","attributes":{},"children":[{"$$mdtype":"Tag","name":"summary","attributes":{},"children":["Learn more about functions"]},"\nMarkdoc includes built-in functions, but you can also build custom functions. Similar to tags, custom functions are built by developers and exposed for writers to use in their content.\n",{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Official Markdoc docs: ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://markdoc.dev/docs/functions"},"children":["Functions"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can use built-in functions to implement conditional logic. For example, adding a beta disclaimer:"]},{"$$mdtype":"Tag","name":"MarkdocExample","attributes":{"renderDemo":false,"language":"markdoc","demoContent":[],"rawContent":"{% if equals($frontmatter.product-status, \"beta\") %}\n  **Note** -- This product is still in beta.\n{% /if %}\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"annotations-extend-elements","__idx":10},"children":["Annotations extend elements"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Annotations pass attributes to elements that don't use Markdoc tag syntax. Use annotations to extend specific Markdown elements or elements inside a tag."]},{"$$mdtype":"Tag","name":"details","attributes":{},"children":[{"$$mdtype":"Tag","name":"summary","attributes":{},"children":["Learn more about annotations"]},"\nAnnotations allow authors to pass attributes that modify the HTML an element renders on a page.\n",{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Official Markdoc docs: ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://markdoc.dev/docs/functions"},"children":["Functions"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Add classes that apply CSS styling to specific elements."]},{"$$mdtype":"Tag","name":"SplitView","attributes":{},"children":[{"$$mdtype":"Tag","name":"LeftView","attributes":{"title":"Syntax"},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdown","header":{"controls":{"copy":{}}},"source":"- An item {% .list-entry-example %}\n- Another item {% .list-entry-example %}\n- Item without annotation\n","lang":"markdown"},"children":[]}]},{"$$mdtype":"Tag","name":"RightView","attributes":{"title":"Output"},"children":[{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{"class":"list-entry-example"},"children":["An item "]},{"$$mdtype":"Tag","name":"li","attributes":{"class":"list-entry-example"},"children":["Another item "]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Item without annotation"]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Define an element's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," to use as an anchor link. ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"#annotation-example-id"},"children":["This link"]}," anchors to the bold text in the example below."]},{"$$mdtype":"Tag","name":"SplitView","attributes":{},"children":[{"$$mdtype":"Tag","name":"LeftView","attributes":{"title":"Syntax"},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdown","header":{"controls":{"copy":{}}},"source":"**Example anchor element** {% #annotation-example-id %}\n","lang":"markdown"},"children":[]}]},{"$$mdtype":"Tag","name":"RightView","attributes":{"title":"Output"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{"id":"annotation-example-id"},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example anchor element"]}," "]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use annotations to pass styling attributes directly to an element. Setting the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["width"]}," of a column in a Markdoc table is a great example."]},{"$$mdtype":"Tag","name":"SplitView","attributes":{},"children":[{"$$mdtype":"Tag","name":"LeftView","attributes":{"title":"Syntax"},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdown","header":{"controls":{"copy":{}}},"source":"{% table %}\n  * Heading 1 {% width=\"20%\" %}\n  * Heading 2\n  ---\n  * First cell content\n  * Second cell content\n{% /table %}\n","lang":"markdown"},"children":[]}]},{"$$mdtype":"Tag","name":"RightView","attributes":{"title":"Output"},"children":[{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"width":"25%","data-label":"Heading 1"},"children":["Heading 1 "]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Heading 2"},"children":["Heading 2"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["First cell content"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Second cell content"]}]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"keep-learning-markdoc","__idx":11},"children":["Keep learning Markdoc"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Markdoc builds on the simplicity of Markdown to unlock powerful new capabilities for writers. This guide provides a foundation to explore Markdoc's advanced features and start using them in your own writing."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use these resources to more about Markdoc:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/learn/markdoc"},"children":["Markdoc Overview"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/learn/markdoc/evaluating-markdoc"},"children":["Evaluating Markdoc"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/learn/markdoc/tags/tag-library"},"children":["Markdoc Tag Library"]}]}]}]},"frontmatter":{"seo":{"title":"Write with Markdoc","description":"Learn to use Markdoc in your technical writing. Markdoc is a powerful tool that unlocks powerful features in your Markdown documents."},"example":{"value":"world","days":["Monday","Tuesday","Wednesday"]}},"tagList":["admonition","html","left-view","markdoc-example","right-view","split-view","table"],"title":"Write with Markdoc","lastModified":"2025-05-28T16:01:32.000Z"}