{"record":{"id":"1027d560a12a2004","repo":"Shopify/liquid","slug":"errors-syntax-doc-invalid-nested","errorCode":"errors.syntax.doc_invalid_nested","errorMessage":"parse_context.locale.t(\"errors.syntax.doc_invalid_nested\")","messagePattern":"parse_context\\.locale\\.t\\(\"errors\\.syntax\\.doc_invalid_nested\"\\)","errorType":"exception","errorClass":"Liquid::SyntaxError","httpStatus":null,"severity":"error","filePath":"lib/liquid/tags/doc.rb","lineNumber":78,"sourceCode":"\n    def blank?\n      @body.empty?\n    end\n\n    def nodelist\n      [@body]\n    end\n\n    private\n\n    def ensure_valid_markup(tag_name, markup, parse_context)\n      unless NO_UNEXPECTED_ARGS.match?(markup)\n        raise SyntaxError, parse_context.locale.t(\"errors.syntax.block_tag_unexpected_args\", tag: tag_name)\n      end\n    end\n\n    def raise_nested_doc_error\n      raise SyntaxError, parse_context.locale.t(\"errors.syntax.doc_invalid_nested\")\n    end\n  end\nend\n","sourceCodeStart":60,"sourceCodeEnd":82,"githubUrl":"https://github.com/Shopify/liquid/blob/807d45a6b3d4568e64e86b375e3702df2c7c860c/lib/liquid/tags/doc.rb#L60-L82","documentation":"Liquid does not allow a `{% doc %}` block to be nested inside another `{% doc %}` block. raise_nested_doc_error raises SyntaxError with the localized 'errors.syntax.doc_invalid_nested' when a doc tag is encountered while already inside a doc block.","triggerScenarios":"Placing `{% doc %} ... {% doc %} ... {% enddoc %} ... {% enddoc %}` — an inner doc opening tag inside an outer doc block's content.","commonSituations":"Merging snippet files where each section wraps itself in a doc block; templating tools that auto-generate documentation wrappers around already-documented snippets; copy-paste of a documented block into another documented block.","solutions":["Remove the inner {% doc %} block; keep only one nesting level","Document each snippet separately instead of wrapping composed snippets","Refactor includes/renders so documented fragments are not embedded inside other doc blocks","Add a pre-commit lint that detects nested doc tags"],"exampleFix":"// before\n{% doc %}\n  Outer.\n  {% doc %}Inner.{% enddoc %}\n{% enddoc %}\n// after\n{% doc %}\n  Outer only.\n{% enddoc %}","handlingStrategy":"validation","validationCode":"def nested_doc?(source)\n  depth = 0\n  source.scan(/{%-?\\s*(doc|enddoc)\\b/).each do |t|\n    depth += (t.include?('enddoc') ? -1 : 1)\n    return true if depth > 1\n  end\n  false\nend","typeGuard":null,"tryCatchPattern":"begin\n  Liquid::Template.parse(source)\nrescue Liquid::SyntaxError => e\n  raise \"Nested doc blocks are invalid: #{e.message}\"\nend","preventionTips":["Never place a doc block inside another doc block","Document snippets separately rather than wrapping composed fragments","Add lint that tracks doc/enddoc nesting depth"],"tags":["liquid","ruby","template-syntax","doc-tag","nesting"],"backgroundTag":"liquid-tag-syntax-error","analyzedSha":"807d45a6b3d4568e64e86b375e3702df2c7c860c","analyzedAt":"2026-09-08T11:31:38.917Z","contentChangedAt":"2026-09-08T11:31:38.917Z","schemaVersion":2},"datasetVersion":"2026-09-16T09:17:16.951Z"}