Andrew Stiefel | guides

Building a Personal Monorepo for Writing

2025-07-19T00:00:00-07:00

I use Obsidian to organize my thinking and writing. But I’ve always been dissatisfied with the process of turning what I write into a formatted post for my website. I either had to manage multiple vaults—adding complexity and violating one of my core principles of note-taking—or copy, paste, and edit my writing in another tool like VS Code.

I also prefer to keep my content separate from the website’s design, and I wanted to do that without introducing a CMS or additional tooling. Static site generators like Jekyll are great at converting Markdown into websites, but they usually require you to store content alongside all the other website files.

After some experimenting, I landed on a better solution: building a personal monorepo for my writing and publishing workflow.

Why use a monorepo?

A monorepo—short for monolithic repository—combines code for multiple projects into a single repository. A common pattern is to store both frontend and backend code in one place.

That’s actually a good analogy for how I think about writing. The “backend” is my Obsidian vault, where I research and take notes. The “frontend” is the website where I publish finished posts.

Basic Setup

To start ,I moved my Obsidian vault and Jekyll website into a new personal-monorepo directory structured like this:

~/personal-monorepo
          ├── /notes
          └── /website
          

If you don’t already have an Obsidian vault or Jekyll site, you can easily replicate this from scratch. Install Obsidian, open the /notes directory using the “Open folder as vault” option, and you’re ready to go.

Setting up Jekyll requires a bit more technical work, but you can find installation instructions here.

Configuring Obsidian

For this approach it’s important to make a directory where you will only store published posts. I’m going to use /notes/posts for this tutorial but you can configure this directory any way you wish.

I also recommend installing two Obsidian community plugins:

Obsidian Git – adds version control and makes publishing easy
Obsidian Permalink Opener – lets you open post URLs in your browser for previewing

For Git, you can push commits manually or set up periodic syncs. For the Permalink Opener plugin, I added both my website’s base URL and my local development URL so I can preview posts in the browser while editing.

With that we’re ready to move on to building our website.

Connecting Jekyll and Obsidian

By default, Jekyll looks for posts in /website/_posts. But I want it to use the content in /notes/posts. The simplest solution is to create a symbolic link.

First, open Terminal and make sure you’re in the root of your monorepo (~/personal-monorepo). Back up your content, then delete the existing _posts directory:

rm -rf website/_posts

Next, create a symlink that points to your Obsidian posts:

cd website
          ln -s ../notes/_posts _posts
          

Note: Folder names in symlinks are case-sensitive. If your Obsidian vault uses Posts instead of posts, your symlink won’t work with the above command. Folder names must match exactly.

Publishing with Netlify

Netlify provides first-class support for working with monorepos, but you’ll need to do a little additional configuration.

In your project dashboard or netlify.toml file, set the base directory to website, and make sure the build command installs dependencies before running Jekyll:

Here’s what my full netlify.toml looks like, and what is reflected in my dashboard:

[build]
          base = "website"
          command = "bundle install && bundle exec jekyll build"
          publish = "_site"
          

Netlify follows symlinks automatically, but Jekyll needs one extra setting. In your website/_config.yml, add:

# Enable access to symlinked content
          lax_symlink_lookup: true
          

This lets Jekyll access files stored outside its root directory (e.g. the website folder). Without the site will build but won’t pull in your content from the notes/_posts directory.

Final Workflow

I have Obsidian configured to add new notes to my writing inbox under the ~inbox directory. Anything I start writing goes there. Once I’ve finished writing a note, I can then either move it into my permanent notes or add it to the posts directory if I want to publish it. Once I push the commit Netlify will build and publish my site.

While I’m writing, I can preview what the note will look like by starting the Jekyll development server (bundle exec jekyll serve) and adding the note to the posts directory. I can use the Obsidian hotlinks command to open a preview of the post in my browser.

To wrap up, your final workflow looks something this this:

Write, edit, and link notes in Obsidian
Commit and push changes to Github
Netlify will pick up the changes and publish your posts

Bonus: Convert Backlinks to Weblinks

It’s outside the scope of this post, but I also wrote a custom plugin to convert backlinks to web links. That way I can use Obsidian’s backlinks within my published posts.

You can grab the code here.

Additional Resources

How I Use GitHub as a CMS

2025-02-02T00:00:00-08:00

I use Jekyll to build and publish my blog on Netlify. For a long time my content management system (CMS) was just a bunch of markdown files on my laptop. Most of the time I don’t need anything else — it’s simple, and it’s just me.

But as I’ve wanted to focus on writing more often, I wanted to find an easier way to track future ideas, what I’d like to work on now, and easily see what I’ve done.

That’s where GitHub comes in.

Why?

GitHub is built for software development, but many of the features work just as well for content development. In fact, is has about everything I need as you’ll see in my setup section below. This includes templates, project boards, and workflows for publishing.

Plus it’s easy to review and collaborate with other people. I don’t do that much as a solo writer, but I do get readers who spot typos or who share feedback—and then it’s easy to track and add their contributions.

But let’s be honest — this is one of the projects I took on because I could, not so much because it really saves me any time. Choose your adventure accordingly :)

Basic setup

If you’re already using GitHub to host the code for your blog (like I do with Jekyll), then you can get started with this in 15 minutes or less!

Create a project: Go to the GitHub repository for your blog (or make a new one!) and select projects and create your project.
Choose a format: GitHub projects lets you customize views of items in your project using a Kanban board or table format. I recommend starting with the Kanban format. You can always change this later.
Organize your workflow: Once you’ve created your project, take a couple minutes to configure your workflow. I have sections for no status (my backlog), in progress, ready, and done.

You can see an example of mine on GitHub, or with the screenshot below:

Use issues to track posts

