ehcache/ehcache.org-site

The raw source files for ehcache.org

This is the source code/files for the ehcache.org website. The files in this repository are source files, some of which include templating and other raw bits that need to be "compiled"/"built" in order to have files that are suitable to go onto a webserver.

Instructions for building/previewing

Contributing

• Clone this repository to your local system (if you're going to contribute content, fork it first, and clone that)
• Create a branch to contribute content - git checkout -b the_branch_for_the_pull_request

Mac

On Mac OS X, install Xcode command line tools by executing: xcode-select --install

Ruby

Ruby versions are not as nicely backward compatible as Java. We recommend to use something like rbenv that will allow you to select a specific Ruby version. We also recommend to run jekyll through bundler to insure
the right jekyll version will be used.

• Install rbenv, ruby-build and rbenv-gemset - brew install rbenv ruby-build rbenv-gemset (on OS X)
• Configure it - rbenv init and follow the instructions
• Install Ruby - rbenv install (the version is specified in .ruby-version)
• Install bundler - gem install bundler
• Install dependencies - bundle install (the will be installed in the .gems directory as configured in .rbenv-gemsets

Linking with Ehcache 3 repository

To generate the full site including Ehcache 3 docs, you need to link some Ehcache 3 directories in this repository.

You should do it for every version you want to work on.

pushd ${ehcache3_root_directory}
git worktree add ${ehcache.org_root_directory}/${version_dir} ${branch}
popd
ln -s $PWD/${version_dir}/docs/src/docs/asciidoc/user documentation/${version}

version	version_dir	branch
3.0	_eh3	release/3.0
3.1	_eh31	release/3.1
3.2	_eh32	release/3.2
3.3	_eh33	release/3.3
3.4	_eh34	release/3.4
3.5	_eh35	release/3.5
3.6	_eh36	release/3.6
3.7	_eh37	release/3.7
3.8	_eh38	release/3.8
3.9	_eh39	release/3.9
3.10	_eh310	master

Of course, if for some reason you want a specific tag for a version, just create a worktree based on the tag instead.

Linking with Terracotta events repository

The content of the events menu is coming from another repository. To see it in local, just clone the repository and add a link to it.

git clone [email protected]:Terracotta-OSS/terracotta.org-site-events.git
ln -s $PWD/terracotta.org-site-events ${ehcache.org_root_directory}/events

Jekyll

The website is rendered by Jekyll. It is built locally and the result is pushed to the website repository.

To generate and view (locally serve) the site bundle exec jekyll serve then point your browser at http://localhost:4000.

To simply generate the site use bundle exec jekyll build.

To generate the site including all production elements (ie analytics) JEKYLL_ENV=production bundle exec jekyll build

NOTE: If you used links to include Ehcache 3 documentation, you may see an error about watching the same folder twice - it can be ignored.

Html-proofer

Html-proofer is used to validate the content of the website. After building the site with jekyll you can run html-proofer through ./run_proofer.sh.

---

See the issue tracker if you are interested in improving the site in general.

---

Making Changes to the content

If you want to make changes to the website, make them here (in this repository) - as this is where all the source/files for the website are kept.

For instance:

• If there is a new release being made, generated javadoc (from the product build) should be put into the apidocs directory
• New official docs should be put into the documentation and/or generated directories as appropriate
• Pay attention to the content of the _config.yml file in the root of this repository as there are properties there that control various things just as which exact version of javadoc to show for what (e.g. at the time of this writing we link to 2.8.5 javadoc for all 2.8 documentation).
• After making your changes, commit them (remember to do your work in a branch) and create a pull request.

---

Deploying changes to the live webserver

ehcache.org is served/hosted by github. The webserver does NOT serve the content from this repository. It serves the exact content of another repository.

Once your pull request has been merged, the site is deployed automatically.

Contributing a blog post

1. Ensure you first edit _data/authors.yml to add your information
2. Create a new ASCII Doc file under _posts/blog. The file should be named with the following format: yyyy-MM-DD-title-in-lowercase.adoc
3. Add a header in your file. Modify the fields according to your post, especially for the title, headline, tags, authors and date

   ---
   layout: post
   title: "Your blog post title"
   headline: "Your blo post headline"
   categories: blog
   hidden: false
   author: your_author_key
   tags: [ehcache, website]
   date: 2016-05-04T18:00:00-05:00
   modified:
   ---
   

4. Send your pull request 👍

Contributing an external resource

Same rules apply as above, except that you have to put your file into _posts/resources and add a header like this one:

---
title: "Ehcache 3: JSR-107 on steroids"
headline: "Ehcache 3: JSR-107 on steroids at Devoxx Morocco by Louis Jacomet"
categories: resources
date: 2015-11-18T00:00:00-00:00
---

IMPORTANT: Your content MUST be short! Links, headline, title, that's all.

ehcache.org-site's Issues

Invalid links to sections inside pages

See http://www.ehcache.org/documentation/3.0/xml.html

• Link http://www.ehcache.org/documentation/3.0/xsds.html#_core should be http://www.ehcache.org/documentation/3.0/xsds.html#core
• Link http://www.ehcache.org/documentation/3.0/107.html#_supplement_jsr_107_s_configurations should be http://www.ehcache.org/documentation/3.0/107.html#supplement-jsr-107-s-configurations
• Link http://www.ehcache.org/documentation/3.0/xml.html#__code_cache_template_code_elements should be http://www.ehcache.org/documentation/3.0/xml.html#code-cache-template-code-elements

So we have a leading _ for anchors and again _ instead of - inside the anchor.
Also the layout of the page will hide part of the content when linking to an anchor.

Deprecate documentation about Ehcache Server

This should no longer be documented : https://www.ehcache.org/documentation/2.7/modules/cache-server.html#downloading

Prepare for Ehcache 3.0.2

Issue to keep track of all changes necessary for the Ehcache 3.0.2 release.

• Javadoc for 3.0.2
• Update references in files from 3.0.1 to 3.0.2

Prepare for Ehcache 3.0.1 release

Placeholder issue to keep track of all changes necessary for the Ehcache 3.0.1 release.

• Add new doc section on Expiry in TOC
• Javadoc for 3.0.1
• Update references in files from 3.0.0 to 3.0.1

Typos and suggestions on ehcache site

From Yi:

At http://www.ehcache.org/ main page

Typo in: "Ehcache is an open source, standards-based cache that boosts performance, offloads your database, and simplifyies"

The 4th bullet point for milestone3 features with just ellipses doesn't really serve much purpose. Perhaps it can link to the list of issues? e.g. https://github.com/ehcache/ehcache3/issues?q=milestone%3A%22Milestone+3%22

In the quick start, the 'new' is superfluous. There's also a typo in 'development'
"While new Ehcache 3.0 is still in developement"

The link to "user documentation" at the bottom going to http://www.ehcache.org/docs/user/3.0 gives a 404
There's a http://www.ehcache.org/documentation/3.0/, not sure if that's the same/intended target

Layout of the page will hide part of the content when linking to an anchor

See for example http://www.ehcache.org/documentation/3.0/xml.html#code-cache-code-elements

Dead link under Community | Jira (Ehcache 2)

The target URL contains an extra "jira" element:

https://jira.terracotta.org/jira/browse/EHC

The link target should be:

https://jira.terracotta.org/jbrowse/EHC

Clustered doc references `images/storagePools.png`: 404

... looks like this isn't there...

Missing links in Ehcache 3 documentation

Looks like some syncing needs to happen between the asciidoc generated table and the one existing on the website. I am guessing we have duplication here ... not sure if that can be removed ... but at least needs to be in sync.

See http://www.ehcache.org/documentation/3.0/

Extract ToC duplication in 3.0 documentation

The page http://www.ehcache.org/documentation/3.0/ is composed on one side of an asciidoc file from the ehcache codebase that contains a toc. At the same time, the template used to render these pages on the website includes docs3x_page.html which duplicates the toc.

Would be good to find a way to get rid of the duplication.

Visual clue to indicate old, current and future documentation

While Ehcache 3.0.0 has been released, with all its documentation under documentation/3.0, the upcoming 3.1.0 release will have a different documentation as clustered is added to it.
I believe the idea is to have that documentation under documentation/3.1.

Whenever we reach that point, it would be great to have a visual way on every page documentation to indicate which version is current and which is for a previous version.

And by the way, if we were to do that, it would be pretty easy to extend the visual clue so that we could publish documentation for a future version without risk of confusing users.

Opinions and suggestions welcome!

Enabling floating links to sections

See http://asciidoctor.org/docs/user-manual/#anchors

Prepare Ehcache 3.1.0 release

• Documentation for 3.1 under its own folder, keeping the 3.0 documentation available
  • Includes ToC updates for clustering section
• If possible, include fix for #45 even if we work on improving visuals later
• Legal doc updates
  • Link to https://confluence.terracotta.org/display/release/Third+Party+Licenses and remove files/legal
• Update announcement area of home page
• Update documentation root page to have links to both 3.0 and 3.1 items

Downloads page has invalid / outdated maven info

About: "Checkout recently released Ehcache 3."

The About page contains the following paragraph:

Checkout recently released Ehcache 3. It natively complies with JSR107 (JCache spec), supports offheap storage, and has many other additions and improvements.

This doesn't look great now that version 3 was released 7 years ago.

The first sentence should be removed and the second merged into the first paragraph.

Support sharing properly (cards meta tags)

This issue is to support sharing across social media properly by using twitter cards, facebook cards, G+ cards, etc.

Goal is to add some metadata entries in the header that contain the content title, caption, image, etc so that twitter and facebook can read them to generate a sharing card.

Also, links should include UTM tracking attributes.

Here are some details:

• https://moz.com/blog/meta-data-templates-123
• https://dev.twitter.com/cards/overview

Updates to have Ehcache 3 the main entry point at the time of GA

• Documentation landing page
• Downloads page
• maybe more ...

Link to TC doc missing

The docs says: Detailed instructions on how to configure and start a Terracotta server array can be found elsewhere., but a link to that elsewhere (or a WIP mention) would probably be great!

Deprecate documentation about Ehcache monitor

For example the following needs to be updated to better indicate the solution is deprecated and should no longer have any download link - which are dead anyway.

Formatting issue in 2.7 documentation

See for example http://www.ehcache.org/documentation/2.7/configuration/cache-size.html

Fix links in 2.7 documentation

Currently the 2.7 documentation is disabled because it contains a lot of invalid links.

From a quick look, we have links of the following style:

• http://ehcache.org/xref/net/sf/ehcache/search/aggregator/package-frame.html

They most likely need to be replaced by proper javadoc links, according to the new structure of the site.

No way to download the Ehcache Remote Debugger

There is no way to download the Ehcache Remote Debugger on the site which is mentioned in documentations:

https://www.ehcache.org/generated/2.9.0/html/ehc-all/index.html#page/Ehcache_Documentation_Set/co-rmi_about_the_remote_debugger.html

Download page mentions 3.8.1 as latest version, should it be 3.9.9 now ?

The page https://www.ehcache.org/downloads/ mentions 3.8.1 as latest version.
Shouldn't it point to the latest version of the 3.9.* branch ?

Otherwise, if there is some policy about even/odd minor versions, it could be documented here.

Invalid doc explanation

https://www.ehcache.org/documentation/3.8/getting-started.html#configuring-with-xml

<heap unit="entries">20</heap> 3
is incorrectly explained as : foo is declared to hold up to 2,000 entries on heap…​

<offheap unit="MB">10</offheap> 4
is incorrectly explained as : …​as well as up to 500 MB of off-heap memory before it starts evicting

Updates for Ehcache 3 milestone 3 release

_config.yml needs updated for latest ehc3 java doc

the javadoc for ehcache3 needs to point at the m3 docs.

Add legal notice to website

• File available from documentation page near the existing Legal Notice link
• File available from downloads page under the Ehcache 3 section, above the maven one

Link to docs from Ehcache 3 Quick Start (on home page) is probably wrong

Under "Not quite ready yet?" - it links directly to ehcache 3.0 docs. Probably at this point it should link to 3.1.x docs. Maybe for long-term "fool-proofness" it should just link to the root docs page.

Add ehcache-clustered-ext.xsd to "Configuration XSD" (xsds.html)

Typo in ehache 2.7 docs

There is a typo in ehcache 2.8 docs, with an unfortunate, superfluous "NOT", in a sentence that reads "Ehcache is not for both general-purpose caching...".

This occurs in file:

ehcache.org-site/documentation/2.8/get-started/introduction.md

The corrected wording, which is in other versions of doc is:

"Ehcache is not just for general-purpose caching, however, but also for caching Hibernate (second-level cache), data access objects, security credentials, web pages."

Add a "Talks" and "Resources" section

In the documentation section, we could add a "Talk" section with the following links:

Bringing javax.cache'ing to your application

• Video: https://spring.io/blog/2015/10/19/springone2gx-2015-replay-bringing-javax-cache-ing-to-your-application
  • Slides: http://www.slideshare.net/SpringCentral/bringing-javaxcacheing-to-your-app

Terracotta's OffHeap Explained

• Video: https://www.youtube.com/watch?v=xCojSZMp_Zw&index=1&list=FLIxdXH5lS08edKfvRIBe-ZQ
• Slides: http://www.slideshare.net/ChrisDennis7/terracottas-offheap-explained-55214150

Ehcache 3: JSR-107 on steroids

• Slides: http://www.slideshare.net/LouisJacomet/ehcache-3-jsr107-on-steroids-at-devoxx-morocco

There are the ones I know but I guess there are plenty other ones :-)

Add some web traffic monitoring and analysis

We should have some kind of traffic monitoring so that we know how well blog articles do, how much documentation gets consulted and so forth.

The following is a nice intro into enabling Google Analytics in a Jekyll site: https://michaelsoolee.com/google-analytics-jekyll/

Put a right margin on blog posts

http://www.ehcache.org/blog/2016/05/17/ehcache3_jsr107_spring.html

Hard to read when lines are long.