ASF-Pelican getting-started guide

In 2019 Infra created ASF-Pelican as a structure and template for projects to use to build their websites, and for the ASF's own website.

In 2024, Infra moved from ASF-Pelican to the ASF Infrastructure Pelican Action GitHub Action to perform the same functions without being closely tied to BuildBot. The repository for this GHA is github.com/apache/infrastructure-actions/tree/main/pelican.

The material below relates to the 2019 ASF-Pelican and is not relevant to the Pelican GitHub Action.

---

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:

1. Using self-serve, create a new repo for the code and resources for your project’s website.
2. Clone the empty repo to a location on your computer.
3. Download the template zipfile.
4. Unzip master.zip and copy infrastructure-website-master/* to the root of your new repository.
5. Configure .asf.yaml.

pelican:
  notify: EMAIL of a person on your team to receive error messages related to Pelican
  autobuild: preview/*
  target: YOUR SITE'S GENERATED CONTENT BRANCH
  theme: theme/apache
  whoami: main

staging:
  profile: ~
  whoami: YOUR SITE'S GENERATED CONTENT BRANCH
  autostage: preview/*

6. Configure pelicanconf.yaml.
7. Commit and push your new website repository. This should trigger the automatic build to staging (REPONAME.staged.apache.org).
8. Review the site to confirm that the template materials display and function correctly.
9. 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.
   • .md files support GitHub Flavored Markdown (gfm) and html.
   • .ezmd files are for templates using ASF_DATA. .ezmd is a markdown extension of EZT. It lets you embed ezt inside markdown with modifications to simplify the process of fetching generated/external data.
10. If you want to work on and test the site offline, see Local builds of your Pelican-template website.
11. Adjust the theme by editing base.html and 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 content/images folder.
12. 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.
13. Visit YourProject.apache.org after 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.

Frameworks

The example has the following frameworks.

 - JavaScript:
   - [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)
 - CSS:
   - [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.

Data model

Determine whether your site requires a data model.

The .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:

• asfdata.yaml
• data/eccn directory

Issues and template questions

Please let us know if you run into issues with the template.

Earlier versions

Earlier versions of this template made use of a pelicanconf.py configuration file. The current version uses .asf.yaml and 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
   - `PLUGINS`
   - `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