Once you’ve created the basic structure, it’s time to start tracking your writing! You’ll want to create new issues so you can track your progress. I decided to create a new template so I wouldn’t have to add the same info every time.

If you’d like to create one, all you need to add is a markdown file in your repository at the location below:

.
          ├── .github 
          │   └── ISSUE_TEMPLATE
          │      └── cms.md
          

Here’s an example of what mine looks like:

---
          name: cms
          about: Submit an idea for the blog
          title: "[blog post] "
          labels: cms
          assignees: ''
          ---
          **What is this post about?**
          **Outline**
          1. 
          **Tasks**
          - [ ] Write outline
          - [ ] Draft blog post
          - [ ] Find (1) reviewer
          - [ ] Create pull request
          

I use the format [blog post] example title so I can see at a glance that the issue covers a new blog post, and roughly what it’s about. I provide a brief description (usually when I first have the idea). Later I’ll come back and outline the post.

Writing and publishing posts

Jekyll comes with basic structure which makes it easy to get started. I save my draft writing in the _drafts folder and move finished posts into the _posts folder.

.
          ├── _drafts 
          ├── _posts
          

But you have a few options to customize your workflow a bit further:

Work directly in your main branch and publish by moving the your finished drafts from the _drafts folder to the _posts folder.
Create a new branch for each post as you work and merge into your main branch when you’re ready to publish.

JEKYLL TIP You can preview your posts in your development environment as you work! Just append the --drafts flag to the build or serve command. For example, jekyll serve --drafts. Each draft post will be added using the last modified time as the publication date.

I prefer to create a new branch and to submit a pull request when I’m ready to publish (although I’ll admit, I’m not super consistent since it’s just me). Either way, when you’re ready to publish, you’ll close the issue for your blog by writing a commit message that includes the number of the issue. For example, when I published this blog, I used “Closes 212” to tell GitHub to mark the issue as done.

Now if you visit your project, you’ll see your post has automatically been moved to the “done” column!

Final thoughts

I’ve been exploring ways to customize this further by creating new views — for example, a table view that adds publication dates so I can when I want to publish a post. But most importantly, I’m enjoying the flexibility and close integration between what I write and how it’s published.

Working with Multiple GitHub Accounts and SSH Keys

2024-05-09T00:00:00-07:00

I have multiple GitHub accounts – one for work, one for demos, and one for personal projects. Each has a unique email address, password, and 2FA associated with it. They also each have a unique SSH key. In fact, the SSH keys are all saved in different 1Password accounts (personal, demo, and work).

In some cases I perform the development on the same device, like when I’m building a demo on my work device. In that case I need to make sure that I’m using the correct GitHub account and SSH key.

I use 1Password as my SSH agent because it keeps the private keys off my device, plus it makes authorizing SSH connections a breeze. I can authenticate a connection using Touch ID, so just a fingerprint touch on my keyboard and then I’m off to my next task.

Fortunately, this only takes a few minutes to setup!

Organize your local directory

All my repositories are saved under a GitHub folder and then I use directories to organize my projects by account. Although I prefer to keep personal and work separate, you could configure all three accounts for a single device like in the example below:

~/github
          ├── /demo
          ├── /personal
          └── /work
          

This will make it very easy to configure which profile and SSH key to use in the following steps.

Set your global gitconfig file

In this example, I’m setting my personal Git configuration as the global default. Using [includeIf] I specify a different .gitconfig file for the demo and work directories.

[user]
          name = <github_personal_name>
          email = <github_personal_email>
          signingkey = <your_ssh_key>
          [gpg]
          format = ssh
          [gpg "ssh"]
          program = "/Applications/1Password.app/Contents/MacOS/op-ssh-sign"
          [commit]
          gpgsign = true
          [includeIf "gitdir:~/github/demo"]
          path = ~/github/demo/.gitconfig
          [includeIf "gitdir:~/github/work"]
          path = ~/github/work/.gitconfig
          

Create gitconfig files for each directory

Next I’ll create .gitconfig files and save them in the demo and work directories. I’ll use a similar template, but this time I’ll provide the GitHub name, email, and public signing key for my demo and work accounts.

[user]
          name = <github_work_name>
          email = <github_work_email>
          signingkey = <your_ssh_key>
          [gpg]
          format = ssh
          [gpg "ssh"]
          program = "/Applications/1Password.app/Contents/MacOS/op-ssh-sign"
          [commit]
          gpgsign = true
          

Configure the SSH agent

In order to call the correct SSH keys, I’ll need to update the SSH agent config file located at ~/.ssh/config.

I start by setting the 1Password SSH agent as the default for all hosts. Then I create custom hosts for each account, in this case Demo, Personal, and Work.

Next, I downloaded the public keys from 1Password for my demo, personal, and work accounts. I renamed each file (for example, demo_git.pub) and saved the all to my ~/.ssh/ folder.

# By default, use the 1Password SSH agent for all hosts
          Host *
          IdentityAgent "~/Library/Group Containers/2BUA8C4S2C.com.1password/t/agent.sock"
          # Demo GitHub
          Host gh-demo
          HostName github.com
          User git
          IdentityFile ~/.ssh/demo_git.pub
          IdentitiesOnly yes
          # Personal GitHub
          Host gh-personal
          HostName github.com
          User git
          IdentityFile ~/.ssh/personal_git.pub
          IdentitiesOnly yes
          # Work GitHub
          Host gh-work
          HostName github.com
          User git
          IdentityFile ~/.ssh/work_git.pub
          IdentitiesOnly yes
          

Reset your local repositories

Finally, I’ll need to reset each individual repository so it uses one of the hosts specified above. This will make sure it uses the correct SSH key to authenticate with GitHub and when pushing Git commits.

git remote set-url origin <host>:<organization>/<repository>.git

