{"record":{"id":"17d6291e2b63c844","repo":"siyuan-note/siyuan","slug":"renderdocref-is-only-available-when-manually-inser","errorCode":null,"errorMessage":"renderDocRef is only available when manually inserting or previewing a template","messagePattern":"renderDocRef is only available when manually inserting or previewing a template","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"kernel/model/template_doc_tree.go","lineNumber":243,"sourceCode":"\t\treturn \"\", fmt.Errorf(\"createDocTree exceeds the maximum document count of %d\", maxTemplateDocTreeDocs)\n\t}\n\tcollector.bindNodes(nodes, collector.rootID, collector.rootPath, collector.rootHPath)\n\tcollector.nodes = append(collector.nodes, nodes...)\n\treturn \"\", nil\n}\n\nfunc (collector *templateDocTreeCollector) bindNodes(nodes []*TemplateDocTreeNode, parentID, parentPath, parentHPath string) {\n\tfor _, node := range nodes {\n\t\tnode.ParentID = parentID\n\t\tnode.path = strings.TrimSuffix(parentPath, \".sy\") + \"/\" + node.ID + \".sy\"\n\t\tnode.HPath = path.Join(parentHPath, node.Title)\n\t\tcollector.bindNodes(node.Children, node.ID, node.path, node.HPath)\n\t}\n}\n\nfunc (collector *templateDocTreeCollector) renderDocRef(mode string, value any) (any, error) {\n\tif !collector.enabled {\n\t\treturn nil, errors.New(\"renderDocRef is only available when manually inserting or previewing a template\")\n\t}\n\tswitch mode {\n\tcase \"children\":\n\t\tid, ok := value.(string)\n\t\tif !ok {\n\t\t\treturn nil, errors.New(\"renderDocRef children target must be a document ID\")\n\t\t}\n\t\tif collector.rootID == id {\n\t\t\treturn collector.nodes, nil\n\t\t}\n\t\tfor _, node := range flattenTemplateDocTreeNodes0(collector.nodes) {\n\t\t\tif node.ID == id {\n\t\t\t\treturn node.Children, nil\n\t\t\t}\n\t\t}\n\t\treturn []*TemplateDocTreeNode{}, nil\n\tcase \"path\":\n\t\thPath, ok := value.(string)","sourceCodeStart":225,"sourceCodeEnd":261,"githubUrl":"https://github.com/siyuan-note/siyuan/blob/8641553a1f07374001902d3ce773285db1292b2d/kernel/model/template_doc_tree.go#L225-L261","documentation":"renderDocRef is a template action that queries documents created/planned in the current template doc-tree session; it requires the collector to be enabled, which only happens during manual template insertion or template preview. When called with no active collector, it returns this error. This blocks renderDocRef in contexts where there is no doc tree to query.","triggerScenarios":"Using renderDocRef in a template rendered outside insertion/preview (e.g. included via another rendering path, or during template listing/content render where the collector is disabled).","commonSituations":"Moving a template that worked on insert into a passive render context; a shared template fragment using renderDocRef that is included both in previews and in other renders; tests invoking the render function without enabling the collector.","solutions":["Use renderDocRef only in templates inserted manually or rendered in preview mode.","Replace renderDocRef usage with static block references when the target document is known ahead of time.","In test harnesses, enable the collector (enabled=true) and populate nodes before rendering."],"exampleFix":"// before (fragment used in normal content render)\nrenderDocRef(\"children\", \"20240101120000-abc\")\n// after\nuse it only inside a template inserted via the editor, or hard-code ((block ref))s","handlingStrategy":"try-catch","validationCode":"// ensure the collector is enabled before rendering templates that use renderDocRef\nconst usable = renderMode === \"editorInsert\" || renderMode === \"preview\";","typeGuard":null,"tryCatchPattern":"try {\n  renderTemplate(src);\n} catch (e) {\n  if (String(e).includes(\"renderDocRef is only available\")) {\n    // re-render with preview/insert enabled or use static refs\n  }\n}","preventionTips":["Use renderDocRef only in insert/preview render modes","Keep renderDocRef out of passively rendered template fragments","Enable the collector in test harnesses that render such templates"],"tags":["template","render-context","permission"],"backgroundTag":"operation-not-supported","analyzedSha":"8641553a1f07374001902d3ce773285db1292b2d","analyzedAt":"2026-09-11T16:08:28.414Z","contentChangedAt":"2026-09-11T16:08:28.414Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}