Andrew Stiefel | writing

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.

Markdown Files, Not Apps

2025-01-17T00:00:00-08:00

Files, not apps. I’m convinced this is the best way to work in the future.

I write down almost everything important in my life: lists, ideas, plans, code, and articles. They form my extended memory. They are a record of what I’ve done, and who I’ve been. That’s why I only use markdown files.

Traditional document and note-taking apps like Word, Evernote, and Notion create data silos and vendor lock-in, limiting your ability to freely move and process information.

I discovered this the hard way when I tried to move between different ecosystems like Evernote and Apple Notes. Sure, there was a way to export my data. But it was a mess. Things broke, attachments went missing, and I spent hours converting, reformatting, and importing.

Markdown is simple

Markdown files solve these challenges through their fundamental simplicity. Any text editor can open and edit them, eliminating dependency on specific applications or platforms. They have all the basic formatting you need for headlines, bullets, lists, and even basic tables.

Markdown is portable

If you use Evernote or Notion, for example, you are helpless without them. If they go out of business you are trapped and have to move your files to another format. You will outlive those companies. I’ve already outlived a few note-taking companies.

I can work with markdown files on any device, forever. I can access them with any text editor I want. This makes them remarkably long-lived. Proprietary formats come and go, but markdown’s open, plain text nature ensures it will likely outlast me. This makes it the ideal format for building a personal knowledge base.

Markdown works offline

There are times when I want to be offline and unreachable, but would still like to jot ideas down in a format that is easily searchable. Working offline is an amazing productivity boost. Why give that up for an online database?

Markdown is ready for AI

This is a use case I wouldn’t have imagined a few years. But it’s the main reason I’m convinced markdown files are the future. Since markdown is just text, AI systems can easily process and analyze your notes.

For example, I can easily grab my “Ideal Customer Profile.md” file and throw it into ChatGPT, Claude, Gemini, or whatever I’m using at the moment to work with it. I can add my messaging framework, and immediately start brainstorming marketing copy.

I can run a local LLM, point it at a folder of my markdown files, and then interact with my notes by asking questions. It’s like a personal assistant built on everything I’ve learned and experienced.

Conclusion

Everything I write is human readable, and yet actionable with apps and tools. I always have my files available locally, and backups are just making a copy of the folder and putting it somewhere safe.

Markdown is simple, portable, independent, and free — exactly how I want to live.

Thoughts on Information Fidelity and Transmission

2023-08-25T00:00:00-07:00

There is a useful axiom to keep in mind whenever you are crafting a message for someone else, whether writing a book, filming a video, or drafting an email.

Simple ideas travel farther than complex ones

Most of us intuitively understand this. But sometimes we forget as we get into the details of whatever we are doing. That’s why I like to keep the idea of fidelity vs transmission in mind.

A book has hi-fidelity, but low transmission. You can read an author’s ideas in depth. Everything they wanted to tell you is there. But the full message — the text of the entire book itself — will practically never be remembered or transmitted, in detail, to the recipient. They may highlight the text, take notes, and summarize the text. But the full message will be lost.

In contrast, a social media post has lo-fidelity, but high transmission. The full idea is almost invariably reduced to its essential elements. Details are left out. Things become black and white. But the recipient might be able to remember the entire message, so it has high transmission.

This is why slogans are so powerful. They are easy to remember, and collect associations with other information you might have received or interacted with about a brand, politician, or idea. But they don’t have to communicate the whole thing – the recipient fills in the rest.

Why does this matter?

There is an inherent tension between fidelity and transmission in all communication. Too much information, and your audience won’t remember what you needed them to know. Too little, and the message becomes banal, or simply worthless.

There is an ethical element to navigate as well, especially when reporting or documenting someone else’s experience. Storytelling is reductive: it removes and flattens details in favor of creating an understandable narrative. The details you include or leave out will shape an audience’s understanding of the message you are communicating.

What does this look like in practice?

Practically, this is why most messaging frameworks provide multiple tiers:

Pillars — Simple, two or three word phrases
Key Message — Short, memorable statements
Proof Points — supporting statements, benefits, or other evidence

From here, you can expand into even higher fidelity forms like blog, videos, white papers, or books that expand and build on the summary provided by the messaging framework.

Closing Thoughts

We see the impact of this all the time. Stories go viral based on a bit of sensational news. But as the details come out, the original story turns out to be false. Bias and hate travels farther and faster than the nuance of compromise and collaboration.

As a writer, marketer, or anyone who works with words, how do you balance fidelity and transmission in your work?

Writing for Technical Audiences

2023-05-06T00:00:00-07:00

Whether you are marketing to software developers, scientists, academic audiences, or other specialized industries, writing is a tool that can serve you well.

But writing for technical audiences is a unique skill that requires a different set of techniques than copywriting for a consumer marketing campaign. You need not only an in-depth understanding of the subject but also the ability to convey complex information clearly and concisely.