Finally, run git remote -v to confirm that Git is using the correct remote repository. You can run git fetch to confirm that 1Password offers up the correct SSH key for authentication.

Resources

Configure Multiple Git Signing Setups (1Password)
Use Multiple GitHub Accounts (1Password)
Adding a New SSH Key to Your GitHub Account (GitHub)
Register a Public SSH Key with GitHub (1Password)
Testing Your SSH Connection (GitHub)
Switching Remote URLs from HTTPS to SSH (GitHub)
Optimize Your Git Setup: Strategies for Handling Multiple GitHub Accounts (Dev.to)

Pocket Guide to Privacy-First Email Newsletter Software

2023-02-09T00:00:00-08:00

When I first started to look for privacy-first email newsletter options back in 2019, there just weren’t many options. There were great privacy-first website analytics tools like Fathom Analytics, but nothing for email. Nearly every provider required tracking pixels by default.

I want to briefly acknowledge that there are some legitimate reasons why email newsletter software providers might require pixels. Tracking pixels are one way to evaluate a sender’s reputation and ensure overall deliverability for everyone using their platform. Higher open and click rates indicate that a list is engaged. The reverse could indicate that an account is sending spam emails.

The problem is that tracking pixels collect far too much information, including exact location information from each recipient. Most of us understandably don’t want senders to know where we read an email, how many times we read that email, what links we clicked, and how many times we clicked each link.

There are, of course, other ways to evaluate list engagement. Unsubscribes and spam reports are a clear signal – and they are the indicators that matter most. As a sender, you can evaluate email engagement by website traffic, list growth, unsubscribes, spam reports, and other methods.

The good news is that over the past year or two many major email newsletter providers have started to let you turn off email trackers (e.g. MailChimp, but with limitations). Other providers still do not (e.g. ConvertKit).

I wanted a provider that offered a privacy-first by default platform. So I compiled a list and I’m sharing it here. My criteria for inclusion in this list were simple:

Open and click tracking are turned off by default
Does not use Google ReCaptcha on the subscription form
Does not have third-party trackers (e.g. Google Analytics) on their website

Below is a list of the email newsletter services that met the criteria, as well as their lowest price point as of February 9, 2023:

Company	Tracking	HQ Location	Cheapest Plan
Buttondown	Off by default	US	Free up to 100 subscribers
SendStack	None	EU	Free up to 100 subscribers
MailCoach	Off by default	EU	$9.99

Buttondown

Buttondown is a minimalist tool for writing and producing email newsletters. Based in the United States, it is run as an indie software business. Buttondown gets a lot of things right, like privacy-first by default (you can, however, opt-in to tracking if you want), the ability to write in markdown, RSS-to-Email tools so you can run your own version of Substack, and a first-party API that is included in the free plan for the hackers among us.

SendStack

SendStack is one of the newest tools and was released by a team based in the European Union (Germany, specifically). It has fewer features than Buttondown but a much friendlier user interface. They also make their first-party API available to free plans, which is a great feature for developers or anyone wanting to build their own first-party email newsletter subscription form. SendStack takes a much harder line on automation, however, so there is no RSS-to-Email function or other automation tools.

MailCoach

MailCoach offers both a hosted and a cloud-based solution. Interestingly, they also support transactional email. Like the other platforms here they offer a streamlined interface. But unlike Buttondown and SendStack, automation and transactional email are treated as important features. This is a good solution if you need more than just a newsletter, and would be a great option for agencies, businesses, or anyone building more complex email workflows.

Conclusion

I have personally used Buttondown and SendStack, but I haven’t tried MailCoach yet. This isn’t an endorsement of any particular service. You should try them out and see what works best for you. I also recommend this article comparing pricing models for privacy-first email newsletter services if you are considering one of these platforms.

But, if you’ve been looking for a private alternative to Mailchimp and similar services, you now have a handful to choose from. I’m looking forward to seeing this space grow as more creators and businesses start to adopt privacy-first marketing practices in the future.

Build an Email Subscription Form with Netlify Functions

2022-08-28T00:00:00-07:00

I enjoy the process of building and maintaining my own personal website. It’s a great way to experiment with different technologies, and have fun learning new tools and concepts along the way.

This time, I wanted to learn how to use serverless functions. There are a lot of great resources out there already. But I had trouble finding a guide that adequately addressed my use case: a humble email subscription form.

This tutorial is strongly inspired by an excellent guide created by Matthew Ström. I’ve added solutions for some of the problems I encountered while following his guide, but Matthew deserves the credit.

After going through all the work to build my personal website, the last thing I wanted to do was slap a pre-designed newsletter subscription form on it.

I wanted the flexibility to design my own custom forms for a few reasons:

Better design: Email marketing providers offer great default forms, but they never perfectly match a site’s design
Better Performance: External email forms require additional calls for CSS and Javascript, and they sometimes get blocked by privacy settings
Better privacy: Hosted email forms can collect additional information about users, like their IP address

I set out a few rules for this challenge:

It should work without extra JavaScript or AJAX
It must use Netlify functions
It shouldn’t need external dependencies

The Team: Jekyll, Netlify, and ConvertKit

My website is built using a static site generator called Jekyll. It allows me to build my own templates and components, so I’ll use it to build my email form. I also used Tailwind CSS Forms Plugin to simplify the design process.

I use a service called Netlify to deploy my website. It’s key for this project, because it complies the static assets built by Jekyll and runs the serverless function to send emails to my email list provider.

Finally, I’m using ConvertKit as my email list provider. I’ve also included information on how to use Buttondown and SendStack in this tutorial, but the basic principles of the function should apply to any other email providers that offers an API.

Ok, let’s get started!

Create the serverless function

You need to follow three basic steps to create a Netlify function:

