foam.edit.linkReferenceDefinitions vs markdownlint (MD053)

[DevPartner]

Issue: foam.edit.linkReferenceDefinitions vs markdownlint (MD053)

Workaround: set foam.edit.linkReferenceDefinitions to off when using markdownlint

Environment

• VS Code
• Foam extension
• markdownlint extension (as default formatter)

Problem

When foam.edit.linkReferenceDefinitions is not set to off, Foam appends an autogenerated block:

 [//begin]: # "Autogenerated link references for markdown compatibility"
[example-note]: path/to/example-note.md "Example Note"
[//end]: # "Autogenerated link references"

markdownlint (rule MD053) flags:

• Unused definitions: [//begin] and [//end]
• After save cycles, markdownlint may autofix; Foam may re-add the block, resulting in duplicate link definitions and MD053 warnings.
• Resulting in editor flicker (Foam adds / formatter removes), noisy diffs, and duplicated blocks.

Expected behavior

• Foam appends an autogenerated block without [//begin] and [//end] autogenerated strings

[example-note]: path/to/example-note.md "Example Note"

Reproduction

1. Set:

   "foam.edit.linkReferenceDefinitions": "withExtensions",
   "[markdown]": {
     "editor.defaultFormatter": "DavidAnson.vscode-markdownlint",
     "editor.formatOnSave": true
   }

2. Create a file with wikilinks: [[example-note]]

3. Save repeatedly

4. Observe MD053 warnings and block churn

Solutions / Workarounds (I picked the first one)

1. Disable Foam link reference generation (simplest):

   "foam.edit.linkReferenceDefinitions": "off"

   Then suppress VS Code’s missing reference warnings:

   "markdown.validate.referenceLinks.enabled": "ignore"

2. Keep Foam, adjust markdownlint to ignore sentinel markers:
   .markdownlint.json:

   {
     "MD053": {
       "ignored_definitions": ["//begin", "//end"]
     }
   }

3. Keep Foam, locally disable MD053 around the block:

   <!-- markdownlint-disable MD053 -->
   [//begin]: # "Autogenerated link references for markdown compatibility"
   ...
   [//end]: # "Autogenerated link references"
   <!-- markdownlint-enable MD053 -->

4. Avoid wikilinks; use standard reference links (Foam preview will not resolve them):

   See [Example][example-note]
   
   [example-note]: path/to/example-note.md

Sample Minimal Settings (Workarounds 1)

{
  "foam.edit.linkReferenceDefinitions": "off",
  "markdown.validate.referenceLinks.enabled": "ignore",
  "[markdown]": {
    "editor.defaultFormatter": "DavidAnson.vscode-markdownlint",
    "editor.formatOnSave": true
  }
}

[riccardoferretti]

Yes to all that :)

I agree, ideally we'd remove the //begin and //end labels, let's say that was the easiest way to get started back in the days, but we can improve the code to work without those.

At the same time, the workarounds are pretty straightforward so I am not sure about the urgency connected to this issue.
I will still keep it on as I think it's a valid point and a first good issue for someone to work on.