Developers' Guide

Developers' Guide

Developers are responsible for the technical infrastructure of the website and solve complex problems about accessibility, performance, internationalization, SEO, and more.

Commitment summary

• Platform development: Developers will work together to build the front and back ends of the Almanac website, reusing some components from previous editions and building new ones. This is an ongoing commitment with varying levels of work at any given time from June to November.

The amount of time you put in is up to you, but developers typically give about 10 hours over 6 months.

How to join

Leave a comment in the Call for Developers issue.

Browse issues with the Development label.

Tech Stack

The Web Almanac website is built using vanilla CSS and JS, hosted on Google Cloud Platform, through a Python-based Flask application server, serving Jinja2 templates. Wow that's a lot of technical terms!

The tech stack is essentially split into the following pieces:

• Scripts
• Templates
• Python
• Static

These are discussed below:

Scripts

The scripts in the src/tools/generate folder are Node/JavaScript files which are used to convert the chapters (written in Markdown in the content folder), into Jinja2/HTML templates. They use some EJS templates (very like Jinaj2 in functionality but with slight syntax differences). This is run automatically on commit to main using a GitHub template, but can also be run manually. Run npm install from src directory to be able to run the npm run generate command.

Templates

The Jinja2 templates in the templates folder allow us to avoid duplicating code for all the pages, and support multiple languages and years. The templates in the base folders are the majority of the HTML, and the language specific templates mostly just contain translations of various phrases and paragraphs. The individual chapter's HTML should never need be edited directly as it is overwritten with about generate process

Python code

Python scripts in the main src folder are the webserver code, including mapping of URL routes, to templates and various functions made available to the Jinja2 templates. You need to install the dependencies as detailed in the src/README folder and then run the webserver with python main.py so you can browse the site locally at http://127.0.0.1:8080/ using the built in werkzeug development server.

Static folder

The static folder contains CSS, JS, Images, Fonts and other "static" files, that can be served directly by Google Cloud Platform without going through Python application server. Developers will mostly be editing the CSS and JS files. Some CSS and JS in inlined into the template, but for code that is shared across many pages (e.g. the core CSS, or the chapter JS) they are separated out into static files to allow caching reuse.

Config folder

The cofig folder contains a JSON config per year. This allows common config to avoid being hardcoded and using JSON allows the config to be share between the node/JS generate scripts and also the Python/Jinja2 site.

SQL folder

Note the top-level sql folder is a collection of the HTTP Archive SQL queries used to get the stats. It is not used on the site (though there is a link to this from chapters to explore). So mostly developers can ignore this folder and leave it for the https://github.com/HTTPArchive/almanac.httparchive.org/wiki/Analysts'-Guide to manage. They will also create the figure images for each chapter.