Ignored `.md` files should not be read with `jupytext`

[jorenham]

As I also explained in mwouts/jupytext#1306 (comment), the Plugin.should_include at

mkdocs-jupyter/src/mkdocs_jupyter/plugin.py

Lines 60 to 86 in a3cded5

	def should_include(self, file):
	ext = os.path.splitext(str(file.abs_src_path))[-1]
	if ext not in self._supported_extensions:
	return False
	if ext == ".md":
	# only include markdown files with jupytext frontmatter
	# that explicitly specifies a python kernel
	try:
	data = jupytext.read(file.abs_src_path)
	if not (
	(meta := data.get("metadata", {}))
	and (kernelspec := meta.get("kernelspec"))
	and kernelspec["language"] == "python"
	):
	return False
	except Exception:
	return False
	srcpath = pathlib.PurePath(file.abs_src_path)
	include = None
	ignore = None
	for pattern in self.config["ignore"]:
	if srcpath.match(pattern):
	ignore = True
	for pattern in self.config["include"]:
	if srcpath.match(pattern):
	include = True
	return include and not ignore

will attempt to read any .md with jupytext.read, even if .md files are configured to not be included, or to be ignored.

In https://github.com/jorenham/lmo/, this results in many confusing warning messages to be logged to stderr, specifically, the following is printed 12x when I run uv mkdocs build:

INFO    -  MissingIDFieldWarning: Cell is missing an id field, this will become a hard error in future nbformat versions. You may want to use `normalize()` on your notebooks before validations (available since nbformat 5.1.4). Previous versions of nbformat are fixing this issue transparently, and will stop doing so in the future.
             File "/home/joren/Workspace/lmo/.venv/lib/python3.12/site-packages/nbformat/validator.py", line 351, in _normalize
               warnings.warn(
             File "/home/joren/Workspace/lmo/.venv/lib/python3.12/site-packages/nbformat/__init__.py", line 96, in
               validate(nb)

As you can see from mwouts/jupytext#1306, it took me many hours to figure this out, so I think I at least deserve a cookie now. And it would be even better if this could be fixed :)

[gbrandt1]

seeing this as well. ignore option doesn't work. please fix. thanks

[aazuspan]

The underlying issue seems to be that jupytext parses the mkdocstrings autodoc syntax without errors but (unsurprisingly) complains about its formatting. For example:

import jupytext

jupytext.reads("::: foo", fmt="md")

.../lib/python3.12/site-packages/nbformat/__init__.py:96: MissingIDFieldWarning: Cell is missing an id field, this will become a hard error in future nbformat versions. You may want to use `normalize()` on your notebooks before validations (available since nbformat 5.1.4). Previous versions of nbformat are fixing this issue transparently, and will stop doing so in the future.
  validate(nb)

As @jorenham found, mkdocs-jupyter parses every Markdown file with jupytext before checking ignore patterns, so every Markdown file with mkdocstrings syntax throws that warning, even if the file is ignored.

Whether or not ::: foo should be a parseable input for jupytext, checking the ignore patterns first in Plugin.should_include seems like an easy fix, as that would resolve this issue (and avoid some unnecessary parsing) for users who are explicitly ignoring .md files.

I'm happy to make a PR with that fix.