Title: 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.
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.
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.
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 is a static site generator written in Python. Highlights include:
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.
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 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.
At least six ASF projects use Hugo, an open-source framework for building static web sites.
At least two ASF projects use JBake, a Java-based tool for building static web sites.
The basic requirements for site management are that
Infra supports these tools for publishing and maintaining Apache project websites:
http://project.apache.org
. The project team can use any site build mechanism it wants as long as the above requirements are met.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.Infra provides these build tools:
The build output from your job when you compile your site is available from either Buildbot or Jenkins, depending on which you use.
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.)
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.
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.
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:
-notimestamp
option. This will avoid most files from being modified between runs if there haven't been code changes.svn copy
operation to tag or branch the content, rather than checking in a complete copy.Staged
link that will take you to the staged site.