From 3128a97c7524404e8169a94e26faa6d62c9b7359 Mon Sep 17 00:00:00 2001
From: riccardoferretti <riccardoferretti@users.noreply.github.com>
Date: Tue, 5 Sep 2023 22:09:13 +0000
Subject: [PATCH] Docs sync @ e327115 Feat #879: Note Embedding Syntax (#1281)

---
 .../features/built-in-note-embedding-types.md | 29 +++++++++++++++++++
 docs/features/including-notes.md              |  4 ++-
 docs/features/note-templates.md               |  4 +--
 3 files changed, 34 insertions(+), 3 deletions(-)
 create mode 100644 docs/features/built-in-note-embedding-types.md

diff --git a/docs/features/built-in-note-embedding-types.md b/docs/features/built-in-note-embedding-types.md
new file mode 100644
index 0000000..64cd6e5
--- /dev/null
+++ b/docs/features/built-in-note-embedding-types.md
@@ -0,0 +1,29 @@
+# Built-In Note Embedding Types
+
+When embedding a note, there are a few ways to modify the scope of the content as well as its display style. The following are Foam keywords that are used to describe note embedding.
+
+Note, this only applies to note embedding, not embedding of attachments or images.
+
+![Note Embed Types GIF](../../assets/images/note-embed-type-demo.gif)
+
+## Scope
+
+- `full` - the entire note in the case of `![[note]]` or the entire section in the case of `![[note#section1]]`
+- `content` - everything excluding the title of the section. So the entire note minus the title for `![[note]]`, or the entire section minus the section header for `![[note#section1]]`
+
+## Style
+
+- `card` - outlines the embedded note with a border
+- `inline` - adds the note continuously as if the text were part of the calling note
+
+## Default Setting
+
+Foam expresses note display type as `<scope>-<style>`.
+
+By default, Foam configures note embedding to be `full-card`. That is, whenever the standard embedding syntax is used, `![[note]]`, the note will have `full` scope and `card` style display. This setting is stored under `foam.preview.embedNoteStyle` and can be modified.
+
+## Explicit Modifiers
+
+Prepend the wikilink with one of the scope or style keywords, or a combination of the two to explicitly modify a note embedding if you would like to override the default setting.
+
+For example, given your `foam.embedNoteStyle` is set to `content-card`, embedding a note with standard syntax `![[note-a]]` would show a bordered note without its title. Say, for a specific `note-b` you would like to display the title. You can simply use one of the above keywords to override your default setting like so: `full![[note-b]]`. In this case, `full` overrides the default `content` scope and because a style is not specified, it falls back to the default style setting, `card`. If you would like it to be inline, override that as well: `full-inline![[note-b]]`.
diff --git a/docs/features/including-notes.md b/docs/features/including-notes.md
index 85e9149..21e9c60 100644
--- a/docs/features/including-notes.md
+++ b/docs/features/including-notes.md
@@ -8,7 +8,9 @@ Including a note can be done by adding an `!` before a wikilink definition. For
 
 ## Custom styling
 
-Displaying the inclusion of notes allows for some custom styling, see [[custom-markdown-preview-styles]]
+To modify how an embedded note looks and the scope of its content, see [[built-in-note-embedding-types]]
+
+For more fine-grained custom styling, see [[custom-markdown-preview-styles]]
 
 ## Future possibilities
 
diff --git a/docs/features/note-templates.md b/docs/features/note-templates.md
index 91c8f00..e1db5b3 100644
--- a/docs/features/note-templates.md
+++ b/docs/features/note-templates.md
@@ -194,7 +194,7 @@ You can add the template metadata to its own YAML Frontmatter block at the start
 foam_template:
   name: My Note Template
   description: This is my note template
-  filepath: `journal/$FOAM_TITLE.md`
+  filepath: 'journal/$FOAM_TITLE.md'
 ---
 This is the rest of the template
 ```
@@ -206,7 +206,7 @@ If the note already has a Frontmatter block, a Foam-specific Frontmatter block c
 foam_template:
   name: My Note Template
   description: This is my note template
-  filepath: `journal/$FOAM_TITLE.md`
+  filepath: 'journal/$FOAM_TITLE.md'
 ---
 
 ---