# Silverpeas Project Web Site

Generator of the main Web site of the open-source Silverpeas project, published at
[www.silverpeas.org](https://www.silverpeas.org).

This repository doesn't contain any source code of Silverpeas itself: it holds the content
(documents, images, stylesheets, downloadable resources) and the Maven build required to generate
and to deploy the community Web site of the project.

## Table of contents

* [What this project is](#what-this-project-is)
* [Requirements](#requirements)
* [Building and previewing the site](#building-and-previewing-the-site)
* [Publishing the site](#publishing-the-site)
* [Project layout](#project-layout)
* [Site structure and navigation](#site-structure-and-navigation)
* [Version properties](#version-properties)
* [Writing content](#writing-content)
* [Continuous integration](#continuous-integration)
* [Relationship with the other Silverpeas sites](#relationship-with-the-other-silverpeas-sites)
* [Community](#community)
* [License](#license)

## What this project is

The site is generated by the [Maven Site Plugin](https://maven.apache.org/plugins/maven-site-plugin/)
from [Doxia](https://maven.apache.org/doxia/) sources:

* the pages are written in **XDoc** (`src/site/xdoc`) and in **FML** for the FAQ (`src/site/fml`);
* the pages requiring the version numbers of Silverpeas are **Velocity templates** (`*.xml.vm`)
  interpolated at generation time;
* the whole site is decorated by the
  [Fluido skin](https://maven.apache.org/skins/maven-fluido-skin/) as configured in
  `src/site/site.xml`;
* the home page is a handcrafted XHTML page (`src/site/resources/index.html`) that doesn't use the
  skin, so that it can have its own layout;
* the output is XHTML5, thanks to the `doxia-module-xhtml5` module declared in the POM.

The Maven coordinates are `org.silverpeas:silverpeas-website` with a `pom` packaging: nothing is
compiled, only documentation is produced. The parent POM is `org.silverpeas:silverpeas-project`,
shared by all the projects of the Silverpeas organization.

## Requirements

* **Java** and **Maven 3** (the exact minimal versions are the ones required by the
  `silverpeas-project` parent POM).
* Access to the [Silverpeas Nexus repository](https://nexus3.silverpeas.org/repository/silverpeas)
  in order to resolve the parent POM; it is declared both as a repository and as a plugin
  repository in `pom.xml`, so no additional `settings.xml` is needed for a simple build.
* For the publishing only: an SSH access to `www.silverpeas.org` (see
  [Publishing the site](#publishing-the-site)).

## Building and previewing the site

Generate the site in `target/site`:

```bash
mvn clean site
```

Then open `target/site/index.html` in a browser.

Beware that the links declared in `src/site/site.xml` are **absolute** (`relativizeDecorationLinks`
is set to `false`), because the generated site is merged on the server with the technical
documentation of the other Silverpeas projects. As a consequence, when browsing the site locally
from the file system, the navigation links point to the root of the file system and not to
`target/site`. To browse the site as it will be published, serve it over HTTP; for instance:

```bash
mvn clean site
python3 -m http.server 8080 --directory target/site
# then browse http://localhost:8080/index.html
```

## Publishing the site

The site is deployed by SCP to the Web server hosting `www.silverpeas.org`, as declared in the
`distributionManagement` section of the POM (`scp://www.silverpeas.org/var/www/`):

```bash
mvn clean site-deploy
```

This requires an SSH account on the server with a write access on `/var/www`. In practice, the
publishing is performed by the CI (see [Continuous integration](#continuous-integration)), and a
manual deployment should only be a fallback.

## Project layout

```
pom.xml                              Maven build: metadata, team, versions, site plugin
Jenkinsfile                          CI pipeline publishing the site
src/site/
├── site.xml                         Site descriptor: skin, banner, menus, footer
├── fml/
│   ├── faq.fml                      General FAQ
│   └── legal/                       Licensing FAQ
├── xdoc/
│   ├── intro.xml                    About Silverpeas
│   ├── screenshots.xml              Screenshots gallery
│   ├── releasenotes.xml             Release notes index
│   ├── support.xml                  Support offering
│   ├── product/                     Functional presentation of Silverpeas
│   │   ├── features.xml             Key features
│   │   ├── applications.xml         Overview of the applications
│   │   ├── social_network.xml       Social network
│   │   ├── documentation_management.xml
│   │   ├── content_management.xml
│   │   ├── data_collection.xml
│   │   ├── gallery.xml              Pictures management
│   │   ├── knowledge_management.xml
│   │   └── project_documentation.xml
│   ├── installation/                Installation guides (Velocity templates)
│   │   ├── index.xml.vm             Entry point of the installation guides
│   │   ├── installationV6.xml.vm    Installation of Silverpeas 6
│   │   ├── izpack.xml.vm            Installation with the IzPack installer
│   │   ├── cloud.xml.vm             Silverpeas in the Cloud (Docker)
│   │   └── webdav.xml.vm            Online edition of documents (WebDAV)
│   ├── configuration/               Configuration tips
│   │   ├── ldap.xml                 LDAP synchronization
│   │   └── proxy.xml                Reverse-proxy setup
│   ├── dev/                         For contributors
│   │   ├── collaboration.xml        How to contribute
│   │   ├── quality.xml              Code quality rules
│   │   └── ldap_testing.xml         Testing the LDAP code
│   └── legal/
│       ├── licensing_gnu_affero.xml AGPL licensing
│       ├── floss_exception.xml      Silverpeas FLOSS exception
│       └── trademark.xml            Silverpeas trade mark
└── resources/                       Copied as-is into the generated site
    ├── index.html                   Home page (standalone XHTML, filtered by Maven)
    ├── css/, js/, font/, images/    Assets of the site and of the home page
    ├── legal/                       License texts (AGPL, FLOSS exception)
    ├── releases/                    Release notes of the past versions, as PDF
    ├── xsd/                         XML schemas published for the integrators
    │   ├── component.xsd            Descriptor of a Silverpeas application
    │   ├── processModel.xsd         Workflow process model
    │   └── migration.xsd            Data migration descriptor
    └── opendj-silverpeas.ldif       Sample LDAP directory for testing
```

Some pages of the menu (`team.html`, `mailing-lists.html`, `issue-management.html`,
`source-repository.html`, `ci-management.html`, `scm.html`) aren't written by hand: they are
generated by the `maven-project-info-reports-plugin` from the metadata declared in the POM
(`developers`, `contributors`, `mailingLists`, `issueManagement`, `scm`, `ciManagement`).
Updating the team of the project is therefore done by editing `pom.xml`, not by editing a page.

## Site structure and navigation

The navigation menus, the banner, the *powered by* logos, the GitHub ribbon and the footer are all
declared in `src/site/site.xml`. Adding a page to the site means:

1. writing the document in `src/site/xdoc/...` (or `src/site/fml/...` for a FAQ);
2. declaring it in the relevant `<menu>` of `src/site/site.xml`, with a link that is **absolute**
   (`/product/my_page.html`) as the other ones;
3. regenerating the site to check both the rendering and the navigation.

A sitemap is generated automatically (`generateSitemap` is enabled in the site plugin
configuration).

## Version properties

The versions of Silverpeas and of its application server are centralized in the `properties`
section of `pom.xml`, and interpolated into the `*.xml.vm` pages:

| Property | Meaning |
| --- | --- |
| `installer_stable_version` | Version of the current stable release of Silverpeas |
| `installer_izpack_version` | Version of Silverpeas provided by the IzPack installer |
| `installer_build_version` | Version of the current build (unstable) release |
| `current_wildfly_release` / `current_wildfly_version` | Wildfly used by the stable version |
| `next_wildfly_release` / `next_wildfly_version` | Wildfly used by the build versions |

Updating the site for a new release of Silverpeas is therefore mostly a matter of updating these
properties and of committing the change: this is what the vast majority of the commits of this
repository do (`Update the build version of Silverpeas to ...`).

Note that `src/site/resources/index.html` is declared as a *filtered* resource in the build, so
Maven properties can be used in it too; today the home page mostly refers to the download links
explicitly.

## Writing content

* **XDoc** pages follow the [XDoc 2.0](https://maven.apache.org/doxia/references/xdoc-format.html)
  format: a `<document>` element with an optional `<properties>` (page title) and a `<body>` made
  of `<section>`/`<subsection>` elements.
* **FML** pages follow the [FML](https://maven.apache.org/doxia/references/fml-format.html) format:
  `<faqs>` grouping `<part>` and `<faq>` entries.
* **Velocity** templates (`*.xml.vm`) are plain XDoc pages in which `${property}` placeholders are
  substituted by the values of the Maven properties. Use them as soon as a page mentions a version
  number, instead of hard-coding it.
* Every source file carries the AGPL header with the Silverpeas FLOSS exception; keep it when
  creating a new file, as it is checked by the license plugin inherited from the parent POM.
* Images go into `src/site/resources/images` (with `screenshots/`, `applications/`,
  `configuration/`, `snapshots/` and `logos/` sub-directories), and are referenced from the pages
  with a path relative to the root of the site.

## Continuous integration

The `Jenkinsfile` at the root of the repository defines the pipeline running on the
[Silverpeas Jenkins](https://integration.silverpeas.org/jenkins) instance. It runs inside the
`silverpeas/silverbuild` Docker image, with the Maven local repository, the Git and SSH
configurations and the GnuPG keyring of the CI account mounted into the container, and it simply
executes:

```bash
mvn clean site-deploy
```

Only the `master` branch is published. On failure, an email is sent to the maintainers of the site;
the standard Jenkins mailer notifies them of any unstable build as well.

## Relationship with the other Silverpeas sites

`www.silverpeas.org` aggregates several generated sites, which explains the absolute links of the
site descriptor:

* this project provides the *community* site: presentation, installation guides, FAQ, legal pages;
* `/docs/core` and `/docs/components` are the technical documentations generated by the
  [Silverpeas Core](https://github.com/Silverpeas/Silverpeas-Core) and
  [Silverpeas Components](https://github.com/Silverpeas/Silverpeas-Components) projects;
* the issues, the roadmap and the changelog live in
  [the Redmine tracker](https://tracker.silverpeas.org).

## Community

* Web site: [www.silverpeas.org](https://www.silverpeas.org)
* Source code: [github.com/Silverpeas](https://github.com/Silverpeas)
* Issue tracker: [tracker.silverpeas.org](https://tracker.silverpeas.org)
* Users mailing list: [silverpeas-users](https://groups.google.com/group/silverpeas-users)
* Developers mailing list: [silverpeas-dev](https://groups.google.com/group/silverpeas-dev)

Contributions to the site are welcome; please have a look at the
[contribution page](https://www.silverpeas.org/dev/collaboration.html) before opening a pull
request.

## License

Copyright (C) 2000 - 2026 Silverpeas.

The sources of this project are released under the terms of the
[GNU Affero General Public License](https://www.silverpeas.org/legal/gnu_affero.html), version 3 or
later, with the [Silverpeas FLOSS exception](https://www.silverpeas.org/legal/floss_exception.html).
The content published on the Web site is licensed under the
[Creative Commons Attribution-ShareAlike 4.0](https://creativecommons.org/licenses/by-sa/4.0/)
license.