Getting Started

Portway, a “Markdown-based, collaborative document app,” pairs really nicely with the static-site generator Eleventy. This starter template provides all the tools you need to set up a simple blog using Portway as the backing CMS.

Here’s what we’ll cover in this guide:

1. Creating your own blog using this template and deploying it to Netlify
2. Adding a new project in Portway
3. Granting read-only access to Portway from Netlify
4. Connecting Portway publishing to trigger new builds in Netlify

To follow along, you’ll need accounts on the following services:

• Portway
• Netlify or a similar static hosting service
• GitLab, GitHub, or a similar Git provider

The guides in this template use Netlify to demonstrate how to publish your blog, but many of the same concepts will apply if you use a different host.

Ready? Let’s get started!

Deploy to Netlify

To create your own copy of this template and get up and running on Netlify, click this handy button:

You’ll be prompted to create a new repository on your preferred Git provider:

Enter a name for your repository (if you’ve already chosen a name for your blog, go ahead and use it here), then click Save & Deploy.

When Netlify’s deployment robots finish building, click the new randomly generated netlify.app URL in the upper right corner to open your new site. You should see something like this:

Let’s head over to Portway now to get things set up on that end. We’ll come back shortly to configure a few details in Netlify.

Portway

Create a new project

A “project” in Portway is a collection of related documents. Let’s create a new project to use as the source for your blog posts:

1. Click the + New project button
2. Enter your blog’s name and description
3. Click Create Project

Project ID

Once you’ve created a new project for your posts, locate the project ID in your browser’s address bar:

Make a note of this number somewhere, we’ll need it in just a bit.

Generate API keys

To access to your Portway project’s contents from Netlify, we’ll need to create an API key.

1. Click the Project Settings link at the bottom of the Portway window
2. Select API keys
3. Click the Add project key button
4. Enter a key name that describes the environment where it will be used
5. Leave Role set to Reader to ensure contents are read-only
6. Click Create key

Heads up! Treat this API key just like you would a password. Store it securely and don’t share it with anyone.

Once you’ve generated an API key, copy the string for use back over at Netlify.

Tip — Consider generating separate keys (ex., one for your local machine and one for Netlify) rather than reusing the same key in multiple environments.

Netlify

Environment variables

Netlify needs to talk to Portway each time your blog is built. We’ll use environment variables to store your secret API key and project ID:

1. Open your site in the Netlify dashboard
2. Navigate to Site Settings → Build & deploy → Environment
3. Click Edit variables
4. Add PORTWAY_API_KEY and paste the API key you generated in Portway
5. Add PORTWAY_PROJECT_ID and enter your Portway project’s ID number
6. Click Save

Build hooks

To take advantage of Portway’s Publish feature, we need to generate a Netlify “build hook,” a special URL Portway will use to let Netlify know it’s time to re-build your site.

1. Open the Site Overview for your site in the Netlify dashboard
2. Navigate to Site Settings → Build & deploy → Build hooks
3. Click Add build hook
4. Enter a descriptive name (ex., “Portway”)
5. Click Save

Heads up! Just like the API key, store this URL securely and don’t share it with anyone.

Copy the URL and head back to Portway for our final setup step:

1. Click the Project Settings link at the bottom of the Portway window
2. Select Webhooks
3. Paste the Netlify build hook URL
4. Click Add endpoint

That’s it! Netlify and Portway are now configured for two-way communication 🎉

Next…

With the initial setup complete, it’s time to create your first blog post!