Skip to content

Latest commit

 

History

History
340 lines (255 loc) · 13.2 KB

survival-guide.adoc

File metadata and controls

340 lines (255 loc) · 13.2 KB
Raw

Survival guide to website editing

This document will guide you through the ways of website edition.

Table of Contents

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:

  1. create the project directory mkdir orm

  2. copy the pages from search cp -R search/ orm

  3. create a project section in _config/site.yml under projects.

    1. best is to simply copy the search subsection and update the data

    2. the project section name is lowercase and corresponds to the URL path (search and not hibernate-search)

  4. edit the pages (*.haml, *.adoc) under orm/ and replace the project or awestruct-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.

Caution
 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.

  1. Install the appropriate live reload plugin.

  2. 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

There are two types of pages, HAML based (*.html.haml) and Asciidoc (*.adoc).

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.

Tip
Best of both worlds?

You can embed Asciidoc fragments inside a haml page.

.row-fluid
  .span6
    :asciidoc
      == Some header

      And now I'm back in plain Asciidoc with http://example.com[links] and all.
  -# Back in HAML, notice the indentation
  .span6

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.

An haml example
----
# 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)
An Asciidoc file
= 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.

Note

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 under search, 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).

4.3. Partials

Partials (in the _partials directory) are page fragments that can be reused from within a haml page or layout.

Caution
 Partials do not get automatically refreshed when change. You need to stop, clean and restart Awestruct rake clean preview.

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>/.

Caution
 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 to false.

    • 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 in site.yml, and values being objects with a version 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 is yyyy-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 to true. 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.

Note

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.