@nbcnews/machinist

Machinist

Opinionated scaffolding and static site generator for storytelling.

• Metalsmith
• Handlebars
• StandardJS
• Sass
• Stylelint Standard
• Webpack 3
• Babel Preset Env
• Autoprefixer
• HTMLHint
• Editorconfig
• ai2html
• ArchieML

Quick Start

See Setup for recommended local install.

By default machinist init will automatically set the generated project's month and year.

1. Install Node.js (v8.x required)
2. npm install -g @nbcnews/machinist
3. machinist init <project-name> <optional-explicit-month: MM> <optional-explicit-year: YYYY>
4. npm i
5. npm run dev
6. Visit http://localhost:3000

Features

• Included optional CSS/Markup/JS for story components, see ./src/data/models/story.aml
• Add structured data globally via JSON or YAML in the ./src/globaldata/
• Add structured data to a specific file, see Structured Data
• Google Doc to JSON using ArchieML
• Dropbox Paper to JSON using ArchieML
• An ai2html pipeline

Setup

You can either scaffold using the globally installed Machinist or scaffold locally.

By default machinist init will automatically set the generated project's month and year.

Install locally (recommended)

1. cd into an empty project directory
2. npm install @nbcnews/machinist
3. $(npm bin)/machinist init <project-name> <optional-explicit-month: MM> <optional-explicit-year: YYYY>
4. npm install

Install globally

1. npm install -g @nbcnews/machinist
2. cd into an empty project directory
3. machinist init <project-name> <optional-explicit-month: MM> <optional-explicit-year: YYYY>
4. npm install

How To Use

Publishing, Google Doc, and Dropbox Paper workflows require credentials in ./env. You can copy .env.example and rename to .env.

Develop

Runs your project locally at localhost:3000 with BrowserSync. Edit contents of ./layouts, ./lib, ./partials, and ./src.

npm run dev

Develop with debugging.

npm run dev:debug

Dropbox Paper Data (recommended)

Create a new Paper document.

Get the file ID from the URL. It should look like: S7sSIlM2E0g6p3OXhhts4. Add that as the value for dropboxPaperJson.fileId in config.yml.

To ingest the Dropbox Paper you will need to have access to it. Generate an access token for your own account and add the token to ./env.

npm run doc-ingest

Google Doc Data

Create a new Google Doc and optionally paste the contents of ./src/data/models/story.aml to get started.

Get the file ID from the URL. It should look like: 1bj563rIzGL95pvfWORPk-4ukUhRU-GYR55QGx9emyjY. Add that as the value for googleDocJson.fileId in config.yml.

To ingest the Google doc you will need to have access to it. Generate credentials and add credentials to ./env.

npm run doc-ingest

Structured Data

The ./data/models/ folder can have structured data written in YAML, JSON, or AML. In the front matter for the page you can add that data to the page's metadata.

Single file:

----
layout: story.hbs
model: story.aml # Specify the file with your data
----

<h1>{{model.headline}}</h1>

Multiple files:

----
layout: story.hbs
model: # Specify the files with your data
  key1: story.aml # Access by the key set
  key2: data.yaml # Access by the key set
----

<h1>{{model.key1.headline}}</h1>
<p>{{model.key2.source}}</p>

ai2html Workflow

Can be changed, but by default:

• Duplicate or rename assets/##-ai2html-machinist-template.ai for your graphic
• Install ./assets/ai2html.jsx for Illustrator. Docs
• If you are using ArchieML for data, you can use the following to place the graphic in the story

{.ai2html}
title: Optional title
subtitle: Optional subtitle
fileName: name-of-the-ai2html.html
caption: Optional caption
source: Optional Source
{}

• Design and Develop
• npm run publish will update ai2html image paths and rev assets

Build

Generates your dist to be deployed in the folder ./www.

npm run build

Build with debugging.

npm run build:debug

Publish

Generates your dist be deployed and publishes the dist to s3.

npm run publish

Publish assets

Publish static assets in the cdnassets folder, like images, videos and vendor scripts, to the CDN.

npm run publish:cdn

Lint

Lints your styles, scripts, and generated markup.

npm run lint

Format

Fix auto-fixable errors in your styles and scripts.

npm run format

Contribute

git clone https://github.com/nbcnews/machinist.git
npm install
npm run dev