Simple references are only going to get you so far. In Antora, we made the tough but important choice not to be constrained by what GitHub allows and instead develop a robust and comprehensive referencing system that enables you to create the types of references that enterprise documentation requires. It's a trade-off for sure, but we believe one that will pay off in the long run. (And there's always a chance that GitHub will catch up).

In other words, we're not going to allow GitHub to dictate the type of references that we're allowed to make. It's simply too limiting. In the end, perfect GitHub preview just isn't that important, esp since the site is being continuously published in full fidelity (theme and all).

Best,

-Dan