[hibernate-dev] People can't find our docs

[Guillaume Smet]

On Thu, Jul 21, 2016 at 2:07 PM, Emmanuel Bernard
<emmanuel at hibernate.org> wrote:
> Should we add a X or I got it button to remove this nagging when I have
> to read and stay on the old doc?

I thought about it but I don't find it that invasive that we need to
add a close button. But I can do it if people think it's needed. I
suppose we would need a cookie to keep the information during the
navigation on the doc.

> If that piece of code is in the xsl, how will it work when the doc is in
> the distribution?

It won't work. It won't be able to load the Javascript files (the //
doesn't work with file:// protocol, and
/hibernate/_outdated-content/outdated-content.js will not be present).
I can make it work by using absolute URLs for everything but I thought
it was better to not have it in the distribution doc: if you have
downloaded a particular version of the doc, you probably want to read
this version.

> How screwed are you if we stop using these stylesheet and say embrace
> the Asciidoctor default style?

Well, either we can include top and bottom template anyway or we have
to run a sed on the files before uploading them to the doc server.

Maybe we should even do it this way and add the sed calls in our
release process. This way, it won't be in the distribution doc and we
won't have to alter the stylesheets.

Basically, we have to execute this in the reference directory (I
didn't do the work for the Javadoc, would it be useful?):
# Hibernate Search

find . -name \*.html -exec sed -i 's@</body>@<script
src="//code.jquery.com/jquery-3.1.0.min.js"
integrity="sha256-cCueBR6CsyA4/9szpPfrX3s49M9vUU5BgtiJj06wt/s="
crossorigin="anonymous"></script><script
src="/hibernate/_outdated-content/outdated-content.js"
type="text/javascript"></script><script
type="text/javascript">$(document).ready(function() {
HibernateDoc.OutdatedContent.install("search"); });</script></body>@'
{} \;

find . -name \*.html -exec sed -i 's@</title><link
rel="stylesheet"@</title><meta name="description" content="Hibernate
Search, full text search for your entities - Reference Documentation"
/><meta name="keywords" content="hibernate, search, hibernate search,
full text, lucene" /><meta name="viewport"
content="width=device-width, initial-scale=1.0" /><link
rel="canonical"
href="https://docs.jboss.org/hibernate/stable/search/reference/en-US/html_single/"
/><link rel="stylesheet"@' {} \;

We might even include <!-- HibernateDoc.Outdated Content--> xxxx <!--
/HibernateDoc.OutdatedContent --> markers to be able to update the
code easily in the future. Same for the meta.

-- 
Guillaume