Add API tokens to Netlify as environment variables via the admin interface
Tells Netlify where to look for your functions using the netlify.toml file 3. Write the function in a Javascript file in your project
Write the function as a Javascript file in your project

To start, let’s save the API token from our email service as an environment variable. Environment variables are useful to hold information that I don’t want to make public, like this API key. You can add an environment variable using the Netlify admin interface under your build and deploy settings.

Next, specify where Netlify should look for your functions. Edit your netlify.toml to specify the functions directory. It might look something like this:

[build]
          base = "."
          [functions]
          directory = "netlify/functions/"
          

Create a function file in the directory you specified above. If you used the default functions directory, you should save your function at YOUR_BASE_DIRECTORY/netlify/functions.

Next, you’ll need to give your function a name. For example, to create a function with an endpoint name of hello-world, save the function in one of these locations:

netlify/functions/hello-world.js
netlify/functions/hello-world/hello-world.js
netlify/functions/hello-world/index.js

For this tutorial, I’m going to use the submission-created event trigger. Netlify will run my function every time a form is submitted. To do that, I’m going to name my function submission-created.js.

Now you’re ready to start writing the function. Start by importing the API key you created earlier as an environment variable:

const { EMAIL_TOKEN } = process.env
          

On line 2, I add a small library called node-fetch. This allows me to use Javascript’s Fetch API, which is how we’ll format an API POST request to send data to our email service.

import fetch from 'node-fetch';
          

NOTE: When I was writing this post, many of the tutorials available used the require method to import the Fetch API which resulted in errors when I tried to deploy the function. Make sure you use the method I described above. If you upgrade to node-fetch v3, you’ll also need to update either your netlify.toml file or package.json to use ESM.

[functions]
          node_bundler = "esbuild"
          

You can find more information about how to make a fetch request using node-fetch v3 in an excellent guide by Tatyana Novell on the Netlify blog.

Next create a synchronous function on line 4. The exports.handler value is where Netlify expects to find the function, so I define it there. The basic syntax to create the function is provided below:

exports.handler = async function (event, context) {
          // your server-side functionality
          };
          

Next retrieve the email from the event value using JSON.parse:

const email = JSON.parse(event.body).payload.email
          

Then log the data in the console for debugging:

console.log(`Received a submission: ${email}`)
          

After retrieving the email address from the event value using JSON.parse, I’m ready to send it off my email marketing providers. I’ll use the node-fetch library I imported earlier to form the POST request.

I’ve outlined code examples for a few services below, but make sure you consult the API documentation from your email provider to make sure the API request is properly format.

ConvertKit Subscription Form

Using ConvertKit as an example, send a POST request to https://api.convertkit.com/v3/forms/<YOUR_FORM_ID/subscribe.

To find the form ID, navigate to Grow > Landing Pages & Forms, select the form you want to use, and copy the ID number from the url:

https://app.convertkit.com/forms/designers/<YOUR_FORM_ID>/edit

The body of the POST request contains the email token and the email address from the form submission:

const response = await fetch( 'https://api.convertkit.com/v3/forms/<YOUR_FORM_ID/subscribe', {
          method: 'POST',
          headers: {
          'Content-Type': 'application/json',
          },
          body: JSON.stringify({ 
          api_key: EMAIL_TOKEN,
          email: email
          }),
          });
          

Buttondown Subscription Form

Buttondown’s API sends the authorization in the headers rather than the body, so you’ll need to adapt the code slightly:

const response = await fetch( 'https://api.buttondown.email/v1/subscribers', {
          method: 'POST',
          headers: {
          Authorization: `Token ${EMAIL_TOKEN}`,
          'Content-Type': 'application/json',
          },
          body: JSON.stringify({ email }),
          });
          

SendStack Subscription Form

SendStack is a new privacy-first email service. Unlike Buttondown and ConvertKit, they offer API access on their free plan. There is currently a waiting list, but if you have access, you can try it out using the code below.

Add the email token to the headers and the email address to the body of the POST request:

const response = await fetch( 'https://getsendstack.com/api/subscribers', {
          method: 'POST',
          headers: {
          Authorization: `Bearer ${EMAIL_TOKEN}`,
          'Content-Type': 'application/json',
          },
          body: JSON.stringify({ email }),
          });
          

Then capture and log the response from the email service. We do this to diagnose any issues that happened. Netlify makes it easy to check your function’s logs, so use console.log often!

let responseText = await response.text();
          console.log('Response:', responseText);
          

Finally, redirect the form to a confirmation page that tells subscribers to check their emails to confirm their subscription. Use a simple return to redirect the browser to the new page:

return {
          statusCode: 302,
          headers: {
          'Location': '/confirmation/,
          },
          }
          

You can find the completed function below. In this case I used ConvertKit:

const { EMAIL_TOKEN } = process.env;
          import fetch from 'node-fetch';
          exports.handler = async (event, context) => {
          const email = JSON.parse(event.body).payload.email
          console.log(`Received a submission: ${email}`)
          const response = await fetch (
          'https://api.convertkit.com/v3/forms/{YOUR_FORM-ID}/subscribe', {
          method: 'POST',
          headers: {
          'Content-Type': 'application/json',
          },
          body: JSON.stringify({ 
          api_key: EMAIL_TOKEN,
          email: email
          }),
          }
          );
          let responseText = await response.text();
          console.log('response:', responseText);
          return {
          statusCode: 302,
          headers: {
          'Location': '/confirmation/',
          },
          }
          }
          

Create the email subscription form

Now that you’ve built the function, let’s call it from the email subscription form. The HTML for the email subscription form is very minimal.

All you need to do is call the function using the form action:

<form name="newsletter" method="POST" action="/.netlify/functions/subscribe-email">
          <label for="email">Your Email Address</label>
          <input type="email" name="email" placeholder=Email Address"/>
          <button type="submit">Subscribe</button>
          </form>
          

