| <!doctype html> |
| <html class="no-js" lang="en" dir="ltr"> |
| <head> |
| <meta charset="utf-8"> |
| <meta http-equiv="x-ua-compatible" content="ie=edge"> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0"> |
| <title>ASF-Pelican getting-started guide - Apache Infrastructure Website</title> |
| <link href="/css/bootstrap.min.css" rel="stylesheet"> |
| <link href="/css/fontawesome.all.min.css" rel="stylesheet"> |
| <link href="/css/headerlink.css" rel="stylesheet"> |
| <script src="/highlight/highlight.min.js"></script> </head> |
| <body class="d-flex flex-column h-100"> |
| <main class="flex-shrink-0"> |
| <div> |
| |
| <!-- nav bar --> |
| <nav class="navbar navbar-expand-lg navbar-dark bg-dark" aria-label="Fifth navbar example"> |
| <div class="container-fluid"> |
| <a class="navbar-brand" href="/"><img src="/images/feather.png" style="height: 32px;"/> Apache Infrastructure</a> |
| <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbarADP" aria-controls="navbarADP" aria-expanded="false" aria-label="Toggle navigation"> |
| <span class="navbar-toggler-icon"></span> |
| </button> |
| |
| <div class="collapse navbar-collapse" id="navbarADP"> |
| <ul class="navbar-nav me-auto mb-2 mb-lg-0"> |
| <li class="nav-item dropdown"> |
| <a class="nav-link dropdown-toggle" href="#" data-bs-toggle="dropdown" aria-expanded="false">About</a> |
| <ul class="dropdown-menu"> |
| <li><a class="dropdown-item" href="/team.html">About the team</a></li> |
| <li><a class="dropdown-item" href="/roundtable.html">The Infrastructure Roundtable</a></li> |
| <li><a class="dropdown-item" href="/blog/">The Infrastructure Blog</a></li> |
| </ul> |
| </li> |
| <li class="nav-item"> |
| <a class="nav-link" href="/policies.html">Policies</a> |
| </li> |
| <li class="nav-item dropdown"> |
| <a class="nav-link dropdown-toggle" href="#" data-bs-toggle="dropdown" aria-expanded="false">Services and Tools</a> |
| <ul class="dropdown-menu"> |
| <li><a class="dropdown-item" href="/services.html">Services and Tools</a></li> |
| <li><a class="dropdown-item" href="/machines.html">Machines and Fingerprints</a></li> |
| <li><a class="dropdown-item" href="https://blocky.apache.org/">Blocky</a></li> |
| <li><a class="dropdown-item" href="https://app.datadoghq.com/account/login?next=%2Finfrastructure">DataDog</a></li> |
| <li><a class="dropdown-item" href="https://whimsy.apache.org/roster/committer/" target="_blank">Committer Search</a></li> |
| </ul> |
| </li> |
| <li class="nav-item dropdown"> |
| <a class="nav-link dropdown-toggle" href="#" data-bs-toggle="dropdown" aria-expanded="false">Documentation</a> |
| <ul class="dropdown-menu"> |
| <li><a class="dropdown-item" href="/doc.html">Contribute</a></li> |
| <li><a class="dropdown-item" href="/infra-volunteer.html">Volunteer with Infra</a></li> |
| <li><a class="dropdown-item" href="/how-to-mirror.html">Become an ASF download mirror</a></li> |
| <li><a class="dropdown-item" href="/hosting-external-agent.html">Host a Jenkins or Buildbot agent</a></li> |
| |
| </ul> |
| </li> |
| <li class="nav-item"> |
| <a class="nav-link" href="/stats.html">Status</a> |
| </li> |
| <li class="nav-item"> |
| <a class="nav-link" href="/contact.html">Contact Us</a> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </nav> |
| |
| |
| <!-- page contents --> |
| <div id="contents"> |
| <div class="bg-white p-5 rounded"> |
| <div class="col-sm-8 mx-auto"> |
| <h1> |
| ASF-Pelican getting-started guide |
| </h1> |
| <p>Any ASF project using a Git repository for their website code and resources can use the <a href="asf-pelican.html">ASF-Pelican template</a> 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 <a href="https://infra.apache.org/project-site.html" target="_blank">guidelines for project websites</a>.</p> |
| <p>Review the <a href="https://template.staged.apache.org/">Apache Template example</a> to see whether the template's features will support the functions you need for your project.</p> |
| <h2>How to use this template</h2> |
| <p>First, review the <a href="https://github.com/apache/template-site" target="_blank">code repository for ASF-Pelican</a> 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.</p> |
| <p>If you wish to try out the template:</p> |
| <ol> |
| <li>Using <a href="https://selfserve.apache.org/" target="_blank">self-serve</a>, create a new repo for the code and resources for your project’s website.</li> |
| <li>Clone the empty repo to a location on your computer.</li> |
| <li>Download the <a href="https://github.com/apache/infrastructure-website/archive/refs/heads/master.zip">template zipfile</a>.</li> |
| <li>Unzip <code>master.zip</code> and copy <code>infrastructure-website-master/*</code> to the root of your new repository.</li> |
| <li>Configure <a href="asf-yaml.html">.asf.yaml</a>.</li> |
| </ol> |
| <div class="highlight"><pre><span></span><code><span class="n">pelican</span><span class="o">:</span> |
| <span class="w"> </span><span class="n">notify</span><span class="o">:</span><span class="w"> </span><span class="n">EMAIL</span><span class="w"> </span><span class="n">of</span><span class="w"> </span><span class="n">a</span><span class="w"> </span><span class="n">person</span><span class="w"> </span><span class="n">on</span><span class="w"> </span><span class="n">your</span><span class="w"> </span><span class="n">team</span><span class="w"> </span><span class="n">to</span><span class="w"> </span><span class="n">receive</span><span class="w"> </span><span class="n">error</span><span class="w"> </span><span class="n">messages</span><span class="w"> </span><span class="n">related</span><span class="w"> </span><span class="n">to</span><span class="w"> </span><span class="n">Pelican</span> |
| <span class="w"> </span><span class="n">autobuild</span><span class="o">:</span><span class="w"> </span><span class="n">preview</span><span class="o">/*</span> |
| <span class="w"> </span><span class="n">target</span><span class="o">:</span><span class="w"> </span><span class="n">YOUR</span><span class="w"> </span><span class="n">SITE</span><span class="s1">'S GENERATED CONTENT BRANCH</span> |
| <span class="s1"> theme: theme/apache</span> |
| <span class="s1"> whoami: main</span> |
| |
| <span class="s1">staging:</span> |
| <span class="s1"> profile: ~</span> |
| <span class="s1"> whoami: YOUR SITE'</span><span class="n">S</span><span class="w"> </span><span class="n">GENERATED</span><span class="w"> </span><span class="n">CONTENT</span><span class="w"> </span><span class="n">BRANCH</span> |
| <span class="w"> </span><span class="n">autostage</span><span class="o">:</span><span class="w"> </span><span class="n">preview</span><span class="o">/*</span> |
| </code></pre></div> |
| |
| <ol> |
| <li>Configure <a href="https://infra.apache.org/asf-pelican-config.html" target="_blank">pelicanconf.yaml</a>.</li> |
| <li>Commit and push your new website repository. This should trigger the automatic build to staging (<code>REPONAME.staged.apache.org</code>).</li> |
| <li>Review the site to confirm that the template materials display and function correctly.</li> |
| <li>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.<ul> |
| <li><code>.md</code> files support GitHub Flavored Markdown (<a href="gfm.html"><strong>gfm</strong></a>) and html.</li> |
| <li><code>.ezmd</code> files are for templates using <code>ASF_DATA</code>. .ezmd is a markdown extension of <a href="https://github.com/gstein/ezt/blob/wiki/Syntax.md" target="_blank">EZT</a>. It lets you embed ezt inside markdown with modifications to simplify the process of fetching generated/external data.</li> |
| </ul> |
| </li> |
| <li>If you want to work on and test the site offline, see <a href="https://infra.apache.org/asf-pelican-local.html" target="_blank">Local builds of your Pelican-template website</a>.</li> |
| <li><a href="https://infra.apache.org/asf-pelican-theme.html" target="_blank">Adjust the theme</a> by editing <code>base.html</code> 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 <code>content/images</code> folder.</li> |
| <li>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.</li> |
| <li>Visit <code>YourProject.apache.org</code> after every update to make sure it displays and functions correctly.</li> |
| </ol> |
| <p><strong>Note</strong>: we strongly suggest that you do your site development in a <a href="apache-pelican-branches.html">branch</a> 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. </p> |
| <h3>Frameworks</h3> |
| <p>The example has the following frameworks.</p> |
| <div class="highlight"><pre><span></span><code> - 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) |
| </code></pre></div> |
| |
| <p>For fenced code highlighting, consider <a href="https://highlightjs.org" target="_blank">highlightjs</a>.</p> |
| <h3>Data model</h3> |
| <p>Determine whether your site requires a <a href="asf-pelican-data.html">data model</a>.</p> |
| <p>The <code>.ezmd</code> files in the template's <code>content</code> directory show examples, and <a href="https://github.com/apache/template-site/blob/main/asfdata.yaml" target="_blank">asfdata.yaml</a> has many examples.</p> |
| <p>Remove the following if you do not need a data model: |
| - <code>asfdata.yaml</code> |
| - <code>data/eccn</code> directory</p> |
| <h2>Issues and template questions</h2> |
| <p>Please let us know if you run into <a href="https://github.com/apache/template-site/issues">issues</a> with the template.</p> |
| <h2>Earlier versions</h2> |
| <p>Earlier versions of this template made use of a <code>pelicanconf.py</code> configuration file. The current version uses <code>.asf.yaml</code> and <code>pelicanconf.yaml</code>, 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.</p> |
| <div class="highlight"><pre><span></span><code><span class="w"> </span><span class="n">Edit</span><span class="w"> </span><span class="n">the</span><span class="w"> </span><span class="n n-Quoted">`pelicanconf.py`</span><span class="w"> </span><span class="n">configuration</span><span class="w"> </span><span class="k">file</span><span class="o">:</span> |
| |
| <span class="w"> </span><span class="o">-</span><span class="w"> </span><span class="n">Website</span><span class="w"> </span><span class="k">specific</span> |
| <span class="w"> </span><span class="o">-</span><span class="w"> </span><span class="n n-Quoted">`PLUGINS`</span> |
| <span class="w"> </span><span class="o">-</span><span class="w"> </span><span class="n n-Quoted">`ASF_DATA`</span><span class="w"> </span><span class="o">-</span><span class="w"> </span><span class="n n-Quoted">`asfdata.py`</span><span class="w"> </span><span class="k">plugin</span><span class="w"> </span><span class="k">set</span><span class="n">tings</span> |
| <span class="w"> </span><span class="o">-</span><span class="w"> </span><span class="n n-Quoted">`ASF_GENID`</span><span class="w"> </span><span class="o">-</span><span class="w"> </span><span class="n n-Quoted">`asfgenid.py`</span><span class="w"> </span><span class="k">plugin</span><span class="w"> </span><span class="k">set</span><span class="n">tings</span> |
| <span class="w"> </span><span class="n n-Quoted">`asfgenid.py`</span><span class="w"> </span><span class="n">performs</span><span class="w"> </span><span class="n">a</span><span class="w"> </span><span class="n">series</span><span class="w"> </span><span class="k">of</span><span class="w"> </span><span class="n">html</span><span class="w"> </span><span class="n">fixups</span><span class="w"> </span><span class="n">including</span><span class="w"> </span><span class="n">permalinks</span><span class="p">,</span><span class="w"> </span><span class="n">heading</span><span class="w"> </span><span class="n">ids</span><span class="p">,</span><span class="w"> </span><span class="k">and</span><span class="w"> </span><span class="k">table</span><span class="w"> </span><span class="k">of</span><span class="w"> </span><span class="n">contents</span> |
| </code></pre></div> |
| </div> |
| </div> |
| </div> |
| <!-- footer --> |
| <div class="row"> |
| <div class="large-12 medium-12 columns"> |
| <p style="font-style: italic; font-size: 0.8rem; text-align: center;"> |
| Copyright 2024, <a href="https://www.apache.org/">The Apache Software Foundation</a>, Licensed under the <a href="https://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.<br/> |
| Apache® and the Apache feather logo are trademarks of The Apache Software Foundation... |
| </p> |
| </div> |
| </div> |
| <script type="application/ecmascript" src="/js/bootstrap.bundle.min.js" integrity="sha384-OERcA2EqjJCMA+/3y+gxIOqMEjwtxJY7qPCqsdltbNJuaOe923+mo//f6V8Qbsw3"></script> </div> |
| </main> |
| <script>hljs.initHighlightingOnLoad();</script> |
| </body> |
| </html> |
