Support different embedding styles

[riccardoferretti]

Currently embedding includes the note/section content inlined.

It would interesting to support different "embed styles" to customize the embedding behavior with:

• inline (include the full section, title included, in the note)
• content (include the full section, excluding the title, in the note)
• card/panel (add the embed inside a card or panel)

This could either be set by a workspace setting, or with some flag on the embed itself.

With a setting this would be pretty straightforward, with a flag on the embed we'd have to figure out a syntax that is falls back somewhat gracefully in other tools (e.g. Obsidian), but that adds the semantic we care about it Foam. (e.g. card![[my-note#section]])

The interesting thing about this approach is that it would also allow more styling to be applied in the future.

[SteveDadoly]

This is great. Gave this some thought and suggest the following:

Would consider a way to separate embed content scoping from embed content styling. For example: all|card![[my-note#section]]

Suggested Section Embed Content Scoping Flags

• all (include the full section, title included, in the note. Default if no scoping flag specified)
• contentOnly (include the full section, excluding the title)
• firstBlockOnly (include only the first block of content, excluding the title)
  • Based on CommonMark spec, first blocks be parsed and embedded via these html tags: <p>...</p>, <ul>...</ul>, <ol>...</ol>,<blockquote>...</blockquote>, and <pre>...</pre>
    • firstBlock <p> without a title would allow definitions, summary para, TL/DR para, etc. to be reused across documents, in tables cells, etc. (This is my primary use case for embeds.
    • firstBlock <pre> embed would allow fenced code blocks (mermaid diagrams, etc.) to be reused across multiple docs. (This is my second most important use case for embeds)
• excludeSubSections (Includes title and content but excludes sub-sections contained within the section)

Suggested Section Embed Styling Flags

• inline (include the embed in the note. Default if no style flag specified)
• card (render the embed in a card)

Thank you for considering this. I'll take a look at the code base next.

[riccardoferretti]

Hi @SteveDadoly thanks for your thoughts above.

I like the idea of describing both content and layout in the "modifier ", I think it's a good way to conceptualize the mapping.
To keep things simple I would avoid to have "special syntax", but instead make the list "flat". The simple way to achieve it is by replacing | with - (which IMO feels more natural and less "scripty"). See below for what I mean.

So, assuming:

• the content modifiers full (I think it works better than all) and content
  • I am excluding for now the "first block" and "exclude sub sections" options; the design supports them (which is what matters) but I am prefer to start small
• and the style modifiers inline and card

we'd end up with:

full-inline![[wikilink#section]]
full-card![[wikilink#section]]
content-inline![[wikilink#section]]
content-card![[wikilink#section]]

For each of those dimensions (content and style) we can have a default (which is what comes from the Foam setting).
E.g. with full and inline as defaults, the above list would turn into:

![[wikilink#section]]
card![[wikilink#section]]
content![[wikilink#section]]
content-card![[wikilink#section]]

Which seems pretty reasonable to me.

A couple of extra questions:

• which settings is more appropriate as default between card and inline, thoughts?
• would it make sense to have content-card![[wikilink#section]] == card-content![[wikilink#section]].. does it really matter if the content modifier is before or after the style modifier?

[SteveDadoly]

Hi @riccardoferretti,

Thank you for your thoughtful reply. Agree with all of your points above. Best to keep it simple.

From my perspective:

• Would default to the style that matches the target document (inline)
• The order of modifiers does not matter to me.

[riccardoferretti]

Cool, I think we have a plan 👍

[badsketch]

Hey I'd like to give this a shot, if there's still interest! Granted this issue is a little dated and things might've changed, I feel the content-scoping seems useful to have.

Am I correct that as of v0.25, embed styling (card vs inline) is determined by a settings config preview.embedNoteInContainer and content-scoping hasn't been implemented yet? Could we make the settings config the default and otherwise follow the syntax discussed above?

[riccardoferretti]

Hi @badsketch good to hear from you :)

As a first step I would replace the current boolean setting preview.embedNoteInContainer with a preview.embedStyle config as an enum of full-inline full-card content-inline content-card.

Even without adding the syntax right away, this:

• expands the possibilities of embedding
• adds the rendering code for the various options

For now you just need to be happy with having the same style across the knowledge base, in a second PR we can focus on the embed variant syntax.

Thoughts?

[badsketch]

Yeah totally! So IIUC, say a user has default preview.embedStyle=content-card, and in a note, types full![[foo#bar]], then wikilink-embed will treat it as style=card (because it's the settings default) and scope=full ( because it's explicit).

So we need to

1. add the config setting so we have established enums. Essentially, the config will be the default for when a user has ![[wikilink#section]]
2. modify wikilink-embed extension regex to support any combination !<style|null>-<scope|null>[[wikilink#section]]. For ex.

![[wikilink#section]]
card![[wikilink#section]]
content![[wikilink#section]]
content-card![[wikilink#section]]

3. update wiklink-embed implementation to support the actual rendering.

For now you just need to be happy with having the same style across the knowledge base, in a second PR we can focus on the embed variant syntax.

Would you prefer if we split the above into separate PR's so it's more readable and we discuss implementation at 1.? Otherwise, I think I can fit it all in one PR

[riccardoferretti]

Everything you wrote is correct.

And yes, I would focus on point n.1 at first, as it's MD compatible.
Then I would go for point n.3, which basically means all different styles are supported.

Finally I would add the ability to customize the styling for the individual wikilink by implementing point n.2.

[badsketch]

So double-checking content scoping functionality, if I have a note

# title

summary 

## sec 1

sec 1 content

### subsec a

more subsec content

Would content![[note]] just remove the note title, but still leave the section titles?

[riccardoferretti]

That's correct.

In terms of next step/PR, I would suggest starting by adding the remaining 2 configuration options.
This will give the 4 embedding combos (inline/card content/full), only driven by the configuration.

Once that is working, the next PR would focus on the wikilink syntax, in order to overwrite the default for a specific embedding.

Does that work for you?

[badsketch]

Yeah! That sounds great to me! I'm afk for the next few days but I'll get started asap afterwards