Make sure you specific input name (“email”) and make sure it matches the information you parse from the event value using JSON.parse.

If you used the submission-created trigger for your function like I did, you’ll need to change the <form> field slightly by adding data-netlify="true" to tell Netlify to process this form:

<form name="newsletter" method="POST" data-netlify="true">
          <label for="email">Your Email Address</label>
          <input type="email" name="email" placeholder=Email Address"/>
          <button type="submit">Subscribe</button>
          </form>
          

Deploy the function

Now that I’ve written my function, configured my netlify.toml file, and added my environment variables, everything is ready to go. Deploying is painless: just set up Netlify’s GitHub integration, and your function will be deployed when your project is pushed.

Conclusion

It took less than 50 lines of code to create my own email subscription form including custom HTML and a serverless function to add new emails to my list. I wrote it all in HTML, CSS, and JavaScript, and everything is served from my domain. Plus, my website visitors get a nice experience whether they have JavaScript enabled or not, and it will still serve even if they have advanced privacy protection enabled.

Why is Storytelling Important for B2B Marketing?

2022-06-22T00:00:00-07:00

Storytelling has been a buzzword in consumer marketing (B2C) for nearly a decade. And for a good reason. We, as humans, can’t help but tell stories. They are a critical way to convey information and build common ground.

Storytelling in B2C Marketing

When I think about storytelling in marketing, emotional, high-production ads from companies like Apple, Coca-Cola, REI, and Starbucks come to mind.

You’ve probably seen examples, especially around the Super Bowl or other significant events. For instance, in this 2015 advertisement, Apple uses Robin Williams’ speech from Dead Poets Society to sell the iPad Air.

I may not want to run out and buy an iPad right after watching this, but I do remember the ad. And I feel inspired to create something. That feeling is now associated with Apple and their products. The Apple advertisement is an excellent example of why B2C marketers rely on storytelling to build customer connections and trust.

Why Storytelling Matters for B2B Marketing

For a long time, B2B marketing has held out as a place filled with dry white papers and ebooks waiting behind lead generation forms.

But storytelling is even more critical for B2B (enterprise) marketing.

Unlike most B2C products, in B2B marketing, you are selling to groups of people who need to make a decision together. These diverse groups of individuals have unique needs and problems that need to be solved. In many cases, you may sell to stakeholders whose problems you don’t directly solve (typically C-suite leadership).

The only way to win a deal with so many people is by first uniting everyone around a common cause that turns their problems into a set of shared obstacles to overcome.

A successful story must resonate with everyone in the buying process and establish a higher-level mission to solve together.

Successful B2B marketing starts with a strategic narrative — why your company exists and what you help solve. One of my favorite examples is Microsoft’s new mission under CEO Satya Nadella: to empower every person and every organization on the planet to achieve more.

Microsoft can apply a simple story to consumer products and business tools. It can reframe whatever Microsoft sells around helping customers achieve a shared goal. That could include better healthcare outcomes, increasing student achievement, or building inclusive workplaces.

Takeaway

To summarize, storytelling is an essential component of B2B marketing because it is a powerful tool for persuasion that can help align groups of buyers around a shared narrative. With the right story, you can inspire confidence and build trust with your customers.

Let me know what you think on Twitter and LinkedIn.

How to Differentiate Your Product When You Aren’t (Really) Different

2022-06-21T00:00:00-07:00

Product differentiation communicates the unique qualities of your brand or product to distinguish it from your competition.

But what if your product isn’t unique?

Today plenty of products go to market without unique features. In the early days of B2B software, it was common to have features that no one else had in the market. Differentiation was reasonably straightforward. You would identify the unique benefit your feature provided for customers and craft a positioning statement around it.

In today’s technology landscape, differentiation with features is rare — everyone has similar functionality.

For example, you probably own a smartphone. Maybe you even own an Apple iPhone like more than 50% of U.S. consumers. But can you tell me the difference between the screen resolution on your iPhone versus a Samsung Galaxy? Are they even different?

Your opinion of that question is likely influenced by brand differentiation more than the unique qualities of either phone. Do you know how many pixels are in a Retina display? Or how that’s different than the screen on a Samsung phone?

It’s easier than ever for competitors to copy your product. But does that mean you shouldn’t build a great product? Nope.

It just means that a great product is table stakes.

Companies that are beating their competitors have a great product and build a unique market position.

Here’s how you differentiate your product from the competition:

Target a niche market segment
Tell a differentiated story
Provide valuable education
Build a community around your vision
Cultivate a partner ecosystem
Amplify employee advocacy

Each takes time to build. But don’t get intimidated—that’s the point. Your competition cannot easily duplicate your work.

Let’s explore how you can differentiate your product even when your products don’t have any unique features.

Target a niche market segment

The first mistake many companies make is targeting too large a market. When you’re trying to please everyone, you please no one.

Success starts by narrowing in on a niche in the market that isn’t being served well by current solutions. If you’re familiar with Geoffrey Moore’s book Crossing the Chasm, you might recognize this approach by another name – “land and expand.”

You may have to niche down a few times to find the right fit in the market, progressively narrowing in on a smaller and smaller customer niche each time.

But wait, you might ask, don’t I want a bigger audience?

Eventually, maybe you will. But not when you are struggling to gain traction with your first customers. The more specific and targeted you can be with your positioning and messaging, the more your product will resonate with your customers.

I think ConvertKit is an excellent example of the niche-down approach. When Nathan Barry started the company, he targeted anyone who needed email marketing. As a result, he was up against heavyweights like MailChimp, ActiveCampaign, and others. And he was failing to gain traction.

