This theme is currently experimental, but intended to provide the branding for Jakarta EE projects using GitHub pages for their documentation. This Jekyll theme is intended to copy the theme of the main https://jakarte.ee website so the projects use branding that is consistent with the main website.
Jakarta EE projects typically publish their documentation using the GitHub pages functionality of the source code repository on GitHub.
This involves pushing the documentation materials to the gh-pages
branch in the repository. Once content has been pushed to this branch
it is publish statically at https://eclipse-ee4j.github.io/<projectname>
. Without a theme, the site will be published using a default
theme.
To use this theme in GitHub pages, simply specify:
remote_theme: jakartaee/jekyll-theme-jakarta-ee
in _config.yml
at the root of the gh-pages
branch.
Once the project has been set to use the theme, the project team should review each page on the site to ensure it renders correctly. Any problems with the theme should be raised as an issue on this project, and pull requests are most welcome.
If you are publishing html files directly from gh-pages
, please note that these are likely to require some additional work to ensure
the correct CSS and Javascipt is pulled in.
The _config.yml
can contain variables to control the content in the
Project Resources box on the right side of the page:
links.source
- a URL to the source codelinks.javadocs
- a URL to the javadocslinks.docs
- a URL to other documentationlinks.faq
- a URL to Frequently Asked Questionslinks.download
- a URL to a download pagelinks.hide_issuetracker
- set to true to disable the default link to the project's Issue Tracker pagelinks.mailinglist
- a URL to the project's mailing list
For example, the configuraion for the JavaMail project page sets these links:
links:
source: https://github.com/eclipse-ee4j/javamail
javadocs: docs/api/
download: https://github.com/eclipse-ee4j/javamail/releases
mailinglist: https://accounts.eclipse.org/mailing-list/javamail-dev
faq: FAQ
Note that some of the links are relative references to other pages in the
gh-pages
branch.
Some of the javaee GitHub organization projects have existing gh-pages
web sites that are being contributed to Eclipse.
These sites can be converted to the new scheme by replacing the theme
entry with the remote_theme
entry specified above, and by changing the
links in the _config.yml
file.
The _layouts
directory can be removed.
The assets
directory can most likely be removed, unless it contains
assets (e.g., images, css) used by pages in the web site.
Follow these steps to run and check your project's site locally on your machine. Further instructions for Jekyll and GitHub pages can be found here:
Pre-requisites:
- Ruby 2.1.0 or greater (check with
ruby --version
)
Instructions:
- (1 time only) Ensure you have a Gemfile in the root of your project with the following content:
source 'https://rubygems.org'
gem 'github-pages', group: :jekyll_plugins
gem 'jekyll-theme-jakarta-ee'
-
(1 time only) Install the
bundler
gem:gem install bundler
-
Install Jekyll and other dependencies:
bundle install
-
Switch the theme in
_config.yml
. Change this
remote_theme: jakartaee/jekyll-theme-jakarta-ee
to
theme: jekyll-theme-jakarta-ee
This will make sure the locally installed Gem will be used to render the site.
- Run the Jekyll site locally:
bundle exec jekyll serve
To build the theme itself, clone this repository (or your own fork of it), and do the following:
Pre-requisites:
-
Ruby 2.1.0 or greater (check with
ruby --version
) -
Install the
bundler
gem:gem install bundler
-
Install the dependencies:
bundle install
-
Build the Gem:
gem build jekyll-theme-jakarta-ee.gemspec
Pushing the Gem to RubyGems
(please update the version number in jekyll-theme-jakarta-ee.gemspec
)
gem push jekyll-theme-jakarta-ee-*.gem