The following tips can help you to communicate your ideas more effectively.

Know your audience

One of the tricky aspects of writing for technical audiences is knowing when to simplify something, and when to assume a level of advanced knowledge. Nothing drives developers, scientists, and other technical audiences away faster than overly simplified, 101-level writing. Occasionally, you do need 101-level content! But know what level of information your audience should already know.

For example, I often write about API technologies. In 101-level content, I might define that the acronym API stands for an application programming interface. But if I start an article for a technical audience by introducing “what is an API” and defining the acronym, they are likely to quit reading and look for a resource that is more aligned with their knowledge level.

Use clear language

When writing technical documents, it can be tempting to use complex technical jargon and terminology. However, this can often make your writing more difficult to understand, especially for those who are not familiar with the subject.

To avoid confusion, it is best to use simple, clear language that is easy to understand. This means avoiding overly technical terms and breaking down complex concepts into more digestible pieces. You should also summarize key ideas in bullet points, which can help reinforce your ideas and improve retention.

One of the most important first lessons I learned was to avoid adverbs whenever possible, especially in headlines. Adverbs typically make writing “feel like marketing” because they make broad claims (for example, “quickly, effortlessly, rapidly, always”).

Provide evidence

In technical writing, you should avoid making sweeping statements or generalizations. It is important to back up any claims you make with evidence. This could be in the form of data, statistics, or references to existing research. By providing evidence to support your arguments, you can add credibility to your writing and show that your ideas are based on solid research and analysis.

A brief word of caution: most technical audiences know what is a valuable resource, and what is marketing evidence. Use authoritative sources whenever possible, or commission relatively neutral third parties to conduct research on your behalf.

Give concrete examples

Whenever possible, show rather than tell your audience how your product works. It’s one thing to claim that something is easier. But it’s more impactful to show it in action. Rather than relying on abstract concepts or hypothetical scenarios, try to use real-world examples to illustrate your points. For example, if you are writing a user manual for a software application, you could include screenshots or step-by-step instructions to help users understand how to use the software.

Use visuals

Visual aids can be extremely helpful in technical writing, as they can help to clarify complex concepts and make your writing more engaging. This could include diagrams, charts, graphs, or illustrations. Visuals can be particularly effective when you are trying to explain a complex process or system, as they can provide a clear, easy-to-follow representation of the subject.

Incorporate storytelling

While technical writing is often associated with dry language, incorporating storytelling can make your writing more engaging and accessible. This could involve using anecdotes, case studies, or narratives to illustrate your points. Techniques like metaphors, extended analogies, and other techniques can be valuable ways to explain complex topics or frame a concept in a new way. By using storytelling, you can help your readers understand the subject on a deeper level.

Summary

Technical writing is an essential skill for anyone working in a complex field, or marketing to experts. By following these tips, you can ensure that your technical writing is clear, concise, and easy to understand, helping you to communicate your ideas more effectively to your intended audience.

A few parting questions to consider:

Are there any examples of technical writing that you particularly admire What made it stand out, and what lessons can be learned from its approach to technical writing?
What are some strategies for using visuals effectively in technical writing
Are there any tips you would add to the list above?

Additional Resources

How to Get Started with Technical Writing – tips for building your technical writing skills and portfolio
A Software Developer’s Guide to Technical Writing – useful tips for anyone interested in writing for software developers
Hemingway Editor – an excellent resource for sharpening your writing and removing those pesky adverbs

Thoughts on Open-Ended Writing

2023-03-03T00:00:00-08:00

Writing online, especially for a blog, can feel difficult. Especially for a (recovering) social media and content marketer like myself. Yes, it’s easy to make a blog. It seems like there are constantly new tools popping up promising to help you blog, build a newsletter, or post on social media.

But writing is a different matter. Today it seems like blogging is focused on producing capital “C” Content for consumption. Everything becomes an “ultimate guide to X,” even if you try to use slightly more tasteful titles. With the arrival of Chat-GPT and other AI tools, the world is faced with even more bland and repetitive capital “C” content as the “dark forest” of the web expands, to borrow a term from Yancey Strickler.

This isn’t inspiring. And it’s rarely enjoyable to write these types of articles.

Digital Gardening and Small b Blogging

When I started writing on this website (again), I wanted to treat it more like a digital garden. I’d like to expand my thoughts on digital gardening sometime, but I think Maggie Appleton has the best working definition for now:

“A garden is a collection of evolving ideas that aren’t strictly organised by their publication date. They’re inherently exploratory – notes are linked through contextual associations. They aren’t refined or complete - notes are published as half-finished thoughts that will grow and evolve over time. They’re less rigid, less performative, and less perfect than the personal websites we’re used to seeing.”

This approach resonates with me. Mainly because producing exhaustive articles is, well, exhausting. This definition of the digital garden is similar to the concept of “small b blogging” introduced by Tom Critchlow:

