Annotations to published content
One of the first thing users of my (very much still forthcoming!) Antora website mentioned after a brief demonstration is that they would like the ability to annotate documentation with their own comments. I almost burst into tears
I suspect this requirement comes because we would be transitioning from a Microsoft Word based environment and the ability to annotate documents and add comments is widely used in a corporate environment to comment on policy and guidance and as part of the review and approval process.
After a little research my fears have been found to be unfounded
I note that the service for storing comments, AnnotateIt closed in about May 2017. However their website contains some valuable information:
- A blog entry about web annotations as a W3C standard.
- The W3C recommendations for annotation.
- A successor (presumably following the W3C recommendations) called h. or hypothes.is. This is 2-clause BSD open source and development is on Github.
Hypothes.is can be tested with Antora by simply including the following in
footer-scripts.hbs for example:
<script src="https://hypothes.is/embed.js" async></script>
Obviously we can't do this for the default UI as the policy for this is is that it must function offline (a fine thing in my view and one that matches my current use case where deployment may occur in a restrictive corporate environment).
It's a little unclear how integration might occur. The instructions indicate an application OAuth token is required and then the build is customised to these as expressed in environment variables.
The approach with the default UI and various forks for theming and plugins within Antora is a little unclear at the moment (partly related to #65) perhaps partly because the focus up to this point has been the core.
So I log this issue mainly as a possible future development option and for general interest...