////
     Licensed to the Apache Software Foundation (ASF) under one
     or more contributor license agreements.  See the NOTICE file
     distributed with this work for additional information
     regarding copyright ownership.  The ASF licenses this file
     to you under the Apache License, Version 2.0 (the
     "License"); you may not use this file except in compliance
     with the License.  You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

     Unless required by applicable law or agreed to in writing,
     software distributed under the License is distributed on an
     "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
     KIND, either express or implied.  See the License for the
     specific language governing permissions and limitations
     under the License.
////
= Apache NetBeans / netbeans.apache.org
:toc:

The http://netbeans.apache.org website.

== Introduction. Objectives.

The NetBeans project has a huge website at https://www.netbeans.org. The site
has grown over the years, and is indeed quite big. Now that
link:https://github.com/apache/netbeans[NetBeans] is being donated by
Oracle to the link:http://www.apache.org[Apache Software Foundation], a new static web site must be
created, trying to keep as much information as possible
from the "old" website.

This is ongoing effort and is being performed in these two steps:

1. Wade Chandler has made a great effort retrieving as much information as
   possible from the old website. This is actually kept in https://github.com/apache/netbeans-website-cleanup.
   He has also set up the a sophisticated, yet simple to use, gradle build system.
2. Once this content is approved by Oracle it will be gradually added here.
3. And once all content is donated, http://netbeans.apache.org will become http://netbeans.org

== About this repository

As stated above, the objective of this repository is to construct the website at http://netbeans.apache.org
that will gradually receive content from http://netbeans.org (as stored in https://github.com/apache/netbeans-website-cleanup).

