== Cool Hello World
Here comes some extremely cool content.
Apache Training (incubating)
Training material for Apache projects
Generating the Website
We are currently using the normal Maven build to not only generate the project artifacts, but also the project’s website.
In order to provide content, every module can have a src/site directory. This content will be generated to those modules site-part.
The skin being used to generate the site is none of the default Maven skins, but a more up-to-date looking skin using:
-
Bootstrap (For the CSS)
-
JQuery (For the JavaScript magic)
-
Fontawesome (For icons and symbols)
But we don’t have to worry about the details, all is configured to be used automatically.
The site content itself is generated from asciidoc files (ending .adoc) which is a simple yet powerful markup language. (See AsciiDoc Syntax Quick Reference or AsciiDoc cheatsheet for details)
Beyond the basic goodies, the build is also configured to generate images from ASCII data using the asciidoctor-diagram plugin.
This allows us to generate images like the ones on the S7 Protocol Description page
Providing new content
The website content can be found on GitHub, in the /site subdirectory, at github.com/apache/incubator-training. Within the src/site directory, there is a file site.xml which generally controls the menu and the look of the site.
Most settings are inherited from the training parent module. That’s also why this is more complicated than the others.
The site.xml file is optional. Even if this is not available a site will be generated however no additional content will be linked from any of the navigation menus.
So if we wanted to add a new page on some (hopefully non-existent) Cool content, we would create a file called:
index.adoc in the src/site/asciidoc/content/cool directory.
For example with this content:
Adding links to menus
In order to add links to the menus, you have to create or modify the site.xml for the module you want to add content to.
The simplest form would probably be something like this:
<?xml version="1.0" encoding="ISO-8859-1"?>
<!--
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
https://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.
-->
<project name="Training">
<body>
<menu name="content">
<item name="cool" href="https://training.apache.org/content/cool.html"/>
</menu>
</body>
</project>This will generate a content menu at the end, and this has one link named cool.
Notice that the link has to have a file ending of .html and not .adoc.
If you want to insert the menu somewhere else, you will have to re-define the entire menu.
<?xml version="1.0" encoding="ISO-8859-1"?>
<!--
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
https://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.
-->
<project name="Training">
<body>
<menu ref="reports" inherit="top"/>
<menu ref="parent" inherit="top"/>
<menu name="content">
<item name="cool" href="https://training.apache.org/content/cool.html"/>
</menu>
<menu ref="modules" inherit="top"/>
</body>
</project>The menu ref items hereby reference standard menus provided by the Maven build.
Deploying the Website
The Apache Training project uses Apache gitpubsub system for maintaining the website.
In general, all content in a repos asf-site branch is copied to the web servers, if that repo is registered for it.
The content in this branch is generated and maintained during the Maven build as part of the site generation if the site-deploy phase is executed.
The build system needs to check-in content to the asf-site branch and usually the ASF Jenkins nodes don’t have the permissions to do that.
In order to be able to push to the asf-site GIT branch, a dedicated build job is configured to build on nodes with the Jenkins label git-websites.
Only on these machines are jobs allowed to push changes to a Git repo and here only to a branch named asf-site.
See https://builds.apache.org/view/S-Z/view/Training%20(incubating)/job/Training%20Multi-Branch%20Pipeline/ for details on the Training Jenkins Website build job.
As soon as the content is updated in the asf-site the gitpubsub mechanism will make those changes available at https://training.apache.org