Archiva Site Publishing

Table of Contents

General information about the site publish process
Where is site content generated?
Tasks for publishing
- Using the script (Linux/Bash)
- Run the process manually
Information about Maven / Script configuration
Information about site generation

General information about the site publish process

The archiva site is built from multiple different more or less independent modules. The build process uses maven-site-plugin for generating the static HTML pages and stylesheets and scm-publish-plugin for publishing the results to the repository.

The generated HTML pages are stored at a git repository: archiva-web-content.git.

The git repository contains a .asf.yaml file that defines the branch asf-staging as staging branch. The master branch is used by git-pub-sub to publish the official archiva site at https://archiva.apache.org .

If you push something to the asf-staging branch you can see the changes immediately at https://archiva.staged.apache.org

The maven site report and publishing plugins are configured to deploy the the asf-staging branch. That means the overall publishing process is the following:

Generate the site content for a module by using the scripts / maven
Use the maven publish plugin to push the generated pages to the asf-staging branch of archiva-web-content.git
Check the generated content at https://archiva.staged.apache.org/
If the result is fine, release the new content by merging the content from asf-staging to the master branch

For all modules there exists a script that runs all the steps (apart from the check on the staged site). Currently the script runs only on Linux / Bash. For details see below.

Where is site content generated?

The Archiva site is generated from the following components:

Component	Content	Git Repository	Path inside Repo	Publish Path	Skript
Archiva Site	Main Pages, like index.html. General information.	`archiva-site.git`	/	/	`deploySite.sh`
Archiva Documentation	Archiva User Documentation. Archiva Configuration.	`archiva.git`	/archiva-docs	/docs/${project.version}	`archiva-docs/deploySite.sh`
Archiva Reference Documentation	Developer documentation for Archiva, API Javadoc pages. Information for each maven module.	`archiva.git`	/archiva-modules	/ref/${project.version}	`archiva-modules/deploySite.sh`
Redback Site	Pages for Redback. General information about redback.	`archiva-redback-site.git`	/	/redback	`deploySite.sh`
Redback Reference Documentation	Developer documentation for Redback, API Javadoc pages. Information for each maven module.	`archiva-redback-core.git`	/	/core/${project.version}	`deploySite.sh`
Archiva Component Documentation	Information about the Archiva Components	`archiva-components.git`	/	/components	`deploySite.sh`

Tasks for publishing

Using the script (Linux/Bash)

The easiest way is always to use the script deploySite.sh in the directory of the corresponding repository.

cd <path inside repo for component>
./deploySite.sh
...
...
*****************************************
>>>> Finished the site stage process <<<<
> You can check the content in the folder target/staging or by opening the following url
> file:///archiva/archiva-modules/target/staging/ref/3.0.0-SNAPSHOT/index.html
>
> If everything is fine enter yes. After that the publish process will be started.
Do you want to publish (yes/no)? yes

When this output is shown you can check the staging output for this component only on the given path.

If you enter y or yes here, the content will be pushed to the asf-staging-branch at archiva-web-content.git If you enter any other key, the process will be aborted.

After the page was pushed to the asf-staging-branch, you can check the result at https://archiva.staged.apache.org/

If you would like to check the page with a local clone of archiva-web-content.git you can run the script with:

./deploySite.sh -DsiteRepositoryUrl=scm:git:file:///${path-to-your-local-archiva}/archiva-web-content.git

If the result on the staged URL is fine you have to merge the branch to the master branch:

# git clone https://gitbox.apache.org/repos/asf/archiva-web-content.git
cd archiva-web-content
git checkout master
git merge --ff-only asf-staging
git push

Run the process manually

Generating Site Pages for a component

The script basically runs

mvn clean site
mvn site:stage

The pom.xml has a plugin definition to checkout the repository as sparse checkout to a local directory .site-content The patterns for the sparse checkout are stored in the file git-sparse-checkout-pattern

The content of the module and all submodules is put to the directory target/staging/${Component Path}

Publishing to the staging branch

This is the part that is run, when you answer y or yes for publishing.

mvn scm-publish:publish-scm

This checks the differences in .site-content and pushes the differences to the asf-staging branch.

Information about Maven / Script configuration

There are some properties in the pom.xml that are used by the deploySite.sh. You should always make sure, that these properties are set to the corresponding values for the given module:

<scmPubCheckoutDirectory>.site-content</scmPubCheckoutDirectory>: The directory for the sparse checkout
<scmPublishBranch>asf-staging</scmPublishBranch>: The staging branch
<scmPublishPath>/</scmPublishPath>: The path relative to the base URL where the content is placed

The helper script checkoutSite.sh is used for running the sparse checkout of the content.

For multi-module projects the CSS (site.css) is always relative to the module directory. Therefore, we have a link to the stylesheet at /css/site.css in site.xml

Information about site generation

Most content is written in apt and xdoc. New documentation can/should be written in asciidoc. Asciidoc needs some css modification to get the styles right. So please check the generated content before publishing it.

For multi-module builds you should add the central /css/site.css to the <head>-Section in site.xml. Because submodules include only their own site.css and not the parent stylesheets. This can be done with:

<head>
        ...
        <![CDATA[    <link rel="stylesheet" href="/css/site.css" type="text/css" >]]>
        ...
</head>