Spectate

Spectate provides a workflow for building and publishing freeform stories. It allows reporters to code locally while writing stories in Google Docs.

Check out these examples: University responses to COVID-19; EOAA investigation; Union Theological Seminary.

Prerequisites

1. Install Git and make a GitHub account. Ask your Graphics editor or deputy editors to add you to the graphicsdesk organization.

2. To be able to write to our repositories, set up an SSH key. Follow the instructions in the first five sections of Connecting to GitHub with SSH.

3. Install Node.

4. Install a code editor. Visual Studio Code is a great option. (If you use VS Code, I highly recommend going through the First Steps in the documentation).

5. You should be comfortable coding in HTML, CSS, and JavaScript. You should also be familiar with using git and version control.

Install Spectate

Spectate is a command line tool (just like ls and javac). The following steps download Spectate onto your computer and make it available on the command line.

1. Clone the Spectate repository into your home directory and move into it:

$ git clone https://github.com/graphicsdesk/spectate.git ~/spectate
$ cd ~/spectate

2. Install the necessary Node packages:

$ npm install

3. Make the spectate command available everywhere:

$ npm link

4. Lastly, to authorize Spectate to download Google Docs, you'll have to set up Google Docs API credentials (make sure you're signed into Google with your Spec account). Follow this guide to finish this setup.

Creating a Spectate project

Read about how a Spectate project works.

1. In the terminal, create a new directory for your project. The name of the directory should be the slug of your article. The slug you choose will hereafter be referred to as SLUG. Move into the directory.

$ mkdir SLUG
$ cd SLUG

2. Next, run $ spectate create. You will be prompted for your choice of a template. If your story is a single page, choose default. If your story is multiple pages, choose series. The command copies the relevant template files of a Spectate project, like boilerplate HTML/CSS and ai2html configuration, into your directory.

3. On GitHub, create a new repository in either the graphicsdesk or NewsroomDevelopment organization (depending on your department) with SLUG as the name.

4. Run $ spectate init, which helps set up the remote connections necessary to your project. It will first prompt you for the article slug. If you leave the answer blank, it will use the name of your project directory by default. It will then ask you for the GitHub organization the repository is at. Finally, it will ask for a Google Docs link for the project. To create a Spectate template Google Doc, open the Spectate Doc template by inputting o into the prompt. Make a copy of the Doc (Make sure you DO NOT edit the original template). Paste the new Doc's link into the prompt.

5. spectate create has already created an initial commit for you. Push it to GitHub by doing:

$ git push -u origin main

6. See Usage for further instructions.

Cloning a Spectate project

Make sure you have first completed the prerequisites and installation instructions.

To clone a Spectate project, run:

$ spectate clone SLUG

This will clone the repository https://github.com/graphicsdesk/SLUG.git into a new directory named SLUG and install the project's dependencies. See Usage for further instructions.

Usage

Read about how a Spectate project works.

To start developing, run:

$ npm start

This starts a local web server at http://localhost:1234 that shows you what your page looks like. If you edit and save any code, the page automatically rebuilds and refreshes.

To re-download the Google Doc or update the project's configuration, run:

$ spectate download

Running this command in a terminal tab other than the one you ran npm start in also automatically refreshes the page with the updated content.

To add a graphic to your story (i.e. custom HTML), read this. To add Illustrator artwork (using ai2html), read this.

To add a scrollytelling interactive, read this.

The primary file for SCSS goes into src/styles.scss (SCSS is just CSS with better features, like nested selectors and variables). style.scss can reference/import other styling files from the src/styles/ directory. It's highly recommended that you make a separate styling file for each major chunk of your project. (For instance, if your story has two big graphics that don't have much to do with each other, your code is more organized/navigable if the styling for those graphics are in separate files.) If you have a stylesheet src/styles/scatter-plot.scss, you can import it in src/styles.scss with the line @import styles/scatter-plot.

The primary file for JavaScript is src/script.js. Again, it's recommended that you make separate files for each major feature of your project, and that you organize all these files in the src/scripts/ folder. Don't forget to import it in the main script.js file by adding import './scripts/file-name.js somewhere at the top of script.js. If you're using D3, rather than loading all of D3 as a script or package, opt to install the different libraries of d3 individually. For instance, if you only need select, install just the d3-selection library. This makes JavaScript builds much smaller.

A well-organized project will minimally modify src/index.html, src/styles.scss, and src/script.js. Instead, those files should import/reference small, feature-bounded components.

Here are some other resources:

• Import data to use in JavaScript)
• Add a cover image to the story
• Detailed reference of the Spectate API.
• Publish a Spectate story (scroll down)

Note: All images and videos should be uploaded to Arc's Photo Center. Their public links can then be put directly in the code or in the Spectate Doc.

Publishing on GitHub Pages

Just run spectate gh-publish.

Go to the Settings tab in the repository's GitHub page. Make sure the repository visibility is set to Public. Scroll down to the GitHub Pages section. You should see this:

That means GitHub is starting up the page, but it's not ready yet. Keep refreshing the page. Once you see this screen…

…the link should work. It will show the build that was generated in the dist/ directory.

Publishing on Arc

1. Run spectate prepublish, which will help you set up the S3 URL. Make sure you have completed the AWS setup. Uncomment the appropriate override stylesheet at the top of src/styles.scss.

2. Run spectate publish. (Whenever you want to update JS or CSS assets after publication, just run this command again.)

3. Copy the contents of dist/index.html into an HTML block in an Ellipsis story. (More detailed instructions here.)