Add pre-defined user snippets to roadmap

[ingalless]

See the conversation here

[ingalless]

A useful list for Roam commands

[Just-Insane]

Examples: https://roamhacks.com/slash-helpers-roam/

Some comments made on Discord about using cmd+shift+p vs /commands in terms of what people are used to doing in VSCode. Could default to cmd+shift+p and enable /commands based on user preference.

[jsjoeio]

Notion has similar slash commands

[ingalless]

Notion has similar slash commands

@jsjoeio What's the best way to capture this and Just-Insane's notes in the roadmap item? Is a notes heading like this preferable?

[jsjoeio]

Is a notes heading like this preferable

@ingalless I think that sounds like the best approach for now.

If in addition, you wanted to write a Recipe about creating your own snippets, that could help people take advantage in the interim. Your call!

When you think this is ready it be reviewed, feel free to request or @ me and I'll take a look!

[ingalless]

@jsjoeio sounds great! Recipe sounds a good idea too, definitely will add that

Might it be sensible to write it in such a way that it encourages users to raise snippet suggestions as issues? Would be cool to see what ideas people have!

Going to start a to-do list here so I remember what to do each time I come to the issue

• Add recipe for custom snippets
• Add comments from users into "Notes" (or similar) section

[ShaunaGordon]

Some comments made on Discord about using cmd+shift+p vs /commands in terms of what people are used to doing in VSCode. Could default to cmd+shift+p and enable /commands based on user preference.

Since I was one of the ones that brought this bit up, allow me to elaborate more on my thoughts.

Let me start by saying I love slash commands....in more graphical-oriented environments. I literally use slash commands all the time in places like ClickUp and World of Warcraft, where the alternative is navigating a graphical menu system.

But VSCode already has a similar system in place...it just isn't activated by slashes (because then it'd be getting accidentally activated all the f-ing time), but with cmd/ctrl+shift+p. The talk in other areas about Language Server support suggests a desire to use Foam in other advanced text editors...most of which already use the same or similar command panel paradigm, making it a natural thing to users coming from the "experienced with VSCode" end.

Implementing slash commands, especially if it's with more than just snippets, seems like reinventing the wheel and trying to shoehorn a paradigm that works in other applications for specific reasons into a family of applications that already has its own paradigm and framework for running commands. It honestly struck me as a "your scientists were so preoccupied with whether they could, they never stopped to think whether they should" sort of moment.

It raised some questions for me:

1. What is Foam's intention on how it achieves the goal of facilitating note-taking/thought aggregation? Is it to blend into the "host" ecosystem, or is it to take it over and use the power of that ecosystem to build its own thing? If the former, then wouldn't it be most prudent to work with the paradigms of that ecosystem? If the latter, then perhaps we should start talking about a VSCode fork that is Foam Desktop, or something? (That would actually be kind of cool, to be honest.)

2. Who is Foam for, besides "everyone"? There's certainly merit in "anyone can use this!" but there's still generally some type of core that a thing appeals to the most. What does Foam have that prompts people to pick it over Roam or Obsidian or Notion or one of the few dozen other knowledge collection applications that are out there and why? And what makes them choose Foam every single time they open that new note and (as James Clear puts it) "cast a personal vote" for this platform in particular, instead of switching? Would implementing a competing task-running system to what's already in their ecosystem appeal to that core, or would it cause friction and unnecessary overhead? (Or...is Foam trying to appeal to the Roam and Notion and other more graphical-oriented platforms and bring that paradigm into the VSCode ecosystem, or is/should it fit into its own niche, where it fits more transparently into VSCode, and appeal to those who were turned off by the others in the space? Or should it take Door Number 3?)

3. Perhaps a slash commands framework...thing...would be best as its own extension? Among those that would want it/make use of it, I could see it expanding beyond just Foam stuff if at all possible.

🤷 Just some thoughts.

[ingalless]

@ShaunaGordon Some good points here, thanks for contributing!

You're right that it doesn't make sense to reinvent the wheel with /commands when the command palette already provides that functionality.

Personally, I still think carefully curated and selected snippets that were available to the user could be great. Take the date note id and zettelkasten id examples presented in the GIF of this pull request. For me, snippets are great for allowing me to stay in the flow of the document (or code) I'm editing. Opening the command palette is an interruption in the flow of my note taking or programming. I would count myself among the Foam users who are already experienced with VS Code. When I'm at my computer again I'll open my command palette so I can see what my most recently used commands were. I don't think many of the commands I use would insert text at my cursor.

