• Stars
    star
    215
  • Rank 183,881 (Top 4 %)
  • Language
    JavaScript
  • License
    MIT License
  • Created about 8 years ago
  • Updated over 1 year ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

A starter template for projects.

Development

Run npm start to fire up the project server. control + c to stop.

Any changes to the src/ folder will trigger live reload.

HTML

Where it goes: src/html/partials/story/.

The main HTML file is src/html/index.hbs. Generally speaking, You should mostly just include new partials in there and not modify too much of it since there are a bunch of presets.

Partials are not automatically included. You must add them to index.hbs. If you created a new file content.hbs it would be referenced as {{> story/content }}.

Sticky Header

Change base/header in index.hbs:

  • {{> base/header 'sticky' }}
  • {{> base/header 'sticky-dark' }}

To use the menu but without it being sticky, simply changed position fixed to position absolute in header.styl.

To add in the patreon message and list, uncomment {{> base/patrons }} in sticky.hbs. Running npm run doc will update to latest patrons.

Metadata

Fill out data/meta.json

Copy

Using a Google Doc for copy is recommended. We use ArchieML as a micro CMS.

Setup Google doc

  • Create a Google Doc
  • Click Share button -> advanced -> Change... -> to "Anyone with this link"
  • In the address bar, grab the ID - eg. ...com/document/d/1IiA5a5iCjbjOYvZVgPcjGzMy5PyfCzpPF-LnQdCdFI0/edit
  • paste in the ID above into config.json

Running npm run doc at any point (even in new tab while server is running) will pull down the latest, and output a file data/doc.json.

You can now reference the JSON in your HTML, namespaced by doc (eg. <p>{{doc.explanation}}</p>).

You can also do the same with a Google Sheet.

SVG Icons

There is a directory called svg in the root of project, it contains a bunch of icons. To include them in the HTML, simply do this:

<img inline src='arrow-left.svg'>

This way you can drop in svg icons anywhere in your HTML code whilst keeping it uncluttered.

JavaScript

Where it goes: src/js/

Take a look at main.js. This is the kickoff file, the only one included and run automatically.

Then take a look at graphic.js, it has some basic skeleton stuff setup for you. This is imported and called from main.js once on load, and subsequently on a debounced resize event. I recommend putting your code in here. If you want to create more files, I recommending doing that in graphic.js, but remember they won't be executed until you import them.

D3 is included globally by default. For any other libraries, it is recommend that you use npm to install and import them. You can also do it the vanilla way by including them in the src/assets folder and putting a script tag in the HTML.

The JavaScript is transpiled from ES6, and uses Parcel to bundle into a single file. That means each file creates its own closure, so a "global" variable is scoped to a file unless you declare it as window.variable = .....

Installing Libraries

NPM way: npm install [name] --save. Usage: (see library docs, but usually) import [library] from '[library]'

Old school: Put JS file in the src/assets/scripts directory. Usage: reference in the index.hbs file <script src='assets/scripts/[name].js'></script>

Helper Functions

In the folder src/js/utils there a are a bunch of handy helper JS functions.

  • dom.js: Super minimial wrapper on basic vanilla dom selection for convenience and cross-browser.
  • is-mobile.js: Device sniffing to detect if on mobile hardware.
  • load-image.js: Async image loading to detect when image completely loaded.
  • locate.js: Estimate user location via ip address.
  • truncate.js: Truncate string with options to break on space and add ellipses.
  • url-parameter.js: Get and set the paremeters of the URL in address bar.
  • lookup-state-name.js: Get state name from state abbrevation.
  • lookup-state-abbr.js: Get state abbrevation from state name.
  • tracker.js: Fire simple GA tracking on events.

To use these, at the top of your .js file, include import functionName from './utils/useful-thing.js'

If there is only one exported function, you can use it in your file with just functionName(). Otherwise, you'll need functionName.specificFunction().

Slider

NoUISlider is included by default, with some preset pudding styles. To include it, simply include the library in your JS file import noUiSlider from 'nouislider'. Then in src/css/config.styl, uncomment no-ui-slider.styl.

Google Sheet

You can pull down a Google Sheet to JSON to include in your JS, or use for templating HTML. Make the sheet sharable, then fill out config.json with the details. By default it will be the file in data/sheet.json which you could use for HTML. You can have it save anywhere by supplying a custom filepath (eg. src/js/example.json or src/assets/data/example.json).

CSS

Where it goes: src/css/story/.

There is a file for you to start off with, story.styl. You can create as many files as you want in this directory, they are automatically included. Note: You must restart the server when you create a new stylus file.

Checkout some of the auto-included files in src/css/utils/ (variables.styl, helpers.styl, presets.styl). You can modify these, especially variables.styl.

Fonts