“Small b blogging is learning to write and think with the network. Small b blogging is writing content designed for small deliberate audiences and showing it to them. Small b blogging is deliberately chasing interesting ideas over pageviews and scale. An attempt at genuine connection vs the gloss and polish and mass market of most content marketing.”

I recently read another note by Tom Critchlow that was the direct inspiration for this line of thinking, entitled “Writing, Riffs, and Relationships.” There are lots of good concepts in the article, but the idea of making writing small stood out to me. In particular

“People’s first instinct with content is to try and make it polished and closed. To be useful by solving something or creating the ultimate guide to something. Those pieces of content can be good - but they’re very hard to write, and even harder to write well! Instead I prefer to take a more inquisitive and open-ended approach….”

And then:

“Closed writing is boring writing. If you’ve fully explored and put to bed the topic you’re writing about then there’s very little left for someone to react to. “Nice post” someone might say.

But if you deliberately leave some rough edges, some threads that the reader can pull on, then you’re inviting the reader into the conversation. You’re saying (possibly explicitly!) - “Hey, what are your thoughts on this topic? How do you think about it?”

Critchlow goes on to recommend ending a blog post or “riff” with more questions that encourage you (and your audience) to explore other topics. Altogether, this made me think about the difference between open-ended and closed writing and how they are different modes of writing altogether.

A Brief Definition of Open-Ended Writing

Open-ended writing seeks to connect ideas and identify new pathways of inquiry. It explores a topic by connecting sources and identifying tensions, conflicts, or missing information. Open-ended writing invites conversation and debate.

In practice, open-ended writing is defined by three basic activities: free writing, summarizing, and questioning:

Free writing introduces sources, ideas, and questions and starts to connect them together.
Summarizing organizes the information into a statement of what is known so far and what has been covered.
Questioning identifies tensions and gaps that could be explored further in the future or invites areas of conversation.

Some Spring Cleaning

I started this blog to write small, informal blog posts. So far I’ve fallen back into the trap of writing “articles” that don’t really encourage conversation or provide new threads to pull on. While it’s not critical for doing the actual writing, I decided to re-classify my digital garden to encourage myself to focus more on riffs and notes.

Previously, I had two categories: Notes and Essays. Notes were supposed to be objective and focused on single topics; essays would pull together multiple notes to present a specific point of view. Obviously, neither category encouraged exploratory writing. I generally wrote less and focused on polishing my notes, which were supposed to be the rough form of writing. I seldom got around to writing essays.

I now have my digital garden organized into three categories:

Notes– Open-ended, exploratory riffs that connect 2-3 ideas or sources together. These are the heart of the digital garden.
Articles – Closed writing that thoroughly explores a single topic from a mostly objective point of view.
Essays – Utilizes either open-ended or closed writing to explore a single subject from a personal point of view.

How do you practice open-ended writing?

This particular post might be my first true note. It’s not meant to be comprehensive and it’s mostly my attempt to work out (in public) an approach to open-ended writing.

What do you find hard or challenging about writing?
Does changing the purpose to open-ended writing encourage you to write more? Or does it scare you?
Do you use a public platform or a private one? Is one better than the other, or are they just different?

Just Start

2022-06-28T00:00:00-07:00

How long have you been working on a project with nothing to show?

I am an expert procrastinator. I spent three years building, tearing down, and restarting this blog. The colors were never right, I didn’t like the font, I needed just one more feature to be ready.

Finally, I decided to slim down to just what I need to write. The rest could come later. For now It’s minimal, but it’s all I needed to start.

Today you can publish your writing in less than five minutes. Start with tools like:

The list is endless. So what are you waiting for?

Start writing
Get feedback
Refine your work
Try again

One of the biggest misconceptions about writing or creating anything is that you should start with a strategy: “I’m going to write about X for people interested in Y.”

But here’s the truth: you don’t need a plan to start.

Write about whatever interests you. You’ll eventually find what you enjoy writing about the most and what resonates most with your audience.

You just have to start.

Here are three formats to get started:

Today I learned how to…
Did you read or hear about X? Here’s my reaction…
Someone asked me about X, so here is the answer

Keep a notebook with all the questions people ask you for help with. Write up your answers and publish them.

Eventually you’ll hit your stride — and you’ll probably discover an idea you could never have found while planning your strategy, picking brand colors, and brainstorming topics for your blog.

Start today.

Andrew Stiefel | writing

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

Markdown Files, Not Apps

Markdown is simple

Markdown is portable

Markdown works offline

Markdown is ready for AI

Conclusion

Thoughts on Information Fidelity and Transmission

Why does this matter?

What does this look like in practice?

Closing Thoughts

Writing for Technical Audiences

Know your audience

Use clear language

Provide evidence

Give concrete examples

Use visuals

Incorporate storytelling

Summary

Additional Resources

Thoughts on Open-Ended Writing

Digital Gardening and Small b Blogging

A Brief Definition of Open-Ended Writing

Some Spring Cleaning

How do you practice open-ended writing?

Just Start