Hi all! So here is a status of what I did: - I updated the /stable/ link of ogm from 3.0 (cough, cough) to 5.0: http://docs.jboss.org/hibernate/stable/ogm/reference/en-US/html/: we need to include this in our release process. - I updated the /current/ symlink of ORM to point to 5.2 instead of 5.1: it needs to be integrated in the release process; (the /stable/ link uses the /current/ symlink so it's also fixed) - I removed the docs for OGM 3.0 as they were a copy of the doc of OGM 4.2
Next, I applied some magic to 2 old versions of OGM and Search so that you can check everything is OK for you before I generalize it: - Add meta description and keywords - Add a canonical link to the /stable/ single html version - Add a piece of Javascript to warn the user and propose to redirect him to the best possible place of our last stable release documentation See the 2 examples here: http://docs.jboss.org.local/hibernate/ogm/4.1/reference/en-US/html/ogm-architecture.html (scroll to see the hash tracker in action) http://docs.jboss.org/hibernate/search/4.2/reference/en-US/html/search-architecture.html See the current code and descriptors here: https://docs.jboss.org/hibernate/_outdated-content/ The script and the descriptors work for all existing versions of the OGM and Search doc. The marker to include in the docs looks like that: <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> (I'm using a CDN but maybe we should host jQuery on docs.jboss.org?) The script is capable to redirect either to the multi page version (using the redirects declared in the JSON file: it automatically cumulates the redirects from version X to version Y so we don't need that much metadata) or to the single page version by leveraging the anchors and hashes. For now, I decided to push the user to the single page version as it's the one we use for the canonical link but we can of course discuss it. Note that I add a ?v=X.X parameter to be sure the user is redirected to a fresh version of the corresponding /stable/ page and not a cache. I had the issue a couple of times. Next if you like it: - generalize it to all the existing versions of the docs, sed FTW - modify the Hibernate XSL stylesheets to include it in the newly generated ones - probably modify our website so that the stable release points to the /stable/ link to the docs - do the same for Validator @ORM: interested in me pursuing this for ORM too? It will probably be a lot more work as the structure of the docs got changed a lot. Comments, opinions, thoughts welcome. -- Guillaume On Wed, Jul 20, 2016 at 12:06 PM, Davide D'Alto <dav...@hibernate.org> wrote: > I'll try to apply these changes on Friday. > > Davide > > On Tue, Jul 19, 2016 at 11:53 PM, Guillaume Smet > <guillaume.s...@gmail.com> wrote: >> Hi Sanne, >> >> Thanks for your feedback. I was pretty sure I hadn't all the history! >> >> Getting Google to prioritize our latest doc is probably a long time goal. >> >> I played a bit with jQuery to suggest to the user to go to the latest >> stable. Note that I only took into consideration the page for the time >> being and didn't consider the anchor but it should be easy to add it >> if we think it's worth it (it's a lot more work on the json descriptor >> though). >> >> The following command for each version is all that is needed: >> sed -i 's@</body>@<script >> src="http://code.jquery.com/jquery-3.1.0.min.js"; >> integrity="sha256-cCueBR6CsyA4/9szpPfrX3s49M9vUU5BgtiJj06wt/s=" >> crossorigin="anonymous"></script><script >> src="/hibernate/search/outdated-version.js"></script></body>@' *.html >> (or a find -exec to do it on all the versions at once) >> >> I attached the global json descriptor and the js file (with a .txt >> extension as it didn't pass the mail filter). Both should be added to >> /hibernate/search/. Note that I only did the work for version 4.5 in >> the json descriptor. The work for other versions would mostly be a >> copy/paste. >> >> I also attached a screenshot of how it looks like. Nothing fancy but >> we can do whatever we want. >> >> Note that I only targeted the multi page HTML output as it was the >> most interesting to prototype. >> >> When we release a new version, we would have to update the descriptor file. >> >> Comments? >> >> -- >> Guillaume _______________________________________________ hibernate-dev mailing list hibernate-dev@lists.jboss.org https://lists.jboss.org/mailman/listinfo/hibernate-dev