Fonts are loaded async and use the font-display swap CSS setting.

  • Tiempos Text (default body font)
  • Tiempos Headline (disabled by default)
  • National
  • National Narrow
  • Publico Text (disabled by default)
  • Atlas Grotesk (disabled by default)

Available font-weights (bold means it is loaded by default):

  • Tiempos Text: 500, 700
  • Tiempos Headline: 500
  • National: 500, 700
  • National Narrow: 200, 500, 700, 900
  • Publico: 400, 700
  • Atlas: 400, 500, 600

Variable names in stylus (use these for font-family since they contain proper fallbacks):

  • Tiempos Text: $serif
  • Tiempos Headline $serif-display
  • National $sans
  • National Narrow $sans-display

Assets

Put everything (images, audio, data, etc) in src/assets/.

When deployed, assets paths will remain relative. However, you'll notice that in index.hbs there is a line like <script src='{{basepath}}assets/scripts/d3.v5.9.1.min.js'></script>. basepath here switches from nothing in local development, to https://pudding.cool/ in production. We have a common assets folder for stuff like (which also occurs with fonts). If you need to use this project for a non-Pudding one, make sure to update the data.basepath variable in scripts/html.js.

Deploy

Run npm run deploy

This generates a single html file with inlined css, a single js file, and a folder with assets in the dist folder. It also will automatically optimize jpg and png files in the folders assets/social and assets/images.

Github Pages