Instead of giving up, he narrowed his market to target professional bloggers and worked to address their problems. He gradually expanded to other digital creators as he gained traction with bloggers. Today the business operates at over $100,000 monthly recurring revenue (MRR).

Check out Nathan Barry’s Twitter threadc for more about his journey building ConvertKit.

Tell a differentiated story

When trying to differentiate your business, the most crucial question is not “what makes our product better than others?” Instead, it’s “why should customers care?”

The most successful businesses don’t just sell products; they tell stories and motivate customers to buy into their vision. Instead of discussing what features make your product so great, talk about why it matters. Great stories are never about your products or services. They are about how people use your products and services to improve their lives.

If you are a B2B company, tell the story about how your customers use your products or services uniquely. If you are B2C, tell the story of how consumers use your products or services to improve their lives.

Whatever story you tell, ensure it provides a unique point of view on the market you are targeting. For example, how do you understand the market? What is your unique take on how to address challenges within your space?

Drift is an excellent example of how this can work in practice. They offer chatbots for customer service. But instead of focusing on automation, they invented a new category for their product named “conversational marketing.” They worked to build leadership within that term and created a stronghold in the market despite competition from other vendors in the space.

Check out this HubSpot blog post with examples of 10 companies that brilliantly differentiated themselves from the competition.

Provide valuable education

Educate your audience about the trends and challenges you see in the market, how they can solve their problems, and how to get the most value from your product to solve those challenges.

The key is to help your customers. Whatever you create (blog, video, ebook, podcast, etc.) should help your customers learn something new. You can even take this further and provide certification or verification that they have learned a specific skill. For example, how to use your product (Microsoft Azure Fundamentals) or a particular set of skills (HubSpot Inbound Marketing).

My favorite example of education is Buffer, especially in its early days as a company around 2012–2016. Their blog consistently published valuable content about social media strategy and tactics. Then they shared it via newsletter and social media.

Personally, Buffer’s blog was invaluable when I was starting a career as a social media manager. At that time, there were no college programs or classes for digital marketing. And there weren’t that many other people who had much experience yet either. Nevertheless, we were all learning on the job. Buffer filled a gap by breaking down trends from their data and offering actionable tips daily.

Build a community around your vision

You need to do more than publish content on your blog. It would be best if you found ways to connect with potential customers one-on-one to understand their problems and how you can help.

One of the best ways to do this is by building a community around your vision. Find where your audience interacts online or in person and gradually join the conversation. If you’re already creating valuable educational content, it should be easy to chime in as questions arise. Eventually, you’ll want your audience to buy in and start sharing your vision.

Remember that a community can be centralized (Slack, Discord, Facebook Groups) or decentralized (conversations and hashtags on social media).

Different companies take different approaches depending on what they want to accomplish. For example, Nike, REI, and Starbucks have massive audiences online. As a result, they can rely on social media to amplify their brand messages and drive conversation around their brands. (The REI OptOutside campaign is a great example – people opt-in and interact around it every year.)

Other brands rely on bringing people together in a centralized space. For example, developer communities often organize around Slack or Discord as a place to discuss problems and share ideas – the VueJS community is a great example.

Cultivate a partner ecosystem

In addition to building a network with your customers, you should try to recruit partners who share your vision or philosophy. There are three main ways that partners can help differentiate your product:

1) Provide value-added services Partners function as an extension of your organization. By partnering with other companies, you can offer added value to your customers by leveraging their expertise. For example, your partners could provide anything from training and support to custom development and integration services. By providing additional services, partners can help your customers realize the full value of their investment in your product.

2) Provide product extensions and integrations Partners can provide extensions to your core product, adding new functionality and features that complement what you build. Integrations help customers build seamless workflows that address their specific use cases.

3) Generate co-sell opportunities In addition to extending functionality through integrations, partners can generate new sales opportunities by selling your product and theirs together as a bundle. Selling together is especially effective when the two products are complementary rather than competitive (e.g., CRM + marketing automation).

Once you start noticing how common partnerships are in the market, it’s hard to stop seeing them everywhere. One recent example I came across recently as a business owner was a bank – Novo. They help small business owners get started with business checking accounts.

Novo has built a partner ecosystem that helps new business owners get started faster. They offer discounts and integrations with critical partners like Quickbooks for invoicing, Stripe for collecting payments, and HubSpot as a CRM. New customers get access to these additional perks. By building a partner ecosystem, Novo helps drive business for their partners and helps keep customers invested in using Novo as their bank of choice.

Amplify employee advocacy

You automatically extend your reach when your employees advocate for your brand through their social ecosystem.

But more importantly, you can increase trust.

Customers often look to your employees as the best source of information about your company and products. According to research from Edelman, 68% of consumers say they trust technical experts from a company over the CEO or marketing material.

So why do customers trust employees?

They know more about your company and your products than anyone else
They know what your product can do – and what it can’t do
They know your competition and category and how you fit in
And most importantly: they know what matters to your customers

To succeed, you must first build a culture of trust and sharing. Unfortunately, most companies try to buy some software, implement it, and then give up when employees are less than enthusiastic about it.

A winning example, however, is Refine Labs.

The entire company is active on LinkedIn, sharing insights and commenting on posts about demand generation. Their success isn’t the result of fancy tools — the company’s CEO, Chris Walker, built advocacy into the culture through his leadership, hiring, and coaching of the team. It’s part of their core identity.

The result? A differentiated brand

The strategies above take time and a dedication to implement. That’s why they are so successful. Unfortunately, most companies fail to sustain the needed work to build a differentiated product and brand.

So now that you better understand how to differentiate your product, it’s time for action! If your product has no unique features, you can use the strategies above to differentiate your product and company from the competition.

And if you do have some unique features? Well, don’t stop promoting those just yet! You can still use these strategies to show off what makes your company special.