Perhaps /commands as a name for these muddies the intention. They are just VS Code snippets. You can type one small bit of text and have it expand into a larger piece of text, with the possibility to tab through different parts of text. This is powerful, and even a few simple snippets to get started could be great.

Snippets are great for awkward syntax. Tables in markdown are awkward. Todos in markdown can be awkward to start authoring - [ ].

However, all the points you've made are very good and food for thought! They show the diversity of workflows. My VS Code is highly customised for focused work (only one file open at a time, no sidebar etc) and that works for me. But of course that doesn't work for everyone and my colleagues tell me as much!

I'll definitely include these notes in. We don't want the commands to be invasive.

[jevakallio]

Just dropping a quick nugget here, I found that VS Code has this setting that's set to "inline" by default:

"editor.snippetSuggestions": "inline" | "top" | "bottom" | "none"

The description of the setting is:

Controls whether snippets are shown with other suggestions and how they are sorted.

So this seems that if we have slash-snippets and slash-commands, it's possible that user snippets could be shown along command autocompletions. This has not been verified, just noting it down lest I forget.

[ingalless]

@jevakallio this is great!

[jevakallio]

I'm not certain this is the direction we want to go to, but if we did want to teach non-markdown-writing users markdown, I was playing with the idea of having slash commands for all the standard markdown snippets.

Leaving the code here in case we end up needing it

{
  "Heading 1": {
    "scope": "markdown",
    "prefix": "/h1",
    "description": "Heading 1",
    "body": [
      "# $TM_SELECTED_TEXT"
    ]
  },
  "Heading 2": {
    "scope": "markdown",
    "prefix": "/h2",
    "description": "Heading 3",
    "body": [
      "## $TM_SELECTED_TEXT"
    ]
  },
  "Heading 3": {
    "scope": "markdown",
    "prefix": "/h3",
    "description": "Heading 3",
    "body": [
      "### $TM_SELECTED_TEXT"
    ]
  },
  "Insert bold text": {
    "prefix": "/bold",
    "body": "**${1:${TM_SELECTED_TEXT}}**$0",
    "description": "Insert bold text"
  },
  "Insert italic text": {
    "prefix": "/italic",
    "body": "*${1:${TM_SELECTED_TEXT}}*$0",
    "description": "Insert italic text"
  },
  "Insert quoted text": {
    "prefix": "/quote",
    "body": "> ${1:${TM_SELECTED_TEXT}}",
    "description": "Insert quoted text"
  },
  "Insert code": {
    "prefix": "/code",
    "body": "`${1:${TM_SELECTED_TEXT}}`$0",
    "description": "Insert code"
  },
  "Insert fenced code block": {
    "prefix": "/multiline codeblock",
    "body": [
      "```${1:language}",
      "${TM_SELECTED_TEXT}$0",
      "```"
    ],
    "description": "Insert fenced code block"
  },
  "Insert unordered list": {
    "prefix": "/ul",
    "body": [
      "- ${1:first}",
      "- ${2:second}",
      "- ${3:third}",
      "$0"
    ],
    "description": "Insert unordered list"
  },
  "Insert ordered list": {
    "prefix": "/ol",
    "body": [
      "1. ${1:first}",
      "2. ${2:second}",
      "3. ${3:third}",
      "$0"
    ],
    "description": "Insert ordered list"
  },
  "Insert horizontal rule": {
    "prefix": "/hr",
    "body": "----------\n",
    "description": "Insert horizontal rule"
  },
  "Insert link": {
    "prefix": "link",
    "body": "[${TM_SELECTED_TEXT:${1:text}}](https://${2:link})$0",
    "description": "Insert link"
  },
  "Insert image": {
    "prefix": "image",
    "body": "![${TM_SELECTED_TEXT:${1:alt}}](https://${2:link})$0",
    "description": "Insert image"
  }
}

[jsjoeio]

Since this is just adding an item to the roadmap, we could theoretically merge this, right @ingalless ?

My thought is:

• open issue to keep track of this roadmap item
• add key highlights from this PR discussion to that issue
• link to this PR as well
• update predefined-user-snippets.md to link to discussion issue
• approve
• merge

Thoughts?

[ingalless]

@jsjoeio yes, completely agree. I'd like to just add the comments made in this thread if that's alright?

I can do it Monday morning before I start work!

Apologies for the delay on this. I had the week of work to do some work around the home and haven't had much time for this!

I'll ping you Monday morn once I've wrapped up?

[jsjoeio]

@jsjoeio yes, completely agree. I'd like to just add the comments made in this thread if that's alright?

I can do it Monday morning before I start work!

Apologies for the delay on this. I had the week of work to do some work around the home and haven't had much time for this!

