Specify which markdown files zensical studio should be responsible for

[leoyala]

Context

At the moment, to make zensical studio work, we have to define the following in VSC settings:

{
  "files.associations": {
    "*.md": "python-markdown"
  }
}

This leads to the responsibility for each markdown file in the project being delegated to zensical studio, even for files where is not needed (e.g. ISSUE templates, README, etc.). At the same time this leads to error highlighting in such files, which are not really errors, simply not part of the zensical managed files.

Description

If possible, it would be great if zensical studio could be configured to inherit the responsibility for markdown files in specified locations, like the docs/ folder.
An alternative solution (not sure if possible) would be to let zensical work on top of the native VSC markdown behavior, so that we still have access to the native tools like the markdown preview window. At the moment I can only activate the preview window if I revert the changes to settings.json.

Related links

• Requesting a change
• VSC markdown extension guides

Use Cases

I believe addressing this would lead to simplified work for users, mainly: not having to switch between python-markdown and the native markdown support, and less false errors displayed in the IDE.

Visuals

This is an example of an error being indicated in an issue template, where it ideally shouldn't. You can also see from the snapshot that the preview button (and others) usually available in markdown files is not available because the responsibility has been delegated to zensical studio.

Before submitting

• I have read and followed the change request guidelines.
• I have verified that my idea is a change request and not a bug report.
• I have ensured that, to the best of my knowledge, my idea will benefit the entire community.
• I have included relevant links to the documentation, related issues or Discord discussions, to underline the need for my idea.
• I have read and accepted the Zensicals Terms of Service and the Zensical Studio End User License Agreement.

[squidfunk]

Thanks for suggesting. Can you please try the following:

{
  "files.associations": {
    "docs/**/*.md": "python-markdown"
  }
}

From 0.2.0 on which we released today, Zensical Studio is project-aware, so it should limit its work to the docs folder (and includes) as configured in mkdocs.yml or zensical.toml. Multi-project workspaces should also be supported already. If no file is present, all Markdown files are considered, which might explain the behavior. The file association is only necessary for highlighting, not for workspace intelligence.

We're moving very fast and need to update the docs, which we'll do in the coming days. If the above doesn't work for you, please attach a reproduction that showcases the issue, so we can investigate it.

[leoyala]

Even if I remove the file association entirely, somehow all the .md files are still associated with Python-Markdown. I am attaching a reproduction here and a screenshot to illustrate what I mean.

reproduction.zip

[squidfunk]

Ok, right, I think this might be a bug. So we should associate all files in docs, but not the README.md. We just shipped project-awareness, so this is likely related.

[rmscode]

I can confirm the same. Added docs/**/*.md but Studio is still checking the README.md outside of the docs dir.

[vepain]

The workspace configuration for file association must be modified to **/docs/**/*.md, see: https://stackoverflow.com/questions/49805677/how-can-i-match-intermediate-subdirectories-in-vs-code-files-associations

This fix the fact that only .md files under the subdirectory docs will be associated with python-markdown. However, this does not prevent Zensical Studio to lint regular Markdown files

[leoyala]

The workspace configuration for file association must be modified to **/docs/**/*.md, see: https://stackoverflow.com/questions/49805677/how-can-i-match-intermediate-subdirectories-in-vs-code-files-associations

This fix the fact that only .md files under the subdirectory docs will be associated with python-markdown. However, this does not prevent Zensical Studio to lint regular Markdown files

I tried this now, but after restarting the IDE or reloading the window, the behavior remains the same for me.

[vepain]

Interestingly, I remark that, if the extension is active in the workspace, if you have a zensical.toml file every markdown will be considered as python-markdown whatever the file association configurations are.

If I remove the zensical.toml, it respects the file association configuration.

To reproduce

Versions

• VSCode 1.127.0
• Zensical VSCode Extension 0.1.3

Settings

No file association in user settings for .md (or relative)

In project .vscode/settings.json:

{
  "files.associations": {
    "**/docs/**/*.md": "python-markdown"
  },
}

[rmscode]

The workspace configuration for file association must be modified to **/docs/**/*.md, see: https://stackoverflow.com/questions/49805677/how-can-i-match-intermediate-subdirectories-in-vs-code-files-associations

This fix the fact that only .md files under the subdirectory docs will be associated with python-markdown. However, this does not prevent Zensical Studio to lint regular Markdown files

As @leoyala mentioned, this does not work.

Interestingly, I remarks that, if the extension is active in the workspace, if you have a zensical.toml file every markdown will be considered as python-markdown whatever the file association configurations are.

If I remove the zensical.toml, it respects the file association configuration.

To reproduce

Versions

• VSCode 1.127.0
• Zensical VSCode Extension 0.1.3

Settings

No file association in user settings for .md (or relative)

In project .vscode/settings.json:

{
"files.associations": {
"/docs//*.md": "python-markdown"
},
}

I did not experience the same after removing my zensical.toml file. The README.md outside of the docs dir is still being checked by Studio.

[rmscode]

@squidfunk I noticed something ... Studio is looking inside my python .venv folder. I don't know what the implications of this would be, good or bad, but I would assume that Studio doesn't need to be checking virtual environments.

[squidfunk]

We scan for zensical.toml and mkdocs.yml files. We should probably refrain from doing that in virtual environments. However, note that later, Studio will need to access your virtual environment anyway in order to deeply integrate with Zensical or render previews. We will make this optional of course, so you can turn it off, but lose previews. Medium-term, previews will render completely without Python once we finish our Rust Markdown parser/renderer.

Zensical Studio is still in beta, and we're working our way to provide the best possible authoring environment for Zensical and MkDocs projects. With valuable feedback like this, we expect to fix all major issues and add much more powerful functionality in the coming months and reach stability quite fast ☺️