devdcores/ehcache.org-site

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	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 git@github.com: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

Ensure you first edit _data/authors.yml to add your information
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

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:
---

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.

devdcores / ehcache.org-site