Allow for YAML metadata in templates

[movermeyer]

What are you trying to accomplish?

As part of #563, we are adding a mechanism to provide metadata within a Frontmatter block within a Foam note template.

What approach did you choose and why?

As noted in this comment, it's nicer to be able to add the metadata to an existing YAML frontmatter block.
However, it is also very difficult to programmatically remove an entry from a YAML mapping without disrupting the rest of the YAML.

So in this PR, I allow for both. If you have an existing YAML frontmatter block, and you're willing to abide by fairly strict formatting, then you can add the metadata to the existing frontmatter block.

If for some reason, you cannot use the restricted syntax, you are still able to provide a second, Foam-specific YAML frontmatter block at the start of the template instead.

What should reviewers focus on?

Not quite there

This PR does not succeed at fully implementing the desired behaviour.
I had dreamed of being able to use any VS Code snippet variable in the filepath.

---
foam_template:
  filepath: `journal/${CURRENT_YEAR}-${CURRENT_MONTH}-${CURRENT_DATE}.md`
---

This would allow Foam: Open Daily Note to make use of templates easily.
However, this is not currently possible. VS Code does not currently offer an interface for resolving the snippet variables without opening the snippet in an editor for the user.

In the future, we might vendor the relevant bits snippet resolution code, or submit a patch to VS Code to expose their variable resolution functionality as part of the API.

The PR as it stands still offers value, since it allows you to define relative or absolute directories to store the files into, instead of the default Foam: Create New Note behaviour of opening the file in the same directory as the active file.

Example of using metadata to specify a directory relative to the current workspace

---
# This will create the note in the "journal" subdirectory of the current workspace, 
# regardless of which file is the active file. 
foam_template:
  filepath: `journal/$FOAM_TITLE.md` 
---

Next steps

• Figure out a way to allow for VS Code snippet variables within the metadata
• Make Foam: Open Daily Note use templates

[riccardoferretti]

The general approach looks good to me, a few comments:

• I didn't realize there was such limitation on Snippet strings, that's unfortunate, we should look into getting an API to the text expansion
• I am happy to not support JSON frontmatter
• I am happy to only support a single YAML block if that simplifies your life, I don't mind supporting 2 YAML blocks if you prefer that way and it doesn't make the code awfully more complicated

[movermeyer]

@riccardoferretti, I think this is ready for review.

Since you last looked, I've implemented the name and description template metadata attributes that @jevakallio suggested.

IMO, it looks pretty slick:

---

Replying to your previous comment.

I didn't realize there was such limitation on Snippet strings, that's unfortunate, we should look into getting an API to the text expansion

💯, that's the next step after this PR.

I am happy to not support JSON frontmatter

👍

I am happy to only support a single YAML block if that simplifies your life, I don't mind supporting 2 YAML blocks if you prefer that way and it doesn't make the code awfully more complicated

It wasn't very complicated to support both (with the caveat that users cannot use the full flexibility of the YAML syntax if they want to have the metadata within an existing Frontmatter bock)

[riccardoferretti]

the screenshots look pretty cool, thanks for this!
I have added a few comments, mostly minor, let me know your thoughts

[riccardoferretti]

is this an implicit any? in that case I am surprised it didn't raise a warning from the linter.

I also noticed in other places you are using object for metadata.. given that we have a specific shape for the template metadata, could it be helpful to map it onto a type/interface?

[movermeyer]

is this an implicit any? in that case I am surprised it didn't raise a warning from the linter.

It is. I guess I just missed the warning:

---

I've switched it to Map<string, string>... if that helps?

[riccardoferretti]

I am surprised it didn't show up as a warning in the PR, I thought the integration would do that (kinda like when there is an unused import/variable)... mm, to be looked into at some point.

Given the metadata has a specific type, I would just defined that, as it also provides a good in-code documentation for what info can be found (and is allowed) as template metadata, wdyt?

[movermeyer]

Given the metadata has a specific type, I would just defined that, as it also provides a good in-code documentation for what info can be found (and is allowed) as template metadata, wdyt?

@riccardoferretti Sounds good to me. I won't have time to make this change until next week. If you're eager, we can ship this now, and I'll do that refactor as part of my next PR.

[riccardoferretti]

happy to merge this in the meantime, will do a release later so the feature will already be available. thanks!

[chrisUsick]

Just came across an issue that I couldn't find in the docs, started reading the code and found foam_template.filepath on master but couldn't figure out why it appeared template metadata wasn't working, then noticed that this if 5h old!
So thanks for implementing and can't wait for this to be released!