Let me know what you think on Twitter and LinkedIn. Thanks for reading!

Networking Tips for Remote and Hybrid Work

2022-05-25T00:00:00-07:00

You’ve finally landed that dream job — and it’s going to involve some (or a lot) of remote work. Maybe it’s your first job, or maybe you just took a position with a new company. Or, like the rest of the world, you and your team have transitioned to working remotely during the pandemic.

Regardless of the reason, you are now tasked with building relationships with co-workers you rarely see in person.

I had to onboard remotely twice during the pandemic. It was a much more challenging experience than starting in person. The first weeks can feel lonely, and it takes time to build the visibility and trust you need to drive projects forward.

That said, I love working remotely. And I’ve learned a few things along the way.

Here’s how you can network effectively in an era of remote and hybrid work:

Polish your LinkedIn profile
Schedule virtual coffee meettings
Engage with professional communities
Share what your learn

Polish your LinkedIn profile

Your LinkedIn profile isn’t just for finding a job — it’s also your first impression when meeting and networking with colleagues at your new company.

When I worked in person, I rarely checked my colleagues’ LinkedIn profiles. And why would I? We could chat at our desks or run into each other in the office.

After onboarding remotely twice during the pandemic, I can say with certainty that your LinkedIn profile matters more than even your resume. It’s the first place people look to understand who you are and what you’re about.

I use LinkedIn before scheduling meetings with people I haven’t met yet, or during meetings when I encounter someone new, so I can quickly identify their role and what might be important to them.

Here are some tips on how to optimize your LinkedIn profile:

Write an engaging introduction section that explains your career path, professional interests, and scope of responsibilities
Update your profile regularly so that it reflects your current role at the company, key successes and projects, and relevant skills
Make a great first impression with your LinkedIn headshot — it doesn’t need to be fancy but make sure your face is clearly visible

If you’re looking for more tips, I suggest browsing this comprehensive LinkedIn profile writing guide from the team at Jobscan.

Schedule virtual coffee meetings

When you first join a company, schedule 1:1 meetings with various stakeholders. I treat these like informal coffee chats and use them as an opportunity to learn about what people are working on, what their priorities are, and how I might work with them on shared goals.

Be proactive about introductions – don’t wait for others to introduce themselves. You should focus on meeting with your peers just as much, or maybe more, than meeting with different leaders.

Your goal here is to make sure that people know who you are and what your role is at the company. This helps build relationships early on so that when there are opportunities for collaboration or mentorship later down the road, there will already be a foundation of trust between you and other members of your team.

Don’t be afraid to ask questions and share ideas! Starting a new role is an exciting time to learn. And most people enjoy being consulted as experts in their areas and are willing to share what they know.

Once you’ve established a relationship with someone, it’s important to keep up the communication even when you aren’t working together. Connect over Slack or Teams by sharing interesting articles or news, checking in on how they are doing, or chatting about shared interests.

One of the best things you can do is recognize when someone else is doing something great. Send an email thanking them for their work and letting them know how much you appreciate what they did — especially if it wasn’t necessarily part of their job description. If you’re announcing a major event to your team via Slack or Teams, make sure to tag and thank them in the post.

Engage with professional communities

The rise of professional communities on Slack, Teams, Discord, and other platforms has created many opportunities to connect with other professionals.

Find out where your colleagues hang out online and join their communities. Personally, I use the Product Marketing Alliance (PMA) Slack group as a way to read about product marketing topics, ask questions, and connect with other professionals by answering questions when I can.

Seek opportunities to attend or present at conferences. These are great opportunities to meet other professionals face-to-face and share experiences. They can even be a great way to network with your team or other people at your company if you can attend as a group.

Even though I worked as a content marketer and social media manager for several years, I’ve always been a bit shy when it comes to writing on my blog or using my social media profiles.

After starting two remote roles, I now recognize the importance of creating and sharing valuable content in a remote and hybrid work environment. It’s a way to build reputation and network within your organization just as much as it’s a way to network outside your company.

Be active on social media platforms like LinkedIn or Twitter. Or even better, start a blog, publish a newsletter, or create videos. The goal is to get your voice out in public and get your ideas in front of your co-workers regularly.

Sharing what you learn in public is a great way to build your reputation and connect with people who might share some of your interests. The more people see your name associated with valuable content, the more likely they are to trust you as an expert and reach out when they have questions or need advice from someone with your background.

At first, don’t spend time worrying about having a unique angle, beat, or perspective. Just start and tweak as you go. If you’re not sure what to write about, try one of these prompts to get started:

Today I learned how to…
My favorite tools for X are…
I was thinking about…

The last prompt is actually how this post started. I was thinking about how to better network while onboarding into my new role and decided to write this blog post as a way of teaching myself the best way to get started.

Be patient

Finally, be patient with yourself (and with others). Starting a new job is exciting, and you want to get going right away. Building new relationships takes time, and it’s going to feel lonely at first. If you work remotely, you will have to be ok leading your learning, networking, and career building.

On the flip side, it is also empowering. Remote and hybrid work environments offer greater flexibility, work-life balance, and autonomy. I love taking a few minutes to grab a cup of coffee from my kitchen, pet my rabbits, and take in the view of my neighborhood rather than the concrete downtown streets before heading back to work.

Please let me know what you think on Twitter or LinkedIn. Thanks for reading!

How to Style an Atom Feed with XSLT

2022-01-24T00:00:00-08:00

Maybe it’s nostalgia for the early web, but I love web feeds as a tool for following and reading content. Feeds are privacy-first and put the reader in control: you can opt out any time, choose your tool for reading, and organize them in any way you want.

But the UX experience is terrible.

Web feeds are meant to be machine-readable, so most users follow a link to an RSS or Atom feed and end up looking at something like this:

