Support for Quarto

[joshhopkins]

We've started to use Quarto to create dynamic documents – weaving together narrative and code in plain text. With plans for a Quarto vscode extension it would be amazing to have Foam support for .qmd files in preparation for potentially tighter integration.

Interested to hear thoughts on this.

[philoserf]

If I understand Foam design, then they will work together. Nothing needs be done that I can see now. Caveat: I am a fairly new Foam user. Not yet a contributor.

[riccardoferretti]

I agree, they should be able to coexist, probably the only thing that might need improving is support for the .qmd extension, but nothing major I believe

[joshhopkins]

@riccardoferretti support for the .qmd extension would be great. Beyond that, it would very much depends on quarto's upcoming extension, but rendering quarto static/interactive output in the preview pane would be a very nice value-add.

[riccardoferretti]

Foam is meant to be unopinionated about this like Quarto. Considering notes beyond the .md extension sounds reasonable to me, I wouldn't consider in scope further support for a tool or another.
Of course that gap could be bridged by an extension that uses the Foam API once that's released

[joshhopkins]

Makes sense @riccardoferretti. Perhaps supported extensions could be defined as a Foam preference, to allow for more flexibility.

[jjallaire]

FYI we now have a Quarto VS Code extension that provides various facilities for .qmd files: https://marketplace.visualstudio.com/items?itemName=quarto.quarto&ssr=false#overview

[fbob]

Quarto support could indeed greatly broaden foam community due to its complementary features.

[synesthesia]

Broadening this slightly after Discord conversation with @riccardoferretti .

My use case is for MDX files, which @riccardoferretti suggests we add in here to make this an issue about how different file extensions are handled.

For clarity, I am not (in this issue) asking for MDX preview inside VS Code, for my purposes I am happy for rendering of the MDX components to be solely an issue for my website publishing code.

However I do want the freedom to use *.mdx files within my Foam notes. At present, even though I have got the following in my VS Code settings:

  "files.associations": {
    "*.mdx": "markdown"
  }

many Foam functions don't work against these files:

• wikilinking, including no autofill inside a wikilink and no "Go to reference" or "Peek reference"
• graph, for same reason
• backlinks & orphans

[riccardoferretti]

Your comment also made me think that right now we are a bit too strict in the way we activate Foam with markdown. Our selector is

export const mdDocSelector = [
  { language: 'markdown', scheme: 'file' },
  { language: 'markdown', scheme: 'untitled' },
];

and probably something like

export const mdDocSelector = { language: 'markdown', scheme: '*' };

would do. or even just export const mdDocSelector = 'markdown'.

I see the Quarto has a document selector of type quarto (see https://github.com/quarto-dev/quarto-vscode/blob/main/src/core/doc.ts).

So probably a way to solve both problems would be to allow additional selectors for which Foam should be enabled exposing them in the configuration, e.g to allow the following selector: export const mdDocSelector = ['markdown', 'quarto']

[synesthesia]

@riccardoferretti that sounds plausible but you know far more about workings of VS Code than me, just getting started on my first extension.

I'm slightly confused though, given in my config I have:

"files.associations": {
    "*.mdx": "markdown"
  }

and when I open a .mdx file in the editor the language value shown in the status bar is Markdown...

so why do you think VS Code is not already treating MDX files as selected by { language: 'markdown', scheme: 'file' } ?

[riccardoferretti]

That's a limitation of Foam, as it explicitly only looks for .md files. We need to be smarter, or at least more flexible with configuration, to support other extensions

[randallb]

Hi-- how could I help do this? I'm interested in adding MDX to foam.

[riccardoferretti]

hi @randallb happy to provide support on the task, thanks for looking into it!
Basically right now Foam assumes .md to be the extension of both the files that we are looking for (hence it will not look for .mdx files), and the extension to use for new notes created (this can be worked around with templates, but that's beyond the point at this moment).

My initial step here would be to look at the places where .md is hardcoded/used, and replace is with a setting.
Along the lines of foam.files.attachmentExtensions, I would introduce a foam.files.notesExtensions (or foam.files.markdownExtensions as we still make the assumption these will be markdown compatible files, tbc) that has the same format as the foam.files.attachmentExtensions variable, and is used to find notes.
On top of that, the first extension is the list will also become the default extension to be used when creating new notes.

This is just a off-the-top-of-my-head approach, happy to discuss alternatives you might think of.

Let me know if you have any question, you can also ping me on our discord server.

[omrihar]

I tried using foam with quarto and my experience so far has been (perhaps I didn't set up things correctly):

1. When the foam default template contained YAML front-matter with tags, quarto complained since it didn't recognize it.
2. When trying to naively generate quarto preview from linked notes, I noticed that the generated URL points to the markdown file rather than the html file generated by quarto. So you get links that work, but only in one direction (since the markdown of the referred-to note is simply displayed as plaintext.

Anyone experienced the same or has a good workaround for it?

Cheers,
Omri

[jjallaire]

Quarto front-matter validation should be tolerant of YAML it doesn't recognize. Specifically which front-matter is tripping things up?

Note that you can also specify validate-yaml: false to turn off YAML validation entirely.

[omrihar]

I had issues with the tags section that was automatically added as example in the initial Foam template. For some reason quarto didn't like it and stopped building the project. I did only add the project using quarto create-project . in the directory of the Foam repository. Didn't try to customize much. Probably if I did, i would be able to find a way around it. I think the more problematic issue is the fact that the links lead to the markdown rather than the html files when building the Foam generated notes with wikilinks to a quarto website. This I don't really know how to solve (without adding a postprocessing step to quarto, but I'm not sure that's the best solution.

[omrihar]

Another issue - if i want to create notes with executable code in them, they must use the .qmd file extension rather than .md. Is there a way to tell Foam to use both .md and .qmd file extensions for the detection of the wikilinks?

[riccardoferretti]

At the moment Foam uses .md as default extension, that is not configurable, but we should allow for that.
I have created #1129 to capture that, together with the proposed solution.

[riccardoferretti]

This PR will introduce support for Quarto #1235