A Static Web Site
- How page templates are expanded.
- Using configuration data in a site.
- More about Jinja templates.
- Adding extensions to Ark to display scientific data.
- Figuring out how to build extensions for third-party software.
Terms defined: interpolation, shortcode, static site generator, template (for static site generator), theme (for static site generator)
- Sharing knowledge is the last and most important step of scientific research
- Journals may require a PDF, but a website will get more readers
- Use a static site generator to create one
- We will use Ark (the same tool used to create this site)
Site Elements
- Configuration file
config.pyin root directory- Some SSGs use YAML files, then need workarounds for conditionals etc.
"""Ark configuration file."""
title = "Snail Percolation"
data_dir = "data"
theme = "snails"
src_dir = "src"
out_dir = "docs"
extension = "/"
markdown_settings = {
"extensions": [
"markdown.extensions.extra",
"markdown.extensions.smarty",
"pymdownx.superfences",
]
}
-
Theme lives in
lib/themeextensions: Python to add features (discussed below)resources: CSS and image files copied over as-istemplates: for controlling page layout
-
Markdown files with
.mdextension are turned into HTML
This is the home page.
<!DOCTYPE html>
<html lang="en">
<head>
<link rel="stylesheet" href="@root/style.css">
<title>{{ site.title }}{% if node.title %}: {{ node.title }}{% endif %}</title>
</head>
<body>
<div class="row">
<div class="col-11">
<h1>{{ site.title }}{% if node.title %}: {{ node.title }}{% endif %}</h1>
{{ inc.menu }}
</div>
<div class="col-1">
<p>
<img src="@root/snail.svg" alt="Snail logo" width="80%" />
</p>
</div>
</div>
{{ node.html }}
</body>
</html>
@rootis turned into the path to the root of the generated site{{variable}}is interpolatedsite.namepicks up variables from site configurationpage.namepicks up variables from page header{% if condition %}…{% endif %}is conditional
---
title: Credits
---
- Snail logo by [anarres](https://openclipart.org/artist/anarres)
Customizing
- SSGs weren’t designed with researchers’ needs in mind
- Write our own extensions for things we need and register them as shortcodes
- What we want:
---
title: Analysis Results
---
[%csv 3fd8cbb7.csv %]
- Code for the extension
@shortcodes.register('csv')
def display_csv(pargs, kwargs, node):
"""Handle [%csv filename %] table inclusion."""
assert len(pargs) == 1 and (not kwargs), f"Bad 'csv' shortcode with {pargs} and {kwargs} in {node}"
filepath = Path(ark.site.config['data_dir'], pargs[0])
assert filepath.exists(), f'CSV file {filepath} not found'
with open(filepath, 'r') as raw:
rows = [[val if val else '…' for val in row] for row in csv.reader(raw)]
tbl = PrettyTable(header=False)
tbl.add_rows(rows)
return tbl.get_html_string()