I'll ping you Monday morn once I've wrapped up?

No worries at all! Do it when you have time and then ping me. Sounds great :) thanks @ingalless !

[ingalless]

@jsjoeio Got round to this early. Ready for review!

[jsjoeio]

LGTM! Nice work @ingalless 🥳

[jevakallio]

LGTM!

[jevakallio]

@ShaunaGordon thank you for your thoughts! Here's some back:

But VSCode already has a similar system in place...it just isn't activated by slashes (because then it'd be getting accidentally activated all the f-ing time),

If we implement these, I'd definitely make them optional.

Implementing slash commands, especially if it's with more than just snippets, seems like reinventing the wheel and trying to shoehorn a paradigm that works in other applications for specific reasons into a family of applications that already has its own paradigm and framework for running commands. It honestly struck me as a "your scientists were so preoccupied with whether they could, they never stopped to think whether they should" sort of moment.

This is a tricky one. If our goal is to build a tool solely for developers, then I agree that we could tell them to just use Ctrl+Shift+P, but that has a bit of an overtone of telling people to "just RTFM". If our goal is to empower people to get used to powerful text editing tools, creating familiarity with their existing workflows while they're getting used to the new paradigm seems to me like it could act as a bridge to learning new workflows.

Besides, at least to me, slash commands feel more ergonomic specifically for syntax and snippet expansion, as the option menu appears inside the text editor where the snippet is eventually inserted.

It raised some questions for me:

What is Foam's intention on how it achieves the goal of facilitating note-taking/thought aggregation? Is it to blend into the "host" ecosystem, or is it to take it over and use the power of that ecosystem to build its own thing? If the former, then wouldn't it be most prudent to work with the paradigms of that ecosystem? If the latter, then perhaps we should start talking about a VSCode fork that is Foam Desktop, or something? (That would actually be kind of cool, to be honest.)

This is something I would like us to pursue once we get the basics right in extension-land first.

Who is Foam for, besides "everyone"? There's certainly merit in "anyone can use this!" but there's still generally some type of core that a thing appeals to the most. What does Foam have that prompts people to pick it over Roam or Obsidian or Notion or one of the few dozen other knowledge collection applications that are out there and why? And what makes them choose Foam every single time they open that new note and (as James Clear puts it) "cast a personal vote" for this platform in particular, instead of switching?

These are great questions. The canonical answer is Foam is for hackers, not just for programmers.

If we want more segmentation, we need to do user interviews and/or just decide who we want it to be for. If anyone would be interested in doing the research work to give us that insight, I'd be very happy for it -- currently I don't personally have the bandwidth.

Would implementing a competing task-running system to what's already in their ecosystem appeal to that core, or would it cause friction and unnecessary overhead?

I don't think so. Not if it can be disabled. I believe lowering barriers to entry is valuable enough for the overhead, if the overhead is as low as implementing a few snippets and a setting to toggle it on/off.

Perhaps a slash commands framework...thing...would be best as its own extension? Among those that would want it/make use of it, I could see it expanding beyond just Foam stuff if at all possible.

This is the eternal question in Foam land that we need better default answers for: What belongs to the core? Expect thoughts and guidance on that in the upcoming weeks/months.

For the time being I'm happy merging this as a roadmap item to that we have an idea of how we might implement this, if we choose to prioritise it.

[jevakallio]

Thank you @ingalless for writing this, @jsjoeio for the reviews and @ShaunaGordon for the feedback!

[ShaunaGordon]

Perhaps /commands as a name for these muddies the intention. They are just VS Code snippets. You can type one small bit of text and have it expand into a larger piece of text, with the possibility to tab through different parts of text. This is powerful, and even a few simple snippets to get started could be great.

Snippets are great for awkward syntax. Tables in markdown are awkward. Todos in markdown can be awkward to start authoring - [ ].

I know this is already merged, but I want to clarify something here for the record.

Adding text snippet triggers? I'm all for that. I've got a number of my own for scaffolding out whole files. I totally agree that having them especially for awkward structures are great (hat-tip to the Emmet project, which I might add is a good source of implementation inspiration).

That's not where my reservations are/were. The discussion in the Discord had gone down the path of (at least as I understood it) more powerful commands, not just text snippets. Those more powerful commands get into the realm of the command palette and are where I start to question to the wisdom of shoehorning a new system in.

Perhaps it's just a matter of considering a different name from "slash commands," since that name implies more functionality than I think people are actually going for with this feature?

It might also be worthwhile to include some more transparent snippet triggers. Like...why isn't auto-closing code fencing already a thing?! This could be easily solved with a snippet that is triggered off the opening marks.