--- title: New in Twig 3.29: Documentation Comments (Symfony Blog) description: Twig 3.29 adds documentation comments, a standard syntax using an extra # (e.g. {## ... ##}) for attaching human-readable descriptions to blocks, macros,... canonical: https://daily.dev/posts/new-in-twig-3-29-documentation-comments-symfony-blog--yr4rbofie twitter:card: summary_large_image twitter:site: @dailydotdev og:type: website og:site_name: daily.dev og:title: New in Twig 3.29: Documentation Comments (Symfony Blog) | daily.dev og:description: Twig 3.29 adds documentation comments, a standard syntax using an extra # (e.g. {## ... ##}) for attaching human-readable descriptions to blocks, macros,... og:url: https://daily.dev/posts/new-in-twig-3-29-documentation-comments-symfony-blog--yr4rbofie og:image: https://api.daily.dev/og/posts/Yr4rboFIE.png og:image:alt: New in Twig 3.29: Documentation Comments (Symfony Blog) og:image:width: 1200 og:image:height: 630 og:locale: en --- > ## Documentation Index > Fetch the complete documentation index at: https://daily.dev/llms.txt > Use this file to discover all available pages before exploring further. # New in Twig 3.29: Documentation Comments (Symfony Blog) **[Symfony](https://daily.dev/sources/symfony)** · 4 min read · 1 upvotes · 0 comments ## Summary Twig 3.29 adds documentation comments, a standard syntax using an extra # (e.g. {## ... ##}) for attaching human-readable descriptions to blocks, macros, output expressions, and variable bindings like types, set, for, and macro arguments, without altering rendered output. This replaces ad-hoc conventions like @prop/@block annotations, giving IDEs, static analyzers, and doc generators a common metadata source via Node::getDocumentation(). Older Twig versions and Twig 3.15+ parse the new syntax as an ordinary comment, so it degrades gracefully. The feature is experimental and may evolve. ## Full article daily.dev links to this article rather than hosting it. Read it at the original source: ## Questions this post answers ### How do I add documentation comments to a Twig template in version 3.29? Use the double-hash comment syntax introduced in Twig 3.29. Outside a tag, write {## description ##} immediately before a block, macro, or output expression. Inside a tag such as types, set, for, or macro, prefix the line with ## and it consumes the rest of the line, so the described variable must start on the next line. These comments attach metadata without changing rendered output. _Track new Twig syntax like this on daily.dev to keep template tooling and docs current._ ### What replaces custom @prop and @block annotations in Twig templates? Twig 3.29's built-in documentation comments replace those ad hoc conventions. Previously, projects used custom annotations like {# @prop id string ... #} or {# @block content ... #} that duplicated variable names and types already declared in the types tag, forcing every IDE, analyzer, or doc generator to parse a project-specific format. The new syntax is standardized and readable by tools via Node::getDocumentation(). _Developers standardizing template metadata can follow Twig changes like this on daily.dev._ ### Are Twig documentation comments backward compatible with older Twig versions? Yes, they degrade gracefully. Older Twig versions parse {## ... #} as a regular comment with no special meaning, and Twig 3.15 and later also parse ## inside a tag as an ordinary inline comment. This means templates can adopt the new documentation comment syntax without breaking rendering on earlier Twig releases, though the feature is experimental in Twig 3.29 and may change. _daily.dev helps developers weigh compatibility trade-offs before adopting experimental Twig features._ ## Similar posts on daily.dev - [Twig 3.28.0 released \(Symfony Blog\)](https://daily.dev/posts/twig-3-28-0-released-symfony-blog--dpjk2dnjm) · Symfony · 4 upvotes · 0 comments - [Twig 3.23: Introducing new operators and destructuring support \(Symfony Blog\)](https://daily.dev/posts/twig-3-23-introducing-new-operators-and-destructuring-support-symfony-blog--bk2cqn0wr) · Symfony · 0 upvotes · 0 comments - [New in Twig 4.0: A New Macro System \(Symfony Blog\)](https://daily.dev/posts/new-in-twig-4-0-a-new-macro-system-symfony-blog--iohnteuqx) · Symfony · 6 upvotes · 1 comments - [Ruby Multiline Comments Explained with Examples](https://daily.dev/posts/ruby-multiline-comments-explained-with-examples-szdbqw4wl) · RUBYLAND · 0 upvotes · 0 comments - [Version-Controlled Documentation Inside Your Laravel App with Laradocs](https://daily.dev/posts/version-controlled-documentation-inside-your-laravel-app-with-laradocs-jk21vslab) · Laravel News · 45 upvotes · 8 comments --- Tags: [#php](https://daily.dev/tags/php), [#symfony](https://daily.dev/tags/symfony) [View this post on daily.dev](https://daily.dev/posts/new-in-twig-3-29-documentation-comments-symfony-blog--yr4rbofie) ```json {"@context":"https://schema.org","@graph":[{"@type":"Organization","@id":"https://daily.dev/#organization","name":"daily.dev","url":"https://daily.dev","logo":{"@type":"ImageObject","url":"https://daily.dev/apple-touch-icon.png","width":180,"height":180},"sameAs":["https://twitter.com/dailydotdev","https://github.com/dailydotdev","https://www.linkedin.com/company/daily-dev-ltd"]},{"@type":"WebSite","@id":"https://daily.dev/#website","url":"https://daily.dev","name":"daily.dev","publisher":{"@id":"https://daily.dev/#organization"},"potentialAction":{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https://daily.dev/search?q={search_term_string}"},"query-input":"required name=search_term_string"}}]} {"@context":"https://schema.org","@type":"TechArticle","headline":"New in Twig 3.29: Documentation Comments (Symfony Blog)","url":"https://daily.dev/posts/new-in-twig-3-29-documentation-comments-symfony-blog--yr4rbofie","mainEntityOfPage":{"@type":"WebPage","@id":"https://daily.dev/posts/new-in-twig-3-29-documentation-comments-symfony-blog--yr4rbofie"},"datePublished":"2026-08-21T15:12:18.758Z","dateModified":"2026-09-14T09:02:37.463Z","description":"Twig 3.29 adds documentation comments, a standard syntax using an extra # (e.g. {## ... ##}) for attaching human-readable descriptions to blocks, macros,...","image":"https://media.daily.dev/image/upload/f_auto,q_auto/v1/posts/327b244859fddae8f3a20d0225898aa0?_a=AQAEuop","thumbnailUrl":"https://media.daily.dev/image/upload/f_auto,q_auto/v1/posts/327b244859fddae8f3a20d0225898aa0?_a=AQAEuop","isAccessibleForFree":true,"articleSection":"Symfony","inLanguage":"en","publisher":{"@type":"Organization","name":"daily.dev","url":"https://daily.dev","logo":{"@type":"ImageObject","url":"https://daily.dev/apple-touch-icon.png","width":180,"height":180}},"author":{"@type":"Organization","name":"Symfony","logo":"https://media.daily.dev/image/upload/t_logo,f_auto/v1/logos/cc07051b7112472f9729e73c14660a64","url":"https://daily.dev/sources/symfony"},"commentCount":0,"discussionUrl":"https://daily.dev/posts/new-in-twig-3-29-documentation-comments-symfony-blog--yr4rbofie","interactionStatistic":[{"@type":"InteractionCounter","interactionType":{"@type":"LikeAction"},"userInteractionCount":1},{"@type":"InteractionCounter","interactionType":{"@type":"CommentAction"},"userInteractionCount":0}],"keywords":"php,symfony","timeRequired":"PT4M"} {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://daily.dev"},{"@type":"ListItem","position":2,"name":"Symfony","item":"https://daily.dev/sources/symfony"},{"@type":"ListItem","position":3,"name":"New in Twig 3.29: Documentation Comments (Symfony Blog)"}]} {"@context":"https://schema.org","@type":"FAQPage","@id":"https://daily.dev/posts/new-in-twig-3-29-documentation-comments-symfony-blog--yr4rbofie#faq","mainEntity":[{"@type":"Question","name":"How do I add documentation comments to a Twig template in version 3.29?","acceptedAnswer":{"@type":"Answer","text":"Use the double-hash comment syntax introduced in Twig 3.29. Outside a tag, write {## description ##} immediately before a block, macro, or output expression. Inside a tag such as types, set, for, or macro, prefix the line with ## and it consumes the rest of the line, so the described variable must start on the next line. These comments attach metadata without changing rendered output. Track new Twig syntax like this on daily.dev to keep template tooling and docs current."}},{"@type":"Question","name":"What replaces custom @prop and @block annotations in Twig templates?","acceptedAnswer":{"@type":"Answer","text":"Twig 3.29's built-in documentation comments replace those ad hoc conventions. Previously, projects used custom annotations like {# @prop id string ... #} or {# @block content ... #} that duplicated variable names and types already declared in the types tag, forcing every IDE, analyzer, or doc generator to parse a project-specific format. The new syntax is standardized and readable by tools via Node::getDocumentation(). Developers standardizing template metadata can follow Twig changes like this on daily.dev."}},{"@type":"Question","name":"Are Twig documentation comments backward compatible with older Twig versions?","acceptedAnswer":{"@type":"Answer","text":"Yes, they degrade gracefully. Older Twig versions parse {## ... #} as a regular comment with no special meaning, and Twig 3.15 and later also parse ## inside a tag as an ordinary inline comment. This means templates can adopt the new documentation comment syntax without breaking rendering on earlier Twig releases, though the feature is experimental in Twig 3.29 and may change. daily.dev helps developers weigh compatibility trade-offs before adopting experimental Twig features."}}]} ```