11. Publishing

In our last chapter, all the work we’ve done will finally be published online.

11.1. The importance of being static

Our baker framework, with its tools, structure and shortcuts, has served us well. It’s been a great place to experiment, organize and develop our work. But it’s useless to our readers — it’s the kitchen. We want our readers to have the cake.

We need to publish HTML, JavaScript and CSS files generated by baker. We don’t need the Node.JS code we used to develop them.

The process of converting a dynamic, living website to simple files living on the filesystem is a common strategy for publishing news sites. It goes by different names, like “flattening,” “freezing” or “baking.”

Whatever you call it, it’s a solid path to cheap, stable hosting for simple sites. It is used across the industry for publishing election results, longform stories, special projects and numerous other things.


Examples of static news pages in the wild include:

11.2. Bake your page

Lucky for us, baker is pre-configured to flatten our dynamic site. And GitHub has a hosting service for publishing static pages.

Open the baker.config.js file at the root of the project. It’s the control room where we can adjust how baker works.

To fit our work with GitHub’s publishing system, will instruct baker to output files to the docs directory instead of _dist and set the name of our GitHub repository as the domain. That will require you to make three careful changes to what you see in the file, highlighted below. Take a moment to do that now.

const entrypoints = [
  // Add more script entrypoints here as needed

export default {
  output: 'docs',
  domain: 'https://your-username.github.io',
  entrypoints: `scripts/${
    entrypoints.length > 1 ? `{${entrypoints.join(',')}}` : entrypoints[0]
  pathPrefix: '/your-repo-name/',
// An example of how creating dynamic pages, as described in the README
// createPages(createPage, data) {
//   const pageList = data.example;
//   for (const d of pageList) {
//     const template = 'year-detail.html';
//     const url = `${d.year}`;
//     const context = { obj: d };
//     createPage(template, url, context);
//   }
// },


In my case, that would look like:

  output: 'docs',
  domain: 'https://palewire.github.io',
  entrypoints: `scripts/${
    entrypoints.length > 1 ? `{${entrypoints.join(',')}}` : entrypoints[0]
  pathPrefix: '/my-first-visual-story/',

Return to your terminal where the serve command is running. Hit CTRL-C or CTRL-Z to terminate its process.

Once you are back at the standard terminal, enter the following command to build a static version of your site. Rather than start up the local test server we’ve been using so far, it will instead save the site as flat files in docs.

npm run build

That saves the entire file to the docs folder.

11.3. Commit your work

We’re doing that because it’s the folder expected by GitHub’s free publishing system, called “Pages.”

To take advantage of it, we should start by committing and push to GitHub.

First add.

git add .

Then commit.

git commit -m "Built site to docs folder"

Then push.

git push origin main

11.4. Configure GitHub Pages

Go to the repository on GitHub. Click on the “Settings” tab.

github settings

Click on the “Pages” tab in the left-hand sidebar.

pages tab button

In the “Source” section select the main branch and the /docs folder. Hit Save.

pages tab config

This will result in any files pushed to the ./docs directory of your repository being published on the web. For free.

Wait a few minutes and then visit <your_username>.github.io/first-visual-story/. You should see your app published live on the World Wide Web.

The finished app

If your page does not appear, make sure that you have verified your email address with GitHub. It is required before the site will allow publishing pages. And keep in mind there are many other options for publishing flat files, like Amazon’s S3 service.

If your page does appear, congratulations! You’ve finished this class.