ASF-Pelican getting-started guide
Any ASF project using a Git repository for their website code and resources can use the ASF-Pelican template as the basis for their project website. Building a site in this way simplifies both development and integration into the ASF automated build system, while helping ensure that your site satisfies the ASF's guidelines for project websites.
Review the Apache Template example to see whether the template's features will support the functions you need for your project.
How to use this template
First, review the code repository for ASF-Pelican to confirm that it provides the features your project site needs. The template builds a copy of the full Apaches Software Foundation website, which has features your site does not need, and lacks features, such as a download page for product releases, that you will need to add.
If you wish to try out the template:
- Using self-serve, create a new repo for the code and resources for your project’s website.
- Clone the empty repo to a location on your computer.
- Download the template zipfile.
infrastructure-website-master/*to the root of your new repository.
- Configure .asf.yaml.
notify: EMAIL of a person on your team to receive error messages related to Pelican
target: YOUR SITE'S GENERATED CONTENT BRANCH
whoami: YOUR SITE'S GENERATED CONTENT BRANCH
- Configure pelicanconf.yaml.
- Commit and push your new website repository. This should trigger the automatic build to staging (
- Review the site to confirm that the template materials display and function correctly.
- Add your own content, updating, replacing, and removing template content elements as appropriate. With each commit / push of content, visit the staging site to confirm that the site displays as you expect it to.
- If you want to work on and test the site offline, see Local builds of your Pelican-template website.
- Adjust the theme by editing
base.htmland making any other style changes that will help the site present your project and product well. Don't forget to provide your product's logo in the
- When you are ready to publish the site, create a pull request to merge the content in staging into the trunk of the repo. That will trigger a build of the live site.
YourProject.apache.orgafter every update to make sure it displays and functions correctly.
Note: we strongly suggest that you do your site development in a branch rather than the trunk of the repository, and then merge the branch into the trunk when you are sure that everything is working as you would like it. Each commit to the trunk triggers an automatic build to update your live site; this is great for trivial changes like correcting typos, but more of a challenge if you are making major changes and it turns out that there is an error in your code that disables your live site.
The example has the following frameworks.
- [JQuery 3.6.0 Slim](https://code.jquery.com/jquery-3.6.0.slim.js)
- [Popper 1.14.7](https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.14.7/umd/popper.js)
- [Bootstrap 4.3.1](https://stackpath.bootstrapcdn.com/bootstrap/4.3.1/js/bootstrap.js)
- [Bootstrap 4.3.1](https://stackpath.bootstrapcdn.com/bootstrap/4.3.1/css/bootstrap.css)
- [GitHub Markdown 3.0.1](https://cdnjs.cloudflare.com/ajax/libs/github-markdown-css/3.0.1/github-markdown.css)
For fenced code highlighting, consider highlightjs.
Determine whether your site requires a data model.
.ezmd files in the template's
content directory show examples, and asfdata.yaml has many examples.
Remove the following if you do not need a data model:
Issues and template questions
Please let us know if you run into issues with the template.
Earlier versions of this template made use of a
pelicanconf.py configuration file. The current version uses
pelicanconf.yaml, as noted above. We retain the earlier instruction for the projects using the earlier version of the template; however, any project starting with the template now should use the files and instructions noted above.
Edit the `pelicanconf.py` configuration file:
- Website specific
- `ASF_DATA` - `asfdata.py` plugin settings
- `ASF_GENID` - `asfgenid.py` plugin settings
`asfgenid.py` performs a series of html fixups including permalinks, heading ids, and table of contents