@datagraphics/baker

@datagraphics/baker is a build tool by and for the Los Angeles Times. The Times uses it to build the static pages published at latimes.com/projects. You can use it however you'd like.

An example of how The Times puts the package to use is available at datadesk/baker-example-page-template.

Requirements

• Node.js version 14 and higher
• Node Package Manager

Installation

npm install -D @datagraphics/baker

What is Baker and why do you use it?

Baker is a development environment that can be converted into a static website that’s ready for the web. With a minimal amount of HTML, CSS and JavaScript, you can publish a project. The Los Angeles Times uses Baker to write custom code for projects that aren’t possible within the rigid templates of our content management system.

Does anyone else use Baker?

Yes. Here are some examples of Baker is use outside of the Los Angeles Times.

• AMSAT’s amateur satellite index
• The "First Visual Story" training tutorial by Ben Welsh, Armand Emamdjomeh and Vanessa Martinez
• e.e. cummings free poetry archive by Ben Welsh
• Noodle Tracker by Matt Stiles
• hotsauce.gay and men who don't move by Casey Miller
• A variety of news applications by ProPublica, including "Does Your Local Museum or University Still Have Native American Remains?" and "Look Up Which Fortune 500 Companies Fund Election Deniers".
• "Did your neighborhood turn out to vote?" and other features by THE CITY
• Maryland precinct-level election results by The Baltimore Banner
• moneyinpolitics.wtf by Ben Welsh, Derek Willis, Anu Narayanswamy and Agustin Armendariz

If you know of other examples, please add them to the list.

How does Baker work?

Baker brings together a bunch of different technologies.

The HTML templating is powered by Nunjucks, giving us a Jinja2-like experience for organizing and creating our HTML pages. This is also very similar to the templating language used in Django.

CSS styles are written using the preprocessor Sass. Sass enhances CSS by adding features that don't exist in CSS yet like nesting, mixins, inheritance and other tricks. Baker also uses the postprocessor called Autoprefixer, which automatically adds special prefixes to our CSS for browser support. (--webkit, --moz, etc.)

JavaScript is bundled using Rollup, which makes it possible for us to write modern JavaScript that gets optimized and prepared in a way that makes it load as fast as possible for our users. Code we write is passed through a JavaScript compiler called Babel, which rewrites our code to make sure it works in all the browsers we support.

Data imports, powered by quaff, allow for easily imported structured data files into templates, which is useful for making data visualizations.

How do I get started using it?

The repository at github.com/datadesk/baker-example-page-template is our premade starter that comes with HTML, styles and scripts ready for experimentation. It also includes GitHub Actions that can deploy staging and production version of your page. It works after only minimal configuration. You could customize it to match the look and feel of your site.

Contributing

Fork the repository and clone it locally. The enter the code directory and install the package's dependencies.

npm install

Branch off. Make any changes. Preview them with the test server.

npm start

Run our tests.

npm run build

Once they pass, your changes should be briefly documented in the CHANGELOG.md file under the [Unreleased] header. Depending on the type of change you are making, you may need to add a new subheader as defined by Keep a Changelog. For example, if you are changing how a feature works, you may need to add a ### [Changed] subhead.

Commit. Submit a pull request.

Releasing

This package is distributed using npm. To publish a new release, you will need to have an npmjs account with ownership of the @datagraphics/baker namespace.

Next you should use npm's version command to up the version number. You have to decide if you're a major, minor or patch release. If you're unsure, review the standards defined at semver.org. Then run one of the commands below. The code will be updated appropriately.

# Pick one and only one!
npm version major
npm version minor
npm version patch

Rename the [Unreleased] section of the CHANGELOG.md with the same version number. Commit.

git add CHANGELOG.md
git commit -m "Updated CHANGELOG"

Release the new version of the package.

npm publish

Push your work to GitHub, including tag created by the npm version command.

git push origin main --tags

Create a new release on GitHub at github.com/datadesk/baker/releases with the same version number. Paste the changelog entry into the post as a bullet list.