+1 for a deprecated macro from me.
I agree with adding a version. Is there any reason why this should be optional? I don’t see a case where we have something deprecated without a version for its deprecation (even if it’s just approximative, in which case it still gives an idea of how old it was deprecated for). I believe in our use case a mandatory since would make sense.
We could enforce that the deprecation is done properly with more parameters. E.g.
Useinsteada link or text referencing what this was replaced with. AFAIK we don’t want feature regression in XWiki and every deprecation comes with a new tool that produces the same result but with an improved implementation or UX.
Thank you for the clarification! Do we have a place where this is written down in our doc guide? I remember scouring through plenty of our doc pages to try and find information similar to this. I remember a somewhat recent example of the definition being unclear causing small misunderstandings Proposal: deprecate silk icons theme
Note: This could be a great entry for the glossary. Deprecated has a special meaning in the XWiki project that goes beyond the english definition.
Thank you for sharing your progress on the documentation reorganization!
Lucas C.