Problem definition

1. Short codes are error-prone to write, with a huge number of matching delimiters.
2. Short codes are very hard to read, due to their verbose syntax, arbitrary ordering and lack of support on Github and in IDEs. e.g. {rust_type(type="struct" crate="bevy" mod = "ecs/system" name="EntityCommands" no_mod = "true")}}.
3. Short codes are a strange DSL that new contributors to the book must memorize.
4. Short codes force authors to look up the fully qualified path each type.
5. Short codes require authors to explicitly state whether a given import is a struct, enum, trait or so on.

Requirements

1. Human-legible form is easy to write and read.
2. Acceptable level: struct{{bevy::ecs::system::EntityCommands}}
3. Machine-legible form is standard zola-compatible HTML that links to the appropriate docs.rs page.
4. Docs links must support custom formatting.
5. Human-legible form is committed and reviewed.

Bonus points

1. Hot reloading still works.
2. Implicit imports: automatically assume Bevy prelude: struct{{EntityCommands}}
3. Type elision: {{bevy::ecs::system::EntityCommands}}
4. Explicit imports: list use bevy::ecs::system::EntityCommands at the top of the file, which is processed out, allowing the author to write struct{{EntityCommands}}.

Possible strategies

1. Fork Zola to add support for this.
   1. Probably more immediately elegant.
   2. Significantly more maintenance burden unless merged upstream.
   3. Should only involve writing our own tera functions.
   4. Best we can do is likely {{rs(name="App"}} due to tera limitations :(
   5. Difficulties integrating with our CI.
2. Add a Rust preprocessor which modifies the .md files provided.
   1. These are stored in the build directory and are not commited.
   2. Begin with simple instructions to run the preprocessor before zola serve.
   3. Eventually, wrap this in its own minimal CLI to support hot reloading and one-command builds.
3. Use reference style links instead of short-codes.
   1. Works out of the box!
   2. Very legible.
   3. No special formatting out of the box. Can this be added?
   4. Requires looking up the full URL, and modifying it to either use latest or doing a find-and-replace each Bevy version.