NotePlan / NotePlan/plugins

Templating: Make docs clear about two dashes

Open
#428 0 comments 0 reactions 1 assignee View on GitHub

@mikeerickson is already working on this.

Since Mar 22, 2023.

documentation
Dominant language
JavaScript
Stars
204
Forks
82
Avg merge
22h 27m
Merged PRs (30d)
3

Description

  1. Pls merge the PR on the docs from @ed when you can
  2. When you do, pls make one addition: make it super explicitly clear (maybe in multiple places) that if you want a frontmatter in your template, you should use two dashes "--" which will get converted to three when the template is rendered. Technically, you can now put three dash separators in a template, but NOT as the first line. So, if you want the top of your template to be frontmatter in the generated note, then use two dashes. You should NOT ever have three dashes as the first line in the body of your template.

I spent a couple hours chasing my tail trying to find a bug a user had and it turned out the problem was that three dashes in the first line of the template BODY is a no-no and Templating will try to render it as if it's frontmatter. I'm not sure why exactly this happens (maybe reentrance?) but preRender is called more than once when rendering it.

@mikeerickson why does it call preRender twice?
For example, templateAppend does this:

      let { frontmatterBody, frontmatterAttributes } = await NPTemplating.preRender(templateData)
      let data = { ...frontmatterAttributes, frontmatter: { ...frontmatterAttributes } }

      let renderedTemplate = await NPTemplating.render(frontmatterBody, data)

It calls preRender and then afterwards calls render with the results. The problem is that render() calls preRender again:

        const { frontmatterAttributes, frontmatterBody } = await this.preRender(templateData, sessionData)

And it's this second time through that causes the issues if you have dashes in the first line.

Fixing it feels low priority if the documentation can be super clear that you cannot ever place three dashes as the first line of your template body. For example (note that the first line UNDER the frontmatter is three dashes):

---
title: this template will fail to render
---
---
<%- date.now("Do MMMM YYYY") %>
---
foo bar

I created a test case to illustrate the issue, but it is skipped for now because obviously it will fail:

    //FIXME: (@codedungeon): - I added this test to illustrate an edge case that a user was running into
    // Even though the above test on .render passes using Jest, in the real NotePlan app,
    // if the templateBody starts with three dashes, then for some reason, preRender gets called on that body as if it's frontmatter and fails
    // in the same way it fails in this test
    it.skip(`should preRender with multiple frontmatter-like separators in document (even number) - esp when the first line in the template content is a separator`, async () => {
      const templateData = `---\n<%- date.now("Do MMMM YYYY") %>\n\n---`
      const sessionData = {
        title: 'Daily Note Test',
        type: 'meeting-note, empty-note',
        methods: {},
      }
      let result = await NPTemplating.preRender(templateData, sessionData)
      const lines = result.split('\n')
      expect(lines[0]).toEqual(`---`)
      // date on line 1
      expect(lines[2]).toEqual(``) //empty line
      expect(lines[3]).toEqual(`## Primary Focus`)
    })
    ```


Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.