Home ASF-Pelican getting-started guide (edit)

ASF-Pelican getting-started guide

Any ASF project can use the ASF-Pelican template as the basis for their project website.

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

Note: this information is evolving.

  1. Review the code repository for ASF-Pelican to confirm that it may provide the features your project site needs.

  2. Create a Jira ticket for Infra, requesting Infra to create a repository using this template for your project. Provide a name and short description for the repository. Infra will confirm the repository's location when it is ready for you.

  3. 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 as 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.

    Review ASF Pelican feature branches.

  4. In theme/apache/templates, update the theme's base.html to fit your site's requirements.

    The example has the following frameworks.

    For fenced code highlighting, have a look at highlightjs.

    • The content/images folder holds example logo files. Place your other site image files here.
  5. Determine if your site requires a data model.

    • The .ezmd files in the content directory show examples
    • asfdata.yaml has manuy examples
    • Remove the following if you do not need a data model:
      1. asfdata.py and asfreader.py Plugins
      2. asfdata.yaml
      3. data directory
  6. Edit your configuration

    • 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
  7. Create your content

    • .md files using Github Flavored Markdown (gfm
    • .ezmd files for templates using ASF_DATA
  8. Building

  9. When you are ready to use this repository as the source for your live site, create a Jira ticket to ask Infra to adjust the build process. From then on, changes you make to the trunk of this repository automatically update the live site.

Issues and template questions

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

Copyright 2021, 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...