Sortable list of files when using wildcard

[Adspectus]

I like the plugin, it almost perfectly matches what I am looking for and suits better than blog or macro or snippets. However, I wished to have the opportunity to sort the resulting list of a wildcard match. Curently it is the sort order of the underlying glob function, I guess. A good starting point would be the reverse order. A more sophisticated version would it to be sorted by any property within the files found.

[mondeja]

Makes sense! Any implementation proposal is welcome. Feel free to expose what would fit more your needs.

I would like a complete solution to be able to fulfill the most cases as posible. Probably an enum based on a string like "alphabetical", "alphabetical-reverse", etc... should be enough. What you're referring with "by any property within the files found"? Which properties are you thinking about?

[Adspectus]

Well, I would suggest to provide 2 additional options, sort-order and sort-criteria. sort-order is just asc ("ascending") or dsc ("descendig") and the implementation would just reverse the given list before returning. sort-criteria might provide values like "alphabetical", "numerical", "natural" or "ascii" or whatever is possible with python. As far I can see, the python glob you are using is not determining the order - it seems to be dependent of the underlying OS and its settings. Hence, an option in your pluglet would normalize possible differences.

While the above is just about applying any sorting to the returned list values of the glob, which are filenames, an implementation with respect to any property within the files found would be more expensive. Let's say, one could use the property importance with possible values 1, 2 and 3 in the yaml header of md-files and the sort-criteria would then be "importance". I admit that this could be to much overhead because it would be necessary to parse every file before returning the results.

[mondeja]

It seems too much overhead. I prefer to just implement a sort option with possible values "alphabetical", "alphabetical-reverse", "natural", "natural-reverse" and whatever more.

• Why do you need "numerical", "ascii" and the "importance" one?
• Is not "ascii" "alphabetical"?
• Is not "numerical" "natural"?
• At a first glance, the implementation proposal of "importance" looks like a too much arbitrary property. I prefer to not support YAML headers if we can use the file names to do the same thing. What is the use case of this?

[Adspectus]

Well, the second part (with YAML headers) is overhead, totally agree. It is just an idea for enhancement.

The first part, however, is a big gain at almost no cost. The possibility to just use the reverse order of what comes back from globbing could be just one option and one additional function call in python. The kind of sorting, i.e. "alphabetical", "numerical" and "ascii" produces different results depending on the characters used for filenames. Hence, from my point of view, it would make sense to take into account this as well. However this would introduce much more effort to implement.

Indeed I would suggest rather to use two options (one for the direction, on for the algorythm) because it is more flexible. By using only one option with combined value such as "natural-reverse" you need to extract both parts afterwards, and the user is forced even to decide upon the algo when she just wants the reverse of what comes back anyway. But this is totally up to you.

[mondeja]

Nope, to have two options for one functionality is an antipattern.

[mondeja]

Curently it is the sort order of the underlying glob function, I guess.

This is not true. Currently, the paths are alphabetically sorted after they are gathered from wildcard.

Moved this to #265. If someone wants to implement it go ahead. I'm not personally interested.

[Adspectus]

If you could give me a hint where to start, I could try to do it, i.e. where is the point when paths are sorted after gathered from the wildcard?

[mondeja]

The paths are sorted here, in the function filter_paths of the file process.py:

mkdocs-include-markdown-plugin/src/mkdocs_include_markdown_plugin/process.py

Line 518 in aa17cc0

response.sort()

The function filter_paths is called from resolve_file_paths_to_include, which is called from the main implementations in event.py:

https://github.com/mondeja/mkdocs-include-markdown-plugin/blob/aa17cc062d5a63caec5f43c0425974c6a34725be/src/mkdocs_include_markdown_plugin/event.py#L156C41-L156C70

mkdocs-include-markdown-plugin/src/mkdocs_include_markdown_plugin/event.py

Line 372 in aa17cc0

file_paths_to_include, is_url = resolve_file_paths_to_include(

So you need to add sort to DefaultValues:

mkdocs-include-markdown-plugin/src/mkdocs_include_markdown_plugin/directive.py

Line 32 in aa17cc0

DefaultValues = TypedDict(

To ARGUMENT_REGEXES as a string argument:

mkdocs-include-markdown-plugin/src/mkdocs_include_markdown_plugin/directive.py

Line 94 in aa17cc0

ARGUMENT_REGEXES = {

To the configuration, to be able to set the value globally:

mkdocs-include-markdown-plugin/src/mkdocs_include_markdown_plugin/config.py

Line 13 in aa17cc0

class PluginConfig(Config): # noqa: D101

Pass them to get_file_content:

mkdocs-include-markdown-plugin/src/mkdocs_include_markdown_plugin/event.py

Lines 660 to 671 in aa17cc0

	{
	'encoding': config.encoding,
	'preserve-includer-indent': config.preserve_includer_indent,
	'dedent': config.dedent,
	'trailing-newlines': config.trailing_newlines,
	'comments': config.comments,
	'rewrite-relative-urls': config.rewrite_relative_urls,
	'heading-offset': config.heading_offset,
	'recursive': config.recursive,
	'start': config.start,
	'end': config.end,
	},

And then parse the sort directive argument in the implementations of include (found_include_tag) and include-markdown (found_include_markdown_tag) directives at event.py. For example, this is the implementation of another string argument like exclude:

mkdocs-include-markdown-plugin/src/mkdocs_include_markdown_plugin/event.py

Lines 137 to 154 in aa17cc0

	if 'exclude' in used_arguments:
	exclude_match = ARGUMENT_REGEXES['exclude']().search(
	arguments_string,
	)
	exclude_string = parse_string_argument(exclude_match)
	if exclude_string is None:
	location = process.file_lineno_message(
	page_src_path, docs_dir, directive_lineno(),
	)
	raise PluginError(
	"Invalid empty 'exclude' argument in 'include'"
	f' directive at {location}',
	)
	for path in resolve_file_paths_to_exclude(
	exclude_string, page_src_path, docs_dir,
	):
	ignore_paths.append(path)

To be able to pass them to resolve_file_paths_to_include and from there to filter_paths or whatever refactoring you do to pass them.

To test it, use test_include_markdown and test_include:

mkdocs-include-markdown-plugin/tests/test_unit/test_include_markdown.py

Line 761 in aa17cc0

def test_include_markdown(

mkdocs-include-markdown-plugin/tests/test_unit/test_include.py

Line 358 in aa17cc0

def test_include(

Or maybe use another file like test_glob_include.py. Whatever you feel the right location.

To understand the architecture of the code, think that plugin.py calls to event.py (where reside the implementations of the directives include and include-markdown) and all the other files are all just utilities, being directive.py the utilities more correlated to the directive/arguments parsing and process.py the utilities of content processing.

[mondeja]

This is going to be released in a few minutes with v7.2.0

[mondeja]

See the new order argument.