[feature] I'd like to specify the order of preprocessors

[JakubKoralewski]

I'm building a preprocessor, but it requires that I work on the markdown file that already has the links resolved, i.e. it should have the {{ #playpen }}, {{ #include }}, and {{ #rustdoc_include }} already resolved. I'd like to work on Markdown files that have those included files in the Markdown.

Very simply it would be awesome if I could just do:

[preprocessor.links]
[preprocessor.custom]
command = "cargo run --manifest-path=../../Cargo.toml --bin mdbook-custom"

But since this creates a toml table, it would require either:

1. a depends key in the custom preprocessor, like so:

[preprocessor.custom]
command = "cargo run --manifest-path=../../Cargo.toml --bin mdbook-custom"
depends-on = "links"

Note that in this hypothetical solution explicitly marking the [preprocessor.links] would not be needed.

2. Making the preprocessor into a list.

[[preprocessor]]
name = "links"
[[preprocessor]]
name = "custom"
command = "cargo run --manifest-path=../../Cargo.toml --bin mdbook-custom"

And after this configuration, each preprocessor would work on the book that has already been preprocessed by the preprocessors defined before it (if it is not the first).

If this is already possible, or a workaround exists please let me know (thx).

[JakubKoralewski]

Ok, this is embarassing. I gave the wrong path for the file, that's why it wasn't included. It now behaves as expected. Sorry.

Anyway, I guess in theory, if there was a lot of custom preprocessors (since it seems like you hardcoded links to run before all the other custom preprocessors(?)) it would be a useful feature to have some day.

[remexre]

I kinda want this too, but as a workaround, preprocessors seem to be run alphabetically, so:

[preprocessor.00-repl]
command = "mdbook-repl"

[preprocessor.10-katex]
command = "mdbook-katex"

works. From looking at the source code, seems that depending on what the feature solver determines, preprocessors may run in alphabetical order (default) or in the order they appear in the TOML file (if the toml crate's preserve_order feature gets flipped on in the future), so ordering them both alphabetically and lexically should be sufficient.

[ISSOtm]

I can suggest several options:

• Allow explicitly specifying the order of preprocessors in a table:

  [preprocessors]
  order = [ "early-bird", "links" ]

  Possibly with special syntax to indicate "run any preprocs not in the table here", for example with a special "..." entry. Its absence would cause an error if not all preprocessors are mentioned in the table.

  👍 Trivial to process
  👎 Requires maintenance from the user

• Allow preprocessors to have an priority key:

  [preprocessors.early-bird]
  priority = "1" # Run before `links`

  👍 Simple to process
  👎 Final ordering is not obvious at a glance; is a larger number a higher or lower priority; may require a lot of changes when inserting a new preproc; what to do if the key is missing from an entry

• Allow preprocessors to have a before and after key:

  [preprocessors.early-bird]
  before = [ "links" ] # We generate some links

  👍 The user specifies exactly what they want
  👎 Requires mdbook to resolve dependencies, which is costly and difficult (I'm not aware of any algorithms for this) Require topological sorting of the tasks, that's about it

[remexre]

Allow preprocessors to have a before and after key

That's topological sorting, as implemented by e.g. the topological-sort crate, isn't it?

[bombsimon]

I'm interested in this as well but the opposite which makes this issue relevant. I want to create dynamic content that includes another file like this:

Chapter::new(
    "Chapter 1",
    "{{ #include some_chapter.md }}".into(),
    std::path::PathBuf::from("chapter_1.md"),
    vec![],
);

But since the links preprocessor has already been executed my result will just be the raw {{ #include some_file.md }}. Is there any way to do this until this order feature is implemented?

[ISSOtm]

One way is to use a fork of mdBook with PR #1607... :/ I'm doing that locally for #1549, but it may be more problematic to actually deploy such a fork.