Managing your project web site

Every Apache project or podling has a website hosted at apache.org. Apache provides tools to maintain it. Each project decides how their website looks, its contents, how they maintain it, and what software they use to support it, as long as the result is static files that our public web servers can make available to browsers. We also have limited support for .htaccess files and CGI scripts.

Contents

• Creating the website
• Site management
• Previewing the website

Creating the website¶

Projects are free to choose their own styles and layout for websites, and have a range of options for actually creating the pages. The goal is to create and informative and useful static HTML website that can engage visitors, explain your project to them, and provide download links and documentation so they can use your project's applications.

Website-building options

If you're managing an ASF website repository in GitHub, please add website and <TOOL> Topics to it, where <TOOL> is the name of the tool used to generate the website, like pelican, hugo etc. This helps others use your repository as an example using queries like this one. You can use the .asf.yaml mechanism to add those Topics.

Website template in Markdown

If you'd like to get started with an easy-to-use, Markdown-based site that many projects have used, see the sample Apache project website repository which has many useful features and instructions for using svnpubsub.

Pelican

Pelican is a static site generator written in Python. Highlights include:

• Write your content directly with your editor of choice in reStructuredText or Markdown formats
• Includes a simple CLI tool to (re)generate your site
• Easy to interface with distributed version control systems and web hooks
• Completely static output is easy to host anywhere

Pelican has paths to migrate existing websites from many technologies, including Blogger, Dotclear, Posterous, Tumblr, WordPress, and RSS/Atom.

See a how-to on using Pelican and Buildbot to develop and deploy a project website.

Pelican supports both flat websites and those that have subdirectories. For the latter, Pelican provides a plugin.

Browse a collection of Pelican plugins to find others that support functionality you want to add to your site.

This GitHub query returns ASF repositories which have the pelican Topic, that should provide a few examples.

Github Pages

In theory, projects with a Git code repository can use GitHub Pages to create a staging site for reviewing their website, and to publish the site when it is ready. One project has done this as a proof-of-concept; however Infra does not have a structure in place to fully support using GitHub Pages for project websites.

Jekyll

Jekyll is a straightforward tool for developing blogs or static websites using Markdown, and it is easy to deploy the resulting website as Github Pages. There are many tutorials for doing this avaiilable online.

Hugo

At least six ASF projects use Hugo, an open-source framework for building static web sites.

JBake

At least two ASF projects use JBake, a Java-based tool for building static web sites.

Site management

The basic requirements for site management are that

• only committers should be able to modify the site.
• notifications of all site changes are sent to the relevant project mailing lists. The Apache CMS allows non-committers to send patches via a simple web interface by "Mail Diff"ing to the project mailing list that can be easily published by a committer.

Management tools¶

Infra supports these tools for publishing and maintaining Apache project websites:

• Pelican and BuildBot streamline creating and publishing your project website.
• svnpubsub automatically publishes the static contents of a designated svn folder (example) as the project web site at http://project.apache.org. The project team can use any site build mechanism it wants as long as the above requirements are met.
• pypubsub automatically serves the static contents of a designated git repository as the website for a project. Git-based websites are typically maintained in a repository branch to be published as https://project.apache.org. A project can host the site from its primary project repository. Typically these will be built as a Jenkins or a Buildbot job (see below). We recommend that you only have a single writer to the asf-site branch to avoid potential conflicts.
• For websites using a git repository, you can add a .asf.yaml configuration file. The file lets you set instructions that simplify updating and maintaining the site.
• Apache CMS (being deprecated; don't use for new sites) provides a simple browser-based user interface for editing, staging and publishing site content in Markdown, HTML or any other source format for which support has been added. See the CMS reference and adoption for more details. The Apache CMS uses pypubsub as the underlying mechanism for publishing a site. Note: No new projects can use the Apache CMS, and we enccourage projects using it to migrate to another resource for maintaining their websites. Here are migration instructions.

Build tools

Infra provides these build tools:

• Jenkins is an open source automation server that supports building, deploying and automating a project. Infra resources on Jenkins start here.
• Buildbot is a job scheduling system: it queues jobs, executes the jobs when the required resources are available, and reports the results.

Logging¶

The build output from your job when you compile your site is available from either Buildbot or Jenkins, depending on which you use.

Finding the site revision number¶

This only applies to SVN based websites.

Look at the .revision file at the root of your site (for example, http://subversion.apache.org/.revision). That file updates after every successful svn update. (If the update is underway or exited abnormally, .revision won't have changed.)

Providing public access to the project's mail archive mbox files¶

Some projects have a "mail" directory at the top of their project website. Enable this by creating a symbolic link to /home/apmail/public-arch/$tlp.apache.org in svnpubsub or CMS output.

See more notes aboout project mail.

Using the project's favicon¶

To use a custom favicon for your project's website, add the favicon.ico file to your site's root directory. The ASF feather appears for project sites that don't have a favicon.ico file.

Minimizing the number of changes committed in the project's Maven- or JavaDoc- generated site¶

If you are using svnpubsub, the commit performs very slowly if the number of changes is large, particularly if the number of files is large. This is often the case with JavaDoc, and to a lesser extent with Maven-generated sites.

Here is what you can do to speed up the commit:

• Ask Infra to store your generated content in the CMS repository, rather than the main ASF repository. While this won't necessarily speed up your own commit, it will prevent it from impacting other users.
• When running JavaDoc, pass the -notimestamp option. This will avoid most files from being modified between runs if there haven't been code changes.
• Use a Maven skin that doesn't generate a timestamp into the output. This may require customizing the current skins.
• If you use the Maven dependencies report in the Project Info Reports plugin, use version 2.7+ of the plugin to avoid random strings being generated.
• If you maintain historical versions of documentation, always check-in to a single "trunk", then use an svn copy operation to tag or branch the content, rather than checking in a complete copy.
• Minimize use of "publish date" and "version" in templates to those that are truly necessary or helpful. Consider using a "last modified date" and version in the URL instead (unless "latest" is implied).
• Minimize Subversion keywords in the output that may change frequently without significant meaning. This includes keywords in source code that may be rendered to JavaDoc or a Maven JXR source cross-reference.
• Avoid publishing Maven reports that change constantly to the project site. Code coverage, style reports, static analysis, etc. can be generated into a working copy on the CI server instead for easy developer viewing.

Previewing the website¶

• For svnpubsub sites, review the local files in your svn checkout before committing them. The changes will be published immediately after you commit them.
• For CMS sites, just commit the changes (without "publish"-ing them). Then click the Staged link that will take you to the staged site.
• There is no preview mode for pypubsub. You should ideally have a way to build and test the website locally.