Every Apache project or podling has a website hosted at apache.org. Apache provides tools to support 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.
Your project team wants to build an excellent application that solves a problem, simplifies a process, or breaks new ground. You also want people to find it, try it, and adopt it. Your project website is key to attracting and engaging both contributors to project development and people and organizations that will become part of your user community.
Your website must
The site also should
Once you have outlined the content that will be on the website, and decided how and where to display it, you need to decide how to build the site.
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.
Many TLP sites use JavaScript to provide functions ranging from menu navigation to animations or image galleries. While JS can enhance the site experience for most visitors, it can pose problems:
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.
Any ASF project can use the ASF-Pelican template as the basis for their project website.
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.
ThisGitHub query returns ASF repositories
which have the pelican Topic. You can review them as examples of Pelican in action.
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 available 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.
MKDocs is a static site generator designed for creating project documentation. However, at least one ASF project uses it to build their entire project website. See this note on the build sequence to use to preserve your project site's .asf.yaml file.
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.
You can use any other tool that generates static HTML pages, or hand-code those pages. You then check them into your project's website repository. The check-in will trigger a site update.
Infra does not have a structure in place to support using GitHub Pages for project websites.
The Apache CMS, which projects used to build and deploy their websites since 2010, is no longer available as of July 31, 2021. All projects that used it, including the main Apache website, have moved or must move to other technologies. Those that linger will find at some point that they cna no longer update their website. See the notes in the section on site management tools, below.
If you don't have a web site repository for your project yet, you can create one using https://selfserve.apache.org/.
The convention is to name the repository $project-site.git, for instance httpd-site.git.
Copy whatever you need to start a build into the master branch of the new repository. This will act as the base of the build process.
Configure Pelican or Jekyll to build the site automatically when its contents change, using .asf.yaml and Buildbot. See the .asf.yaml documentation.
Using .asf.yaml with a Git repository, once you have your generated web site committed and pushed to a branch, you can set up a staging web site to test your changes before publishing them to your main web site.
To do so, add or edit .asf.yaml in the staging branch (where the build output is generated) and add the following (assuming your staging branch is asf-staging):
staging:
profile: ~
whoami: asf-staging
Upon commits to this branch, your staging web site will appear with the latest output at: https://$project.staged.apache.org/
For more details on staging via .asf.yaml, see the .asf.yaml documentation on staging web sites.
When you are ready to publish a branch of your Git web site repository to your project web site, you can use .asf.yaml:
publish:
whoami: asf-site
For more detailed procedures, follow the .asf.yaml documentation for publishing your web site.
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.)
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 you are using to generate the website, like pelican or hugo. This helps others who are looking for an example of use of that tool to find your repository with queries like
this one.
You can use the .asf.yaml mechanism to add those Topics.
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.
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 also large. This is often the case with JavaDoc, and to a lesser extent with Maven-generated sites.
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.
Copyright 2023, The Apache Software Foundation, Licensed under the Apache License, Version 2.0.
Apache® and the Apache feather logo are trademarks of The Apache Software Foundation...