{"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"markdown-guide","__idx":0},"children":["Markdown guide"]},{"$$mdtype":"Tag","name":"ConfigOptionRequirements","attributes":{"products":["Redoc","Revel","Reef","Realm"],"plans":["Pro","Enterprise","Enterprise+"]},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Redocly projects support enhanced Markdown that combines standard Markdown syntax with powerful Markdoc extensions, giving you rich formatting options and interactive components for your documentation."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"standard-markdown","__idx":1},"children":["Standard Markdown"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All standard Markdown syntax works in Redocly projects:"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"text-formatting","__idx":2},"children":["Text formatting"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdown","header":{"controls":{"copy":{}}},"source":"**Bold text** and *italic text*\n\n~~Strikethrough text~~\n\n`Inline code`\n\n> Blockquotes for callouts and emphasis\n","lang":"markdown"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"headings-and-structure","__idx":3},"children":["Headings and structure"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdown","header":{"controls":{"copy":{}}},"source":"# Page title (H1)\n## Section heading (H2)  \n### Subsection heading (H3)\n\n- Bulleted lists\n- With multiple items\n\n1. Numbered lists\n2. In sequential order\n","lang":"markdown"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"links-and-references","__idx":4},"children":["Links and references"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdown","header":{"controls":{"copy":{}}},"source":"[Link text](./relative-page.md)\n[External link](https://example.com)\n\n![Image alt text](./images/screenshot.png)\n","lang":"markdown"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"code-blocks","__idx":5},"children":["Code blocks"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdown","header":{"controls":{"copy":{}}},"source":"```javascript\n// Syntax highlighting for many languages\nfunction example() {\n  return \"Hello world\";\n}\n```\n","lang":"markdown"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"redocly-enhancements","__idx":6},"children":["Redocly enhancements"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Redocly extends standard Markdown with additional capabilities:"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"front-matter-configuration","__idx":7},"children":["Front matter configuration"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Control page behavior with YAML front matter:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"---\ntitle: Custom page title\ndescription: Page description for SEO\n---\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"enhanced-code-blocks","__idx":8},"children":["Enhanced code blocks"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Add titles, line highlighting, and annotations:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdown","header":{"controls":{"copy":{}}},"source":"```javascript {% title=\"app.js\" highlight=\"{2,4-6}\" %}\nfunction processData() {\n  const data = fetchData(); // [!code highlight]\n\n  if (!data) { // [!code error] // [!code error]\n    throw new Error('No data'); // [!code error] // [!code error]\n  } // [!code error] // [!code error]\n\n  return data.map(item => ({ // [!code ++] // [!code ++]\n    id: item.id, // [!code ++] // [!code ++]\n    name: item.name // [!code ++] // [!code ++]\n  })); // [!code ++] // [!code ++]\n}\n```\n","lang":"markdown"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Learn more about ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/config/code-snippet"},"children":["code snippet configuration"]},"."," ","For all highlighting and annotation options see examples at ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/content/markdoc-tags/code-snippet"},"children":["Markdoc code snippet tag"]},", and explore ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/content/markdoc-tags/code-group"},"children":["Markdoc code groups"]}," for multi-language examples."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"file-trees","__idx":9},"children":["File trees"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Display file and directory structures using the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["treeview"]}," syntax:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdown","header":{"controls":{"copy":{}}},"source":"```treeview\n.\n├── guides/                 # Guides\n│   ├── guide-1.md\n│   └── guide-2.md\n├── images/                 # Various shared images\n│   ├── favicon.png\n│   └── header-image.png\n├── tutorials/              # Tutorials\n│   ├── tutorial-1.md\n│   ├── tutorial-2.md\n│   ├── index.md\n│   └── sidebars.yaml       # Sidebar specific to the 'tutorials' section\n├── static/                 # Static assets copied directly to build output\n│   └── robots.txt\n├── index.page.tsx          # Custom React component for the landing page\n├── package.json            # Node.js project manifest\n└── redocly.yaml            # Main Redocly configuration file\n```\n","lang":"markdown"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Result:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"treeview","header":{"controls":{"copy":{}}},"source":".\n├── guides/                 # Guides\n│   ├── guide-1.md\n│   └── guide-2.md\n├── images/                 # Various shared images\n│   ├── favicon.png\n│   └── header-image.png\n├── tutorials/              # Tutorials\n│   ├── tutorial-1.md\n│   ├── tutorial-2.md\n│   ├── index.md\n│   └── sidebars.yaml       # Sidebar specific to the 'tutorials' section\n├── static/                 # Static assets copied directly to build output\n│   └── robots.txt\n├── index.page.tsx          # Custom React component for the landing page\n├── package.json            # Node.js project manifest\n└── redocly.yaml            # Main Redocly configuration file\n","lang":"treeview"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"diagrams","__idx":10},"children":["Diagrams"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Add visual diagrams using Mermaid syntax:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdown","header":{"controls":{"copy":{}}},"source":"```mermaid\ngraph TD\n    A[User Request] --> B{Authentication}\n    B -->|Valid| C[Process Request]\n    B -->|Invalid| D[Return Error]\n    C --> E[Return Response]\n```\n","lang":"markdown"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Learn more about ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/content/add-diagram"},"children":["adding diagrams"]}," with additional examples and chart types."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"markdoc-tags","__idx":11},"children":["Markdoc tags"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Redocly includes powerful Markdoc tags for interactive elements:"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"content-organization","__idx":12},"children":["Content organization"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdoc","header":{"controls":{"copy":{}}},"source":"{% tabs %}\n{% tab label=\"Option A\" %}\nContent for the first tab.\n{% /tab %}\n{% tab label=\"Option B\" %}\nContent for the second tab.\n{% /tab %}\n{% /tabs %}\n","lang":"markdoc"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Learn more about the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/content/markdoc-tags/tabs"},"children":["tabs tag"]}," for organizing content."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"visual-elements","__idx":13},"children":["Visual elements"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdoc","header":{"controls":{"copy":{}}},"source":"{% admonition type=\"info\" name=\"Important note\" %}\nThis is an informational callout with custom styling.\n{% /admonition %}\n\n{% cards %}\n{% card title=\"Feature 1\" icon=\"star\" to=\"./feature-1.md\" %}\nDescription of the first feature.\n{% /card %}\n{% card title=\"Feature 2\" icon=\"gear\" to=\"./feature-2.md\" %}\nDescription of the second feature.\n{% /card %}\n{% /cards %}\n","lang":"markdoc"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Learn more about ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/content/markdoc-tags/admonition"},"children":["admonitions"]}," and ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/content/markdoc-tags/cards"},"children":["cards"]}," for enhanced visual presentation."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"images-and-icons","__idx":14},"children":["Images and icons"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Enhanced image display with sizing, lightbox, and captions:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdoc","header":{"controls":{"copy":{}}},"source":"{% img src=\"./images/screenshot.png\" alt=\"Application screenshot\" width=\"400\" withLightbox=true %}\nA screenshot showing the main application interface.\n{% /img %}\n","lang":"markdoc"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Add inline icons for visual enhancement:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdoc","header":{"controls":{"copy":{}}},"source":"{% icon name=\"star\" /%} Highlighted feature\n{% icon name=\"warning\" color=\"orange\" /%} Important note\n","lang":"markdoc"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Learn more about ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/content/markdoc-tags/img"},"children":["image handling"]}," and ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/content/markdoc-tags/icon"},"children":["icons"]}," for visual elements."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"code-and-examples","__idx":15},"children":["Code and examples"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdoc","header":{"controls":{"copy":{}}},"source":"{% code-snippet file=\"./examples/sample.js\" title=\"Sample code\" /%}\n\n{% markdoc-example %}\nThis shows how Markdoc syntax renders in practice.\n{% /markdoc-example %}\n","lang":"markdoc"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdoc","header":{"controls":{"copy":{}}},"source":"{% code-group %}\n{% code title=\"JavaScript\" lang=\"javascript\" %}\nfetch('/api/users')\n  .then(response => response.json())\n  .then(data => console.log(data));\n{% /code %}\n{% code title=\"Python\" lang=\"python\" %}\nimport requests\nresponse = requests.get('/api/users')\ndata = response.json()\nprint(data)\n{% /code %}\n{% /code-group %}\n","lang":"markdoc"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Learn more about ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/content/markdoc-tags/code-snippet"},"children":["code snippets"]},", ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/content/markdoc-tags/code-group"},"children":["code groups"]},", and ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/content/markdoc-tags/markdoc-example"},"children":["Markdoc examples"]}," for displaying code."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"content-reuse","__idx":16},"children":["Content reuse"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdoc","header":{"controls":{"copy":{}}},"source":"{% partial file=\"/_partials/shared-section.md\" /%}\n","lang":"markdoc"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Learn more about ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/content/markdoc-tags/partial"},"children":["partials"]}," for reusing content across pages."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"api-documentation","__idx":17},"children":["API documentation"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdoc","header":{"controls":{"copy":{}}},"source":"{% openapi-code-sample \n   path=\"/users\" \n   method=\"post\" \n   lang=\"javascript\" /%}\n\n{% json-schema schema=\"user-schema.json\" /%}\n","lang":"markdoc"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Learn more about ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/content/markdoc-tags/openapi-code-sample"},"children":["OpenAPI code samples"]}," and ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/content/markdoc-tags/json-schema"},"children":["JSON schema"]}," for API documentation."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"tables","__idx":18},"children":["Tables"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Redocly uses enhanced table formatting:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdoc","header":{"controls":{"copy":{}}},"source":"{% table %}\n- Column 1\n- Column 2  \n- Column 3\n---\n- Row 1, Cell 1\n- Row 1, Cell 2\n- Row 1, Cell 3\n---\n- Row 2, Cell 1\n- Row 2, Cell 2\n- Row 2, Cell 3\n{% /table %}\n","lang":"markdoc"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Learn more about ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/content/markdoc-tags/table"},"children":["table formatting"]}," for structured data presentation."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"best-practices","__idx":19},"children":["Best practices"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"file-organization","__idx":20},"children":["File organization"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use descriptive filenames with kebab-case: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["user-authentication.md"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Organize related content in folders"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Place reusable content in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["_partials/"]}," folders"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"writing-style","__idx":21},"children":["Writing style"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Start with a clear H1 heading"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use descriptive link text instead of \"click here\""]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Include alt text for images"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Break up long content with headings and lists"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"cross-references","__idx":22},"children":["Cross-references"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use relative links for internal pages: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["./other-page.md"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Link to specific sections with anchors: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["./page.md#section-name"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Test links to ensure they work correctly"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"images-and-assets","__idx":23},"children":["Images and assets"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Store images in organized folders like ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["./images/"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use descriptive filenames for images"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Optimize image sizes for web display"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Consider using ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/customization/static-assets"},"children":["static assets"]}," for predictable URLs"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"resources","__idx":24},"children":["Resources"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/content/markdoc-tags/tag-library"},"children":["Built-in Markdoc tags"]}]}," - Complete library of interactive components like cards, tabs, admonitions, and code groups for enhanced content"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/content/markdoc-tags/partial"},"children":["Partial tag"]}]}," - Share and reuse content across multiple pages to maintain consistency and reduce duplication"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/content/project-structure"},"children":["Project structure"]}]}," - Organize your content files and directories for optimal navigation and maintenance"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/content/links"},"children":["Manage links"]}]}," - Create internal and external links with automatic validation and cross-references between pages and sections"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/customization/static-assets"},"children":["Static assets"]}]}," - Host images, files, and other static resources with predictable URLs and optimization"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/config/markdown"},"children":["Markdown configuration"]}]}," - Customize Markdown processing, syntax highlighting, and rendering behavior"]}]}]},"frontmatter":{"products":["Redoc","Revel","Reef","Realm"],"plans":["Pro","Enterprise","Enterprise+"],"keywords":{"includes":["markdown"]}},"tagList":["configOptionRequirements"],"title":"Markdown guide","lastModified":"2026-10-01T23:00:57.000Z"}