Github's convention that web pages for a project are in a different branch of the same project is kind of strange.
It does have the advantage of 0-configuration 0-conflict.
But because it namespaces through the branch, if you're using the repository for something other than just the pages you can't have the gh-pages simply follow/trail master unless you want a bunch of site crap at the root of your repository, and interacting with both code and documentation at the same time is more painful than it needs be.
Also, those things they call "conrefs" are just "macros".
Macros have a wider implied range of behavior, possibly completely arbitrary.
A content reference attribute is just a placeholder or a very small textual include[0] (XML calls them "named entities", rST calls them "substitutions")
Comments
It does have the advantage of 0-configuration 0-conflict.
But because it namespaces through the branch, if you're using the repository for something other than just the pages you can't have the gh-pages simply follow/trail master unless you want a bunch of site crap at the root of your repository, and interacting with both code and documentation at the same time is more painful than it needs be.
Macros have a wider implied range of behavior, possibly completely arbitrary.
A content reference attribute is just a placeholder or a very small textual include[0] (XML calls them "named entities", rST calls them "substitutions")
[0] usually not of a complete document