The tasks to do are described in a specific [NetBeans Wiki Page](https://cwiki.apache.org/confluence/display/NETBEANS/New+NetBeans+Web+Site+Planning).

== Tooling

This repository is build built using the following technologies:

. Gradle
. http://jbake.org/[JBake] see also http://jbake.org/docs/2.5.1/[JBake documentation]
. SaSS
. Apache Groovy
. SnakeYaml
. Apache Tomcat
. ... and others.

NOTE: You *do not need* to install any of these. The tools will be automatically installed by gradle.

The project uses Gradle, Groovy, and JBake to create a template based statically compiled web site.
The technologies used compliment each other. JBake performs the final steps of preparing the site.
Gradle and Groovy are used to preprocess files and execute JBake. Gradle provides features which JBake
currently does not, and thus uses JBake as part of a larger build system which is completely configurable
and programmable. Other features can be added as needed.

Tomcat is used to provide a local web server to use while working with the site sources locally,
and is not intended to be used as the production server though Tomcat could certainly be used
to serve the sources. It is expected the sources will be served by Apache httpd at Apache.

To properly use the build and tools, one should become familiar with this README, but also the build
sources, and have an understanding of how they function. The goal is certainly for this README to suffice,
but it is entirely possible something has been missed. Please update this README accordingly when/if
something is missing.

== The Source and Build Layout and Important Concepts

The project source layout is roughly:

----
build.gradle
settings.gradle
globals.yml
buildSrc
-- src
---- main
------ groovy
---- test
------ groovy
-- build.gradle
-- gradle
---- wrapper
-- deps.gradle
-- utils.gradle
src
-- content
---- templates
gradlew
gradlew.bat
----

Much of the above is standard Gradle build stuff. The rest is explained below:

[options="header"]
|===
|Name|Description


|globals.yml|A YAML file which is used to replace/supplement the notion of jbake.properties plus allows customization
|buildSrc|A convention in Gradle which is a subproject with sources which will be built before tasks are configured and ran
|gradle|A folder for Gradle specifics such as include files and the wrapper
|gradle/wrapper|The gradle wrapper files which allow it to run with nothing but a JDK and JAVA_HOME
|gradle/deps.gradle|A gradle script which defines variables and common dependencies used by the build
|gradle/utils.gradle|A gradle script which defines and maps various utilities the build uses
|src/content|The main content files top level sources directory
|src/content/templates|A folder for JBakes templates; this build uses Groovy templates
|===

=== globals.yml

JBake configuration can go here, but in some cases, the configuration is better
defined in the `jbake` configuration inside `build.gradle` as it can be calculated
by the Gradle build.

Global data or configuration can then be defined here. This data can be in complex
form, such as a YAML tree/map hierarchy, or it may be flat attributes. This
data is used both for JBake configuration, those common to JBake, and thus
accessible by the JBake templates, and is also accessible in pure object form
by the "content templates" (more on these later)

=== buildSrc

Gradle will build `buildSrc` as a project before configuring and executing the
rest of the build. Classes in this project can be used to do some very specific
things in the build. They can provide utilities or they can setup and run
an Apache Tomcat server (which they do).

=== src/content/templates

The JBake templates go here. This project specifically uses Groovy templates. These
should not be confused with "content templates" which is a concept to be described
later. 

These templates are executed by JBake at specific times as described in the
JBake documentation, and usually based on the `type` attribute from content metadata.

An example is `type: page` in content metadata which maps to the JBake template
`src/content/templates/page.gsp` 

The same is true for `type: post`, as it has a `post.gsp` file. Posts are
useful for a "blog like" area of the site where
news items may be kept etc.

For more information about the templates, and how to build one, see the
link:src/content/templates[templates] directory README.

=== src/content (\*\*/\*.html.gsp and \*\*/\*.md.gsp and YAML) or Content Templates

This build treats files ending in `.html.gsp` and `.md.gsp` specially. These files
will be preprocessed before JBake accesses them, and turned into `.html` and `.md`
files respectively. It is a build error to have such a file without a counterpart
file ending in `.html.gsp.yml` or `.md.gsp.yml` respectively.

The YAML file will be merged into the final file as the JBake metadata. The common
JBake metadata attributes defined in the documentation will be added to the top
of the files such as `title=Some Title` if in the YAML file exists the value
`title: Some Title`. The same is true for `type` such that `type: page` becomes
`type=page`. The common attributes along with the entirety of the YAML file will
be rolled up into a JSON attribute (as defined in the JBake documentation), and
will be named `metadata`.

The `tags` attribute is treated specially in the YAML file processing. It can be
a comma separated string value, or, it may be a YAML list of strings. This allows
for better layout of the metadata.

Custom metadata, such as `summary: Some longer page summary` will not be added
as top level attributes in the generated and merged content metadata, but will
instead be available in the JSON object `metadata` in the content. This is
accessible in JBake templates as `content.metadata`. Thus, to access `summary`,
one would write `content.metadata.summary`, and the YAML would look like:

----
type: page
status: published
summary: Some longer page summary
----

and the metadata prepended to the content file will look like (properties/attributes and JSON):

----
type=page
status=published
metadata={"type":"page","status":"published","summary":"Some longer page summary"}
~~~~~~
----

JBake can not currently separate the metadata from the content, and this setup
allows the metadata and the content to reside in separate files, and each file
to remain more pure or clean for its purpose.

Thus, if a file
exists `some-html.html.gsp` and a YAML file exists `some-html.html.gsp.yml`, the
`.yml` file will be merged with the resulting `.html` file, and JBake will
understand the result, and will use it when it "bakes" the site. The file
`some-html.html.gsp` will also be renamed to `some-html.html` during
preprocessing.

It is expected that content templates in this build will not have metadata
added directly to them, or the result will be undefined or may cause
errors in JBake.

The difference between "content templates" and "static content"
as defined below is the JBake information from the `global.yml`
configuration file can be accessed, and used to iterate over
logic, or to reference specific folders or information quite
similarly as JBake templates. The files may also have any logic
added to them which may be placed into a Groovy Server Page or
Simple Groovy Template. Thus is supports `<% %>` and `${ }`
notation. This does mean that JavaScript inline in these files
must be escaped accordingly as it will collide with Groovy syntax
at times, and thus is a good reason to keep JavaScript separated
into files, and not be inlined.

=== src/content (\*\*/\*.html and \*\*/\*.md and YAML) or Static Content

This build treats static content files ending in `.html` and `.md` similar
to the "Content Templates" except it does not process the content files as
Apache Groovy templates. It does however merge the `.html` or `.md` files
with a similarly named file ending in `.html.yml` and `.md.yml` in the
exact same way as this data is added to the "Content Templates". See
above for how those are transformed and merged. 

Thus, if a file
exists `some-html.html` and a YAML file exists `some-html.html.yml`, the
`.yml` file will be merged with the `.html` file, and JBake will understand
the result, and will use it when it "bakes" the site.

It is expected that
content files in this build will not have metadata added directly to them,
or the result will be undefined or may cause errors in JBake.

=== src/content (\*\*/\*.asciidoc)

This build also handles http://asciidoc.org[asciidoc] content. This content
is transformed to `.html` using http://asciidoctor.org/docs/asciidoctorj/[AsciidoctorJ].

All asciidoc files must define some JBake specific metadata like so (see http://jbake.org/docs/2.5.1/#metadata_header for details):

----
= Document title here
Jonathan Bullock
2013-10-17
:jbake-type: page
:jbake-tags: documentation, manual
:jbake-status: published
----

asciidoc documents may also define asciidoc metadata, such as `:toc:` or others. This metadata will be available
to jbake templates inside the `content` map. So, for instance, if the asciidoc contains this metadata:

----
= Document title here
Jonathan Bullock
2013-10-17
:jbake-type: page
:jbake-tags: documentation, manual
:jbake-status: published
:foo: bar
----

then the value of `foo` (i.e., `bar`) will be accessible in the template GSP file as `${content.foo}`.

=== Build Layout

During build, certain structures are setup in the `build` directory
of the main project. This directory should **never** be added to the
git repository, and is included in `.gitignore` file. The build
directories folders are described below. See `build.gradle` for
the technical details as to what files go where. It is extremely
important for the site "bake" or generation.

----
build
--bake
--bake-cache
--generated-bake
----assets
----content
----templates
--tomcat

----

[options="header"]
|===
|Name|Description

|bake|This is the finished product after JBake is run with the bake task
|bake-cache|This is where JBake caches its files to speed up the build; it is cleaned with the clean task
|generated-bake|This directories directories are generated from preprocessing tasks along with content; JBake uses this
|generated-bake/assets|Assets which are copied directly to bake from JBake into this structure such as scss->css
|generated-bake/content|Content files with prepended metadata go here; only those files should go here
|generated-bake/templates|JBake templates are copied here by preprocess tasks
|tomcat|This is the home directory of the tomcat process when run
|===

Specifics on the above may be added here if it is deemed more necessary.

=== Things To Keep In Mind

The various preprocess tasks move files into different areas
of the "Build Layout" from the "Source Layout". Those tasks
are responsible for copying or processing various discrete
file types. If something placed into the `src/content` structure
is not showing up where or as expected, `build.gradle` is
the place to look. Some items could be affected by variables
defined in `deps.gradle`, `utils.gradle`, or sources under
`buildSrc` as well, so keep this in mind.

== How To Bake The Site

There are multiple preprocess tasks in the build which setup the JBake data and structures. These structures
and data are setup in a way JBake understands and is configured in the build.

Run the following gradle build to preprocess content plus run JBake, and bake the web site:

=== Linux and Mac

`./gradlew preprocessContent bake`

or, simply

`./gradlew build`

=== Windows

`gradlew preprocessContent bake`

== Using The Local Tomcat Web Server

Once the server is running, the site can be baked or built multiple times, and the site can be
continually viewed in the browser.

=== Run Tomcat

From a separate terminal, change to the project directory, and run:

`./gradlew run`

This aspect of the build needs to be modified to allow the Tomcat
server to fork, and continue to exist independent of the Gradle
build. At the moment it consumes the shell/command line. This also
hogs a Gradle daemon.

=== Stop Tomcat

To stop the local Tomcat server, from a seperate terminal run:

`./gradlew stop`

or in the same one as `run` press `CONTROL-C`; hopefully this will
change in the future.

== Gradle Tasks of Note

=== Build tasks

. clean - deletes the build directory
. compileContentSass - compiles the projects SaSS files to the build directory.
. preprocessContent - runs all preprocess tasks to prepare for a bake
. preprocessContentAssets - pre-processes all .css, .js (not in the minimize list), images, etc from the content directory into the generated assets directory
. preprocessContentStatics - pre-processes all .html, .md, and possibly other files which have metadata/front matter in a side car file of the same name and extension with an extra .yml extension after that
. preprocessContentTemplates - pre-processes the *.gsp and *.gsp.yml files under content for baking as Groovy templates; edit global.yml to add data used in content other than YAML front matter
. preprocessTemplates - pre-processes the templates for JBake to use for baking

=== Documentation tasks

1. bake - bakes a jbake project; the final generator

=== Run tasks

1. run - runs the Tomcat server
2. stop - stops the Tomcat server


== Important directories

link:src/content[content]:: Main content
    - Different entries in asciidoc format.

link:src/content/assets[src/content/assets]:: CSS, images and Javascript files
    - link:src/content/assets:/css/[foundation *] : A copy of link:https://foundation.zurb.com/sites/download.html/[Foundation 6 for Sites] by Zurb. MIT License (see link:LICENSE-foundation[LICENSE-foundation]).
    - link:src/content/assets:/css/font-awesome.min.css[font-awesome.min.css] The link:https://github.com/FortAwesome/Font-Awesome[Font Awesome CSS]. MIT License (see https://github.com/FortAwesome/Font-Awesome#license).
    - link:src/content/assets:/fonts/[assets/fonts] The link:https://github.com/FortAwesome/Font-Awesome[Font Awesome Fonts]. Released under the link:[http://scripts.sil.org/OFL] SIL OFL 1.1 license.
    - link:src/content/assets:/images/[assets/images] Different images, such as the Apache NetBeans Logo and some background images.
    - link:src/content/assets:/css/netbeans.scss[netbeans.scss] : A simple SCSS file with some Foundation 6 modifications. 

link:src/content/templates[src/content/templates]:: Templates
    - link:src/content/templates/page.gsp[src/content/templates/page.gsp] A prototype page that includes the asciidoc's table of contents in an aside. May also include a 'hero' area and others.
    - link:src/content/templates/menu.gsp[src/content/templates/menu.gsp] A prototype menu bar (Foundation's top bar)
    - link:src/content/templates/head.gsp[src/content/templates/head.gsp] A prototype `<head>` tag that incorporates some of asciidoc's metadata (`keywords`, `description`, title).
    - link:src/content/templates/footer.gsp[src/content/templates/footer.gsp] A prototype `<footer>` tag with some ASF's required links.

build/bake:: The generated website.
    - This is a generated directory.