Run make github (make sure you've enabled github pages in your repo settings to pull from docs).

Password Protection

In the package.json file, modify the password in the protect script. If using Netlify, make npm run protect the build script.

S3

Requirements:

In Makefile, replace year/month/name with your own (eg. 2017/01/nba). Uncomment code.

Run make pudding to deploy and bust cache. If you only made changes to html/css/js, you can run make aws-htmljs then make aws-cache (it will be much quicker than re-uploading all your assets).

Launch Checklist

  • clean data: reduce filesize bloat by making sure you aren't loading unnecessary columns and rows.
  • remove console logs: aesthetics ๐Ÿ˜„
  • enable anayltics: put UA-90567923-1 in data/meta.json
  • fill out metadata: data/meta.json
  • create two social images:
    • Facebook: 1200 x 628 (src/assets/social/social-facebook.jpg)
    • Twitter: 1024 x 576 (src/assets/social/social-twitter.jpg)
  • Before launching, test the final pudding link in Facebook Debugger to ensure all og tags are working properly.
  • Create Twitter asset:
    • Motion works well on Twitter, so when possible use a scrolling video of the story (.MP4)
    • Tweets should always include some sort of visual asset
    • For one image: 1024 x 576 px
    • if you're sharing multiple images in a post, adjust them to twitter's thumbnail formats โ€” previewed thumbnails have a different aspect ratio (1:1) other than the standard twitter social cards (2:1)
    • Add description of photo or video for accessibility purposes
    • Make sure to include the link
    • Include author/contributor Twitter handle in initial story post
    • Use of emojis is encouraged! ๐Ÿค 
  • Create Instagram Story Asset
    • Portrait aspect ratio (1080 x 1920)
    • Text can be added in Instagram
    • These tend to be more insightful/personal than an initial post
    • Make sure to indicate that the link is in our bio
    • Feel free to experiment here!
    • You can add polls and questions to ask the audience (in stickers)
    • You can tag people here (especially if they are talking about us)
  • Create Instagram Feed Asset
    • Square Images (1080 x 1080) or Videos
    • Make sure to change the link & bio description for new story
    • Emojis are encouraged
    • Hashtags are encouraged. Feel free to use #data #dataviz #ddj #datajournalism #chart #charts
    • Include other hashtags that may be relevant to the specific story
    • Tag people in the image if they are relevant
    • Keep in mind that you can only add one caption (even if there is a carousel of images)
    • The images in the carousel all have to be the same aspect ratio
    • No need to tag authors here
  • Post to Patreon (Author posts)
  • Post to FotP (Author posts)
  • Add data to open data repo (with necessary metadata, scripts when possible)
  • Record Process video and post to FotP/Patreon (optional)
  • Make sure repo is on the-pudding
  • Update s3
  • Update homepage
  • Release assets - author can tap the promotion team to post assets, but otherwise expected that authors post.

Future Proofing

Here are some best practices to follow to increase the likelihood that the story doesn't break in the near future.

  • When possible, host assets locally. Put things like images and audio in your project rather than loading from a third party.
  • Don't rely on externally hosted scripts. If you are using a library, use npm or self-host in favor of externally hosted scripts.

More Repositories

1

data

Data sets created for stories on The Pudding, open to the public.
HTML
869
star
2

svelte-starter

A Svelte starter template for projects
Svelte
375
star
3

how-to-implement-scrollytelling

How to implement scrollytelling with six different libraries
HTML
94
star
4

website

The Pudding's website
Svelte
61
star
5

wiki-death-data

JavaScript
45
star
6

censorship

Svelte
44
star
7

blog_scrollytelling-sticky

JavaScript
39
star
8

song-repetition

Are Pop Lyrics Getting More Repetitive?
JavaScript
35
star
9

this-american-life

Jupyter Notebook
19
star
10

lenna

JavaScript
17
star
11

last-two-minute-report

JavaScript
16
star
12

eu-regions

CSS
15
star
13

puddingR

An R package for Pudding-styled analysis
R
13
star
14

svelte-templates

Svelte
12
star
15

lenna-data

Jupyter Notebook
10
star
16

the-svelte-way

Svelte
9
star
17

wiki-billboard-data

JavaScript
9
star
18

year-in-music-apple-music

JavaScript
9
star
19

bad-music-public

JavaScript
9
star
20

smoothing_tutorial

regional smoothing in r
HTML
8
star
21

wiki-death

JavaScript
7
star
22

falsetto-story

JavaScript
7
star
23

people-map

JavaScript
7
star
24

svelte-summit

Svelte
7
star
25

comics

HTML
7
star
26

banknotes

Svelte
7
star
27

nba-player-data

JavaScript
6
star
28

pass-the-mic

A browser extension to visualize how much each person is talking in Google Meet.
JavaScript
6
star
29

old-website

HTML
5
star
30

starter-cli

JavaScript
5
star
31

emo-rap

JavaScript
4
star
32

emotion-wheel

Svelte
4
star
33

song-decay-clean

JavaScript
4
star
34

instagram-comment-data

JavaScript
4
star
35

wiki-billboard

JavaScript
3
star
36

responsive-scrollytelling

JavaScript
3
star
37

nyt

Jupyter Notebook
3
star
38

pockets

JavaScript
3
star
39

yard-sale

Svelte
3
star
40

music-taste-2019

JavaScript
3
star
41

votes-for-women

JavaScript
3
star
42

hyphenated-names

HTML
3
star
43

birthday

JavaScript
3
star
44

blog-svelte-d3

HTML
3
star
45

wine-model

JavaScript
3
star
46

location-game

Svelte
3
star
47

word-game

Svelte
2
star
48

retraining

Jupyter Notebook
2
star
49

cough

Svelte
2
star
50

airports

JavaScript
2
star
51

cetaceans

JavaScript
2
star
52

sixty

Svelte
2
star
53

cities_interactive

JavaScript
2
star
54

summer-reading

JavaScript
2
star
55

people-map-uk

JavaScript
2
star
56

crossword-generator

JavaScript
2
star
57

songwriters

Svelte
2
star
58

clocks

Svelte
2
star
59

infinite-web

HTML
2
star
60

flooding

JavaScript
2
star
61

real-mvp

JavaScript
2
star
62

heat-records-map

Svelte
2
star
63

streaming

JavaScript
2
star
64

book-covers

JavaScript
2
star
65

kpop

kpop kontinentalist story
JavaScript
2
star
66

sleep-training

Svelte
2
star
67

campaign-colors

JavaScript
2
star
68

dress_codes

HTML
2
star
69

karen-viz

JavaScript
1
star
70

vogue

HTML
1
star
71

apology

JavaScript
1
star
72

new-slang

1
star
73

gendered-descriptions

JavaScript
1
star
74

hs-hype

JavaScript
1
star
75

wrestling

Svelte
1
star
76

earnings-call

HTML
1
star
77

3d-cities-story

JavaScript
1
star
78

kidz-bop-data

R
1
star
79

birth_control

HTML
1
star
80

pudding-cup-2019

JavaScript
1
star
81

falsetto-site

JavaScript
1
star
82

three-seconds-etc

JavaScript
1
star
83

outliers

Svelte
1
star
84

millennial_killers

JavaScript
1
star
85

localsandtourists

JavaScript
1
star
86

ig-links

HTML
1
star
87

women-in-headlines

JavaScript
1
star
88

covid-science

JavaScript
1
star
89

outliers-data

Jupyter Notebook
1
star
90

millennials

JavaScript
1
star
91

weather-temps

Svelte
1
star
92

generational-knowledge

JavaScript
1
star
93

how-to-make-dope-shit-part-3

JavaScript
1
star
94

pudding-awards-2018

JavaScript
1
star
95

author-locations

JavaScript
1
star
96

nba-top-plays-2018

JavaScript
1
star
97

predictive-text-twitter

JavaScript
1
star
98

sankey

JavaScript
1
star
99

karen-data

JavaScript
1
star
100

makeup-shades

JavaScript
1
star