Documentation of org-roam in org-roam

Development
1

I just finished @nobiot 's great intro to org-roam part 2.

I think these are the documents that should be somehow incorporated into org-roam’s documentation.

I have always felt that the documentation for templates is not that great. One idea would be to provide a “Other documentation” that is a link to several web pages that have, over the years, explain how to use org-roam.

1 Like
2

@dmg

I have also found that many times people expect org-roam templating system should 1-1 be feature parity with org. But since there is a mechanism of delegation there is always some things lost in translation. For example,

I remember once you remarked about bridging this parity, do you think it’s possible?

3

I started revamping the template system some time ago.

The template system of org-roam is a bit weird. It uses the org-template system. Basically, it parses the template request, splits parameters into org-template and org-roam template, and lets org-template do the work.

one of the things that annoyed me was always being asked for a node, when I know already the node exists.

Currently this is what I have:

  • added a new boolean parameter: create-file. It false, the node should exists
  • added a node destination. If nil, ask user for node, if non-nil, it should exist
  • ask for node name only if no node is provided (this includes file targets)
  • added extra modifiers to the target that mimic some of the targets in org templates (eg. node+olp, node+headline).
  • trying to pass any non-org-roam parameter to org. I think org has been improving a lot since the original templating system of org-roam and only known parameters were passed. Instead, just pass anything unknown and let org deal with it.

lately I have been struggling with the function target.

overall, I think the main problem of org-roam templates is that they are meant to be used for creating new nodes, not to edit current nodes. Perhaps the best was to combine org-templates for nodes already existing and org-roam templates to create new nodes.

My code is dirty at the moment (due to the creation of the function target) but it is here: