Make a Tarbell

Tarbell is a tool that blends a Google spreadsheet and a web template to make beautiful, self-contained web packages.

The Chicago Tribune News Applications Team originally developed Tarbell, and now it is maintained by a broader group of interested parties. Al Jazeera America developed the Big Reader template that we are using as a base.

Extra credit trivia: Tarbell draws its name from Ida Tarbell (1857-1944), a muckraker known for her investigative journalism.

Video demo

<htmlet>tarbelldemo</htmlet> You can check out the spreadsheet from this demo here.

Accessing Tarbell

1. Open Terminal from your applications folder.
2. Type workon tarbell1.0.4 and press enter. You will now see (tarbell1.0.4) before your username.

(Note: This assumes that Dani has installed all of the necessary components on your system. If that's not true and you want it to be, get in touch.)

Create a new Tarbell project

The command is tarbell newproject YOURSLUG, where YOURSLUG is a brief name for your project that does not contain spaces or punctuation. This slug will be used in your site's URL, but in very little else. Type that command and press enter.

The project creation process will walk you through everything else:

• Where would you like to create this project?
  • Hit enter to create the project in the default location within your user folder.
• What is the project's full title?
  • Spaces and punctuation are fine here.
• Pick a template
  • Hit 4 and then enter to select the Big Read Builder template.
• Would you like to create a Google spreadsheet?
  • Why yes, yes you would. Hit y and enter.
  • Enter the Google accounts INCLUDING YOURS that should have access to the spreadsheet and press enter. You can always share the spreadsheet after the fact, as well, using the blue Share button in the upper right corner of the Google spreadsheet app.
• Install requirements now with pip install -r requirements.txt?
  • Hit y and enter.
• Would you like to create a Github repo for this project?
  • Don't bother. Just hit n and enter.

Before you head over to the Google spreadsheet, type tarbell switch YOURSLUG and press enter. This turns on the local server that allows you to view changes as you make them. (Alternately, you can enter cd /Users/YOURFIRSTINITIALANDLASTNAME/tarbell/YOURSLUG and tarbell serve. This does the same thing as tarbell switch YOURSLUG but also sets the project folder as the active directory in Terminal.)

Entering content

Enter the content into the Google spreadsheet, bearing the following in mind:

• Images should be in the tarbell/YOURSLUG/img folder in your user folder. They should also be 72 dpi jpgs with a maximum dimension of 1200 px.
• Reload the locally served page at 127.0.0.1:5000 after every change, so you know what to undo if it breaks.
• See the video for more information about entering content.

Generating output

1. Replace the _content.html, _global-variables.html, _intro.html, socialbuttons.js and theme.css files within tarbell/YOURSLUG.
2. Go back to terminal and press command-c to stop the local server.
3. Type cd /Users/YOURFIRSTINITIALANDLASTNAME/tarbell/YOURSLUG and hit enter to ensure that you're in the right folder. Otherwise, you won't be able to do the next step. (So if the next step fails, make sure you're in the right folder!)
4. Type tarbell generate _output and press enter. If you've already generated output for this site (i.e., you've made a change in the spreadsheet and need a new set of files to put on webFeatures), hit y when prompted (followed by enter) to overwrite the old output files.
5. After the Terminal process is complete, edit _output/index.html to remove the space between the author and any title that follows his or her name.
6. Connect to webFeatures and upload the contents of the _output folder into a new folder within the tarbell directory. (Note that this path should match the URL you entered into the spreadsheet.)

Troubleshooting

If you get an error, try the following:

• Go back and undo the last change you made. Are you using the right id? Is it in the right place? This site has a thorough reference for that.
• Is it possible that you deleted the contents of A1 on any of the pages in the spreadsheet? Go double-check.
• Did you change the id or group id for something? If so, make sure that you've also updated any references.