This doesn’t have to be the case. RSS and Atom feeds can be human-readable with a little extra work. Here’s an example from my website. It’s simple and clean and provides some essential instructions on how to get started:

Let’s explore how to implement this with Atom and an XSLT stylesheet.

Why Atom, and not RSS?

Great question, and one I don’t intend to answer fully here given the vast amounts of writing on this topic already. In short, Atom is a better format.

Specifically, I wanted the following:

Support for a full content payload in the feed
Wide support across feed readers
Extensibility and future-proof format

First, create the feed in Jekyll

If you’re using a different tech stack to create your website, you can skip this section and jump ahead to the part about creating an XSLT stylesheet.

You can either use the excellent Jekyll Feed plugin, or create your own template using liquid tags and save it in your project as feed.xml.

I chose to create my own template, so I could incorporate some additional markup. You can see my version below:

---
          ---
          <?xml version="1.0" encoding="utf-8"?>
          <?xml-stylesheet href="/assets/css/feed.xsl" type="text/xsl"?>
          <feed xmlns="http://www.w3.org/2005/Atom">
          <title>{{ site.title }}</title>
          <link href="{{ site.url }}{{ site.baseurl }}/feed.xml" rel="self"/>
          <link href="{{ site.url }}{{ site.baseurl }}/" rel="alternate"/>
          <subtitle>{{ site.description }}</subtitle>
          <updated>{{ site.time | date_to_xmlschema }}</updated>
          <id>{{ site.url }}/</id>
          <author>
          <name>{{ site.author.name }}</name>
          <email>{{ site.author.email }}</email>
          </author>
          <rights type="text">Copyright © {{ site.time | date: "%Y" }} {{ site.author }}. All rights reserved.</rights>
          {% for post in site.posts %}
          <entry>
          <title>{{ post.title }}</title>
          <link rel="alternate" href="{{ site.url }}{{ post.url }}"/>
          <updated>{{ post.date | date_to_xmlschema }}</updated>
          <id>{{ site.url }}{{ site.baseurl }}{{ post.id }}</id>
          <summary>{{ post.description }}</summary>
          <content type="html">{{ post.content | xml_escape }}</content>
          </entry>
          {% endfor %}
          </feed>
          

Note on YAML Front Matter block: It’s important to leave the dashes at the top of the file. This is necessary because Jekyll will not process a page with Liquid unless there is a YAML block at the top of the file.

Enable auto-discovery: Make sure you add the appropriate meta tag to support automated discovery of your feed. Place the following code somewhere in your template’s <head> section to output the necessary metadata:

<link type="application/atom+xml" rel="alternate" href="{{ site.url }}/feed.xml" title="{{ site.title }}" />
          

Create the XSL file to style the feed

We can use XSLT to style our XML. This makes our feeds more human-readable while supporting bots, aggregators, and search engines.

You’ll notice some similarities to HTML and CSS in the example below, but with a few semantic changes and special attributes.

First, you can place your CSS in the <style> tag like normal. You can also use some standard HTML markup like the <body>, <section>, <p>, and <h1> tags.

There are a few special elements you can use, like <xsl:apply-templates> or <xsl:value-of>. I won’t cover these in detail during this tutorial, but W3Schools maintains a great XSLT reference if you want to learn about all these special elements.

This Github Gist shows an example of the XLST stylesheet I created for my website. I wrote some basic CSS styles to format it, but you could even tap into your site’s primary CSS file to keep the styling consistent.

Save your file as feed.xsl and add the tag below to your XML file. Make sure the href tag points to the correct location and file name for your website.

<?xml-stylesheet href="/feed.xsl" type="text/xsl"?>

Conclusion

With a little extra care and attention, we can improve the experience of using RSS and Atom feeds across the web. Now when you visit my feed, you are greeted with an explanation of how to get started and a formatted recap of my latest posts.

I made my own XML template and XSLT stylesheet based on the examples above. You can see it in action here or download a version to adapt for your website.

Thanks for reading!

Andrew Stiefel | guides

Building a Personal Monorepo for Writing

Why use a monorepo?

Basic Setup

Configuring Obsidian

Connecting Jekyll and Obsidian

Publishing with Netlify

Final Workflow

Bonus: Convert Backlinks to Weblinks

Additional Resources

How I Use GitHub as a CMS

Why?

Basic setup

Use issues to track posts

Writing and publishing posts

Final thoughts

Further Reading

Working with Multiple GitHub Accounts and SSH Keys

Organize your local directory

Set your global gitconfig file

Create gitconfig files for each directory

Configure the SSH agent

Reset your local repositories

Resources

Pocket Guide to Privacy-First Email Newsletter Software

Privacy-First Email Newsletter Services

Buttondown

SendStack

MailCoach

Conclusion

Build an Email Subscription Form with Netlify Functions

The Challenge: Build a Mailing List Sign Up Form

The Team: Jekyll, Netlify, and ConvertKit

Create the serverless function

ConvertKit Subscription Form

Buttondown Subscription Form

SendStack Subscription Form

Create the email subscription form

Deploy the function

Conclusion

Why is Storytelling Important for B2B Marketing?

Storytelling in B2C Marketing

Why Storytelling Matters for B2B Marketing

Takeaway

How to Differentiate Your Product When You Aren’t (Really) Different

Target a niche market segment

Tell a differentiated story

Provide valuable education

Build a community around your vision

Cultivate a partner ecosystem

Amplify employee advocacy

The result? A differentiated brand

Networking Tips for Remote and Hybrid Work

Polish your LinkedIn profile

Schedule virtual coffee meetings

Engage with professional communities

Share what you learn

Be patient

How to Style an Atom Feed with XSLT

Why Atom, and not RSS?

First, create the feed in Jekyll

Create the XSL file to style the feed

Conclusion

Additional Reading