Pelican Builds

This website is built using Pelican.

Process

Pelican Step	Substep	GFM Content	EZMD Content	Description
Initialization	ASF Data			Read data sources
Reader	Class	GFMReader	ASFReader(GFMReader)	Pelican Reader class
	Read	read_source	super.read_source	read page source and metadata
	Data		add_data	add asf data to the model and expand any `[{ reference }]`
	Generate		ezt	ezt template transformation
	Render	render	super.render	render GFM/HTML into HTML
Content	ASF Specific	generate_id	generate_id	Perform ASF specific HTML enhancements

Content

Content is GitHub Flavored Markdown (GFM) with ASF specific enhancements for Apache CMS style annotations.

These file extensions .md, .markdown, .mkd, and .mdown are processed as GFM. .md is preferred.

The ASF specific enhancements are controlled in pelican settings in the ASF_GENID dictionary.

step	ASF_GENID key	default	process	page override
1	-	True	fixup html that GFM marks as unsafe
2	-	True	convert html into beautiful soup
3	metadata	True	`{{ metadata }}` inclusion of data in the html
4	-	True	inventory of all id attributes, duplicates are invalid
5	elements	True	find all `{#id}` and `{.class}` text and assign attributes
6	headings	True	assign ids to all headings w/o ids already present or assigned with `{#id}` text	asf_headings
	headings_re	`r'^h[1-6]'`	regex for finding headings that require ids
7	tables	True	tables with a class attribute are assgned `class=table`
8	toc	True	generate a table of contents if [TOC] is found
	toc_headers	`r'h[1-6]'`	headings to include in the [TOC]

Data

Data is placed into GFM content with a combination of EZT and ASF python style directives.

The file extension .ezmd is processed with ASF python style directives and as an EZT template. Once that is done then the result is processed as GFM.

Data Model

The data model file specifies three types of data:

Constants. These metadata are made available to ezmd, asfgenid, and pelican templates.

- [{ code_lines }]+ lines of code in&nbsp;stewardship

Sequences. These metadata are used by EZT directives and also the ASF python style directives.
EZT

| Office    | Individual  |
|-----------|-------------|[for projects]
| V.P., [if-any projects.site][[][end]Apache [projects.display_name][if-any projects.site]]([projects.site])[end] | [projects.chair] |[end]

[for featured_projs]<li [if-index featured_projs first]class="active"[end]>
     <a href="#[featured_projs.key_id]" data-toggle="tab">[featured_projs.display_name]</a>
</li>[end]

ASF python style directive

|  |  |  |
|-----------|-----------|-------------|
| [{ board[0].name }] | [{ board[1].name }] | [{ board[2].name }] |
| [{ board[3].name }] | [{ board[4].name }] | [{ board[5].name }] |
| [{ board[6].name }] | [{ board[7].name }] | [{ board[8].name }] |

Dictionaries. These metadata are used by ASF python style directives.
ASF python style directive - we know the names and forcing a sequence is indirect.

| Office    | Individual  |
|-----------|-------------|
| Board Chair |  [{ ci[boardchair][roster] }] |
| Vice Chair |  [{ ci[vicechair][roster] }] |
| President |  [{ ci[president][roster] }] |
| Exec. V.P |  [{ ci[execvp][roster] }] |
| [[]Treasurer](https://treasurer.apache.org/) |  [{ ci[treasurer][roster] }] |
| Assistant Treasurer |  [{ ci[assistanttreasurer][roster] }] |
| Secretary |  [{ ci[secretary][roster] }] |
| Assistant Secretary |  [{ ci[assistantsecretary][roster] }] |
| V.P., [[]Legal Affairs](/legal/) |  [{ ci[legal][chair] }] |
| Assistant V.P., [[]Legal Affairs](/legal/) |  [{ ci[assistantvplegalaffairs][roster] }] |

Include and Insert

Templates

Pelican uses HTML templates. Templates have pelican metadata and pelican settings.

Theme

See your pelicanconf.py and templates for details.

# Theme
THEME = './theme/apache'

Plugins

# Pelican Plugins
# pelican-gfm is installed in the buildbot as part of build_pelican.py. It is an ASF Infra custom plugin.
# other plugins are discoverable and can be installed via pip by mentioning them in requirements.txt
# You can find plugins here: https://github.com/pelican-plugins
# Plugins that are custom for this site are found in PLUGIN_PATHS.
PLUGIN_PATHS = ['./theme/plugins']
PLUGINS = ['asfgenid', 'asfdata', 'pelican-gfm', 'asfreader']

Content Configuration

Static content is copied and these assets are mixed in with the rest of the content.

PATH = 'content'
# Save pages using full directory preservation
PAGE_PATHS = ['.']
# Path with no extension
PATH_METADATA = '(?P<path_no_ext>.*)\..*'
# We are not slugifying any pages
ARTICLE_URL = ARTICLE_SAVE_AS = PAGE_URL = PAGE_SAVE_AS = '{path_no_ext}.html'
# We want to serve our static files mixed with content.
STATIC_PATHS = ['.']
# we want any html to be served as is
READERS = {'html': None}
# ignore README.md files in the content tree and the interviews and include folders.
IGNORE_FILES = ['README.md','interviews','include']

Data Model How the global data model works and how to enhance the data availble for your content.
EZT How EZ Templates are used convert global data into content.
Markdown How your content is converted to HTML.
Processing How the process works to create the HTML.
Preview Branching How to work on complex changes like updated templates, new data sources, and alternative content.
Local Builds How to setup your local environment to work on a branch.
Error Analysis How to track down errors in your build.