This document will guide you through the ways of website edition.
1. TL;DR
Wanna start hacking right away? This section is for you.
Look at the search
directory for inspiration in content, structure and markup examples.
To start a new project, for example ORM, do the following:
-
create the project directory
mkdir orm
-
copy the pages from search
cp -R search/ orm
-
create a project section in
_config/site.yml
underprojects
.-
best is to simply copy the search subsection and update the data
-
the project section name is lowercase and corresponds to the URL path (
search
and nothibernate-search
)
-
-
edit the pages (*.haml, *.adoc) under
orm/
and replace theproject
orawestruct-project
attribute to the lowercase project name
2. Prerequisites
Follow the README instructions to get Awestruct and its dependencies up and running.
3. How to edit
Use your favorite editor, for example vim. All pages are using text based markups with various degrees of flexibility and readability. Indentation is two spaces.
In Ruby indentation matters, be careful. |
3.1. Live reload (optional)
You can make the editing/reviewing work-flow faster by using the livereload plugin in your browser.
-
Install the appropriate live reload plugin.
-
Start
guard
(in separate terminal from the root of the repository checkout)bundle exec guard
Every time you save a file, the web page will be automatically reloaded assuming you have activated the browser plugin.
4. Add a page
- HAML
-
HAML is close to HTML and let’s you use Ruby. Use this when you need special layouts in your page or use the site metadata. In general, only super users should use them.
- Asciidoc
-
Asciidoc is a markup language close to Markdown but more powerful. When you start a page, prefer this format. The best resource to learn the Asciidoc syntax are the writer guide and the syntax quick reference.
Best of both worlds?
You can embed Asciidoc fragments inside a haml page.
|
A file named downloads.html.haml
or downloads.adoc
in the search
directory will generate /search/downloads/index.html
that we reference as /search/downloads/
at it makes for nicer URLs. If you plan to create several pages under the download/
path, create the download
directory and add search/downloads/index.html.haml
or search/downloads/index.adoc
.
4.1. Page attributes
Each page has some metadata attributes associated and put at the top of the file.
----
# note that the first block in haml should be surrounded by `---` and not `----`
# but a rending bug prevents the listing to properly show it
layout: project-frame
title: About Hibernate Search
project: search
title_partial: project/title-about.html.haml
----
-# Center body
.row-fluid
.span8
.feature-block
:asciidoc
=== Full-text search for entities
Offers full-text search support for objects stored by Hibernate ORM, Infinispan and other sources.
Think of it as Google(tm) for your entities:
* search words with text
* order results by relevance
* find by approximation (fuzzy search)
= Hibernate Search FAQ
Emmanuel Bernard
:awestruct-layout: project-standard
:awestruct-project: search
:toc:
:toc-placement: preamble
:toc-title: Questions
You've got a question burning you? We might have the answer for you.
== Indexes
=== No file created in index directory
Hibernate Search won't create a new index in existing directories.
Here is a list of the most useful attributes.
- layout (or awestruct-layout in Asciidoc)
-
Represents the layout the page will use. Layouts are present in the
_layout
directory - title
-
The page title.
The page title of an Asciidoc file is the text in the first line following
=
.= Some title :some-attribute: value Preamble (usually bigger) == First section Some text.
- project (or awestruct-project)
-
Optional. Represents the project the page descrcibes. Used to properly compute navigation. Mandatory if the page is under the project subdirectory.
- toc (Asciidoc only)
-
Optional. Enable the rendering of the table of content in Asciidoc documents
- toc-placement (Asciidoc only)
-
Mandatory if
toc
is used. On this website, the table of content position is imposed and defined in css. Just set the value to preamble. - toc-title (Asciidoc only)
-
Optional. Defines the table of content title. Defaults to Table of content.
- numbered (Asciidoc only)
-
Number the sections and the ToC.
4.2. List of layouts
Layouts are used to share the same site structure. They can be nested.
All are in the _layouts
directory.
There are a few important layouts:
-
project
(project.html.haml
): structure of a generic page (we will change the name in a little while) -
project-frame
(project/project-frame.html.haml
): structure of a project specific page. All files undersearch
,orm
,validator
etc. use this layout -
title-nocol
(common/title-nocol.html.haml
): structure of a generic page with a title and no column. Useful for generic Asciidoc pages like this one. -
project-releases
(project/project-releases.html.haml
): structure of the/releases/
page of each project. -
project-releases-series
(project/project-releases-series.html.haml
): structure of series-specific pages of each project (e.g./search/5.8/
). -
project-documentation
(project/project-documentation.html.haml
): structure of the/documentation/
page of each project (except ORM).
5. Update releases
5.1. Add a new release
To add a release, you will need to add a release file in the _data
directory.
The file will have to be named <full version number>.yml
(for example 5.8.0.Final.yml
)
and be located in _data/<project ID>/releases/<series version>/
.
You should never remove the files related to previous releases: they are used to generate links to all JIRA tickets of a given series, for instance. |
If your release is the first one of a new series, you will also have to create a new series.yml
file
in the _data/<project ID>/releases/<series version>
directory.
For information about the content of each file, see here.
5.2. Series status
By default, a series will have the following status (the small label appearing here and there on the website):
-
development
if all it’s releases are unstable (still in development); -
latest-stable
if it’s the latest series with a stable release; -
end-of-life
otherwise.
To override this status,
edit the _data/<project ID>/releases/<series version>/series.yml
file
to set the status
attribute to true
(just add the attribute if it is missing).
This attribute can in particular be set to:
limited-support
-
to convey the intent of not automatically fixing all bugs, while downstream frameworks (Quarkus, WildFly) or commercial offerings (RHBQ, RHEAP) may still provide stronger guarantees.
stable
-
to convey the intent of still actively maintaining the series, even if it is not the latest stable.
By default, an end-of-life’d series is considered "older" and not displayed with the other series: it is not displayed in the drop-down "Releases" submenu, it is moved to its own "Older series" section in the page listing all series, and it is not displayed in the project’s compatibility matrix.
You can override this behavior, to hide a non-EOL’d series or display an EOL’d series,
by editing the _data/<project ID>/releases/<series version>/series.yml
file
and setting the displayed
attribute to true
or false
(just add the attribute if it is missing).
5.3. Hide a specific release
To hide a specific release (not a series),
edit the _data/<project ID>/releases/<series version>/<release version>.yml
file
to set the displayed
attribute to false
(just add the attribute if it is missing).
To only hide download links and Maven coordinates,
set the available
attribute to false
(just add the attribute if it is missing).
6. Data
6.1. _config/site.yml
The site.yml
file contains site-related, YAML-formatted data.
This includes some project-related data.
See the file for more information about available attributes.
6.2. _data
The _data
directory contains YAML-formatted data for the releases of each project.
The structure of this directory is as follows:
-
<project ID, e.g.
search
>-
releases
-
<series version, e.g.
5.8
>-
series.yml
(data about the series) -
<one file for each release in this series, e.g.
5.8.0.Final.yml
>
-
-
-
The series.yml
file may contain the following attributes:
-
Mandatory:
-
summary
: a short text (one or two sentences) summarizing the specifics of this series. You can use Asciidoc syntax here.
-
-
Optional:
-
displayed
:true
to display the series on hibernate.org,false
to hide it. Defaults tofalse
. -
displayed
: whether this series should be displayed. Defaults to false. -
artifacts
: an array of objects, one object for each Maven artifact . Each object has the following attributes:-
artifact_id
: the Maven artifact ID. -
group_id
: the Maven group ID. Optional: defaults to the group ID defined on the series, or on the project. -
summary
: a short text (6/7 words at most) summarizing the purpose of this artifact. You can use Asciidoc syntax here.
-
-
integration_constraints
: a map, with keys being the integration IDs defined insite.yml
, and values being objects with aversion
attribute describing the version constraints summarily (about a dozen characters, and you can use Asciidoc syntax here).
-
The <release>.yml
files must be named after the release version (e.g. 5.6.0.Final.yml
)
and may contain the following attributes:
-
Mandatory:
-
date
: the date of the release. Format isyyyy-mm-dd
. -
stable
:true
for stable releases (*.Final
),false
for development releases (alpha, betas, CRs, …)0
-
-
Optional:
-
announcement_url
: the URL of the blog post announcing the release. -
summary
: a one-sentence summary of the content of the release. You can use Asciidoc syntax here. -
displayed
:true
to display the release on hibernate.org,false
to hide it. Defaults totrue
. Note that a release will only be displayed if its series is displayed.
-
7. Preview changes on staging.hibernate.org
Use git to push your changes to the staging branch on GitHub.
The staging site can be used for various experiments with the site L&F and content.
For this reason, ou might need to use git push --force
to overwrite previous experiments.
Pushing changes to the staging branch will trigger the staging.hibernate.org job on the Hibernate CI Server. The content of staging.hibernate.org will be automatically updated as part of a successful build.
8. Publish changes to hibernate.org
Use git to push your changes to the production branch of the repository on GitHub.
When adding a new release to the site, one needs to make sure that the release artifacts are already published. Part of the site generation is to parse the release metadata from the release POM. If the artifact is not yet published an error will occur! |
Your changes need to be a fast forward of the production branch. Never use the --force
option in this case!
If you have a push error, rebase first and possibly repeat the staging phase.
Pushing changes to the production branch will trigger the www.hibernate.org job on the Hibernate CI Server. The content of hibernate.org will be automatically updated as a result of a successful build.