↩ Back to Comfort Levels

Welcome to the Beginner’s Guide to Making a Blog. Of the free ways to make a blog that require minimal setup and technical knowledge, this is the way that gives you the most control and sovereignty over your content and data.

This guide works on macOS, Windows, and Linux. Where keyboard shortcuts differ, all are listed: macOS / Windows \& Linux.

Before We Start: Terminology

The tech world loves jargon. Here is what the words actually mean—read this now, refer back when you hit a term you do not recognize.

• Vault: A folder on your computer where Obsidian keeps your notes.
• Repository (“Repo”): A storage locker on GitHub for your files. It tracks changes and lets other services read them.
• Host / Hosting: A service that stores your website files and serves them to visitors.
• Deployment: The act of taking your files and turning them into a live website.
• Token: A secret password that lets one service talk to another on your behalf.
• DNS / Domain: DNS is the internet’s phonebook. It turns yourname.com into the actual address where your site lives.
• Plugin: An add-on that gives Obsidian extra features.
• Markdown: A simple way to format text using symbols like **bold** and [links](url).
• Command Palette: A search box in Obsidian that lets you run commands quickly.
• Frontmatter / Metadata: Hidden settings at the top of a note that tell the system how to treat that note.
• Sidebar / Filetree: A navigation panel showing all your published notes.
• Commit / Push: Saving your changes to GitHub and sending them there.

Prerequisites

To get your garden online, you need a few accounts and one piece of software. All of these have free tiers; you should not have to pay a cent to complete this guide.

1. The Essentials (Required)

• GitHub Account: github.com — This is where your garden’s “skeleton” lives. It is the bridge between your computer and the internet.

  • Why: GitHub stores your blog’s template and all your published notes. Vercel reads from GitHub to build your site.
  • What to do: Go to github.com, click “Sign up”, and follow the prompts. Use an email you actually check—you will need to verify it.
  • Common mistake: Creating the account but not verifying your email. GitHub will nag you, and some features will not work until you do.

• Vercel Account: vercel.com — This is your host. It takes your GitHub files and turns them into a website people can actually visit.

  • Why: GitHub does not serve websites to the public on its own. Vercel watches your repo and automatically builds and hosts your site every time you publish.
  • What to do: Go to vercel.com and click “Sign up”. Select “Continue with GitHub”—this links the two accounts instantly and saves you configuration later.
  • Common mistake: Signing up with email instead of GitHub. It still works, but you will have to manually connect them later.

• Obsidian: obsidian.md — Your writing tool. It is a local app, meaning your notes stay on your computer, not in some company’s cloud.

  • Why: You need a place to write your notes before publishing them. Obsidian is free for personal use, works offline, and the Digital Garden plugin is built for it.
  • What to do: Download the installer for your operating system and run it. On macOS, you may need to right-click the app and select “Open” the first time because it is not from the App Store.
  • Common mistake: Trying to use the web version of Obsidian. The Digital Garden plugin only works with the desktop app.

2. The Bridge (Plugin)

• Digital Garden Plugin: Once Obsidian is installed, you will need the Digital Garden plugin. This is the tool that tells Obsidian: “Take this specific note and send it to the web.”
  • Why: Obsidian does not know how to publish to the internet on its own. This plugin adds that ability by talking to GitHub for you.
  • What to do: Instructions are in Step 2 of the Setup Process below.

3. Optional: Your Own Address (Custom Domain) By default, Vercel gives you a free address (e.g., my-garden.vercel.app). If you want a professional address (e.g., yourname.com), you will need a Domain Registrar.

• Recommended: Porkbun or Cloudflare.
• Cost: Usually \$10–\$20/year.
• Note: You can skip this for now and add a domain later once you are comfortable. Your blog works perfectly fine without one.

Setup Process

Now that you have your accounts and software, let us link them together. Each step below explains what you are doing, why you are doing it, and what success looks like. If something does not match the “success” description, stop and double-check.

Step 1: Create Your Garden (Obsidian)

This step creates a folder—called a “vault”—that Obsidian will manage. All your blog posts will live here, and the Digital Garden plugin reads from this vault to find notes to publish.

Instructions:

1. Open Obsidian.
2. You should see a welcome screen. Click “Create new vault” (or “New vault” depending on your version).
3. Name your vault (e.g., “My Digital Garden”) and choose a folder on your computer where you want your notes to live.
   • Tip: Pick a location you will remember, like your Documents folder. Do not put it in a cloud-synced folder like Dropbox or iCloud unless you know what you are doing—it can cause conflicts.
4. Click Create.
5. You are now inside your vault. Create your first note:
   • Click the “New Note” button (page icon with a +) or press ⌘ + N on macOS / Ctrl + N on Windows \& Linux.
   • Name it Hello World.
   • Type a few sentences about why you are starting a blog. This is just practice—you will change it later.
   • Press ⌘ + S on macOS / Ctrl + S on Windows \& Linux to save (though Obsidian auto-saves, manual saving is a good habit).

You should now see a note titled “Hello World” in Obsidian with your text in it, and it should appear in the left sidebar file list. If it is not there, check that you saved to the right location. Creating the vault inside a cloud-synced folder like Google Drive or Dropbox can cause the Digital Garden plugin to get confused about which version of a file is correct.

Step 2: Install the Digital Garden Plugin

Obsidian by itself only saves notes to your computer. The plugin is what actually sends them to GitHub and then to the web.

Instructions:

1. In Obsidian, look at the bottom-left corner. Click the Settings gear icon.
2. In the left sidebar of the Settings window, scroll down and click “Community Plugins”.
3. You will see a message saying community plugins are disabled. Click “Turn on community plugins”.
   • Note: Obsidian limits what unofficial plugins can do until you explicitly allow them. This is a security feature.
4. Click “Browse” (the button with a magnifying glass).
5. In the search box, type “Digital Garden”.
6. You should see “Digital Garden” by Ole Eskild Steensen. Click “Install”.
7. After it installs, the button changes to “Enable”. Click that too.
8. Close the Settings window.

You should see “Digital Garden” listed under “Installed Plugins” with a blue toggle that is turned on. If you look at the left sidebar of Obsidian, you may see a new icon (a small garden or plant symbol)—that is the Digital Garden panel. If the toggle is gray, you forgot to click Enable. The plugin is not active until that toggle is blue.

Step 3: The “Magic” Connection (GitHub \& Vercel)

You do not need to build a website from scratch. The template has all the code. You just need your own copy—called a “fork”—so you can modify it, and Vercel reads your copy to build the site.

Instructions:

1. Open this link in your browser: github.com/oleeskild/digitalgarden.
   • What this is: The template repository created by the same person who made the Digital Garden plugin. It contains the code that turns your markdown notes into a website.
2. Scroll down to the README (the main page content). Look for a button that says “Deploy” or “Deploy with Vercel”. It is usually near the top.
3. Click that button. You will be taken to Vercel.
4. On the Vercel page, under “Git Providers,” select “GitHub” (not GitLab or Bitbucket).
5. If you are not already logged into Vercel with GitHub, click “Add GitHub Account” and authorize Vercel to access your GitHub.
   • What is happening: Vercel is asking permission to read your GitHub repos so it can watch for changes and rebuild your site.
   • Privacy note: Vercel only gets access to the repos you specifically allow. It cannot read private repos unless you give permission.
6. Vercel will ask you to name your new repository. Call it something like my-blog or digital-garden.
   • Remember the name: This is how you will find it on GitHub later. Keep it simple and memorable.
7. Click “Create” or “Deploy”.
8. Wait. Vercel is copying the template to your GitHub account, then building your website. This usually takes 1–2 minutes.
   • What happened? Vercel created a new repo in your GitHub account, copied the template files into it, ran a build process, and put the result on a web server.
9. When it finishes, you will see a “Congratulations!” screen with a “Visit Deployment” button.
10. Click “Visit Deployment.” You should see a generic Digital Garden welcome page.

You should now see a website at a URL like my-blog-12345.vercel.app (the exact name varies). The site has a header that says “Digital Garden” and some placeholder text. This means the template is working.

If it fails:

• “Authentication failed” when connecting GitHub: You probably did not verify your GitHub email. Go to GitHub → Settings → Emails and verify.
• “Repository already exists”: You already have a repo with that name. Pick a different name or delete the old one on GitHub first.
• The “Deploy” button does nothing: Some browsers block pop-ups. Check if a new tab was blocked and allow it.
• The site shows an error instead of the welcome page: Wait 30 seconds and refresh. Sometimes Vercel is still finishing the build. If it is still broken after 2 minutes, the template may have updated and broken something—contact me (link at the bottom of this guide).

Save this URL somewhere. You will need it in Step 6. You can also always find it by going to vercel.com/dashboard, clicking your project, and looking under “Domains.”

Step 4: Linking Obsidian to your Site

The plugin needs to log into GitHub as you. It does this using a “token”—a special password that only works for specific tasks. This is safer than giving the plugin your actual GitHub password.

Instructions:

Part A: Create a GitHub Token

1. Open this link in your browser: github.com/settings/personal-access-tokens/new.
   • What this page is: GitHub’s tool for creating limited-access passwords for apps and scripts.
2. You will see a form. Fill it out as follows:
   • Token name: Type Digital Garden (or whatever you want—the name is just for your reference).
   • Description: Optional, but helpful. Something like “Allows Obsidian to publish my blog notes.”
   • Expiration: Select “No expiration” from the dropdown.
     • Why no expiration: If you set an expiration date, your blog will mysteriously stop publishing when the date hits, and you will have to generate a new token. Most people forget why it broke.
   • Repository access: Select “Only select repositories” (not “All repositories”).
     • Why only select: This limits the token to just your blog repo. If the token ever leaks, it cannot touch your other projects.
   • Select repositories: Click the dropdown and choose the repository you created in Step 3 (e.g., my-blog).
   • Permissions: Click “Add permissions” or look for the “Permissions” section.
     • Find “Contents” and set it to “Read and write.”
     • Find “Pull Requests” and set it to “Read and write.”
     • Why these permissions: “Contents” lets the plugin add your notes to the repo. “Pull requests” lets it manage how those changes are submitted.
3. Scroll down and click “Generate token” (or “Create token”).
4. On the next page, you will see a long string of letters and numbers—this is your token.
   • IMPORTANT: Copy this token right now. Paste it into a temporary text file on your computer if needed.
   • Why: GitHub will never show you this token again. If you lose it, you have to make a new one. It is not the end of the world, but it is annoying.

Part B: Configure the Digital Garden Plugin

5. Go back to Obsidian.
6. Open Settings (gear icon in the bottom-left corner).
7. In the left sidebar, scroll down and click “Digital Garden” under “Community Plugins.”
8. You will see several fields. Fill them in:
   • GitHub Repo Name: Type the exact name of the repository you created in Step 3 (e.g., my-blog).
     • Tip: This is case-sensitive. If you named it My-Blog, type My-Blog, not my-blog.
   • GitHub Username: Type your GitHub username (the one you log in with, not your display name).
     • How to find it: Go to github.com and look at the URL when you are on your profile page. It is the part after github.com/.
   • GitHub Token: Paste the long token you copied in Part A.
9. Close the Settings window completely (click the X or press Escape).
10. Reopen Settings and go back to Digital Garden.
    • Why the close-and-reopen: The plugin sometimes needs a fresh load to test the connection. This is a quirk of how Obsidian handles plugin settings.

After reopening settings, the Digital Garden section should say “Connected with full access” (in green or similar positive indicator) and “Your site template is up to date!”

If it does NOT say “Connected with full access”:

• Close and reopen Settings one more time. Sometimes it takes two tries.
• If it still fails, check:
  1. Did you copy the entire token? It is long—make sure you got it all.
  2. Is your repo name spelled exactly right, including capitalization?
  3. Is your GitHub username correct? Not your display name—your actual login username.
  4. Did you select the correct repository when creating the token?
  5. Did you give the token “Read and write” permissions for both “Contents” and “Pull requests”?
• If all of the above are correct and it still fails, regenerate the token (go back to GitHub, revoke the old one, make a new one) and try again.

Step 5: Publishing Your First Note

The plugin does not publish everything automatically. You choose what goes live. The “home page” is the first thing visitors see when they visit your site.

Instructions:

1. In Obsidian, open your Hello World note (click it in the left sidebar).
2. Open the Command Palette:
   • Press ⌘ + P on macOS / Ctrl + P on Windows \& Linux.
   • What the Command Palette is: A search box that lets you run any command in Obsidian without hunting through menus.
3. Type Digital Garden.
   • You will see a list of Digital Garden commands. Do not worry about the others for now.
4. Click “Digital Garden: Set as Garden Home Page” (or select it with arrow keys and press Enter).
   • What this does: It adds two invisible flags to your note: dg-home: true (marks it as the homepage) and dg-publish: true (marks it for publishing). You can see these if you switch to “Source mode” or look at the note’s metadata, but you do not need to manually edit them.
5. Open the Command Palette again (⌘ + P / Ctrl + P).
6. Type Digital Garden again.
7. Click “Digital Garden: Publish All Notes Marked for Publish.”
   • What this does: The plugin sends your note to GitHub, which triggers Vercel to rebuild your site with the new content.
   • How long it takes: Usually 10–30 seconds. The plugin will show a notification saying “Successfully published 1 note” or similar.

You should see a notification in Obsidian saying your note was published successfully. If you open the note and look at the top (in Source mode), you see dg-home: true and dg-publish: true.

If publishing fails:

• “Failed to publish” or “Unauthorized”: Your token is wrong, expired, or missing permissions. Go back to Step 4 and verify.
• “Repository not found”: Your repo name or username in the plugin settings is incorrect.
• “Network error”: Your internet connection dropped. Try again.
• The note does not appear on the site: Wait 30 seconds and refresh your Vercel URL. Vercel sometimes takes a moment to rebuild.

Step 6: The Moment of Truth

This is the reality check. If you see your note, the entire chain—Obsidian → plugin → GitHub → Vercel → website—is working.

Instructions:

1. Open your web browser.
2. Navigate to the Vercel URL from Step 3.
   • If you forgot it: Go to vercel.com/dashboard, find your project, and look under “Domains” or “Production Deployment.”
3. You should now see your Hello World note instead of the generic Digital Garden placeholder!

Your note’s title and content should appear on a webpage. The URL is something like my-blog-12345.vercel.app. There may be a header saying “Digital Garden”—that is the template branding, which you can change later.

If it is not there:

1. Refresh the page. Sometimes browsers cache the old version.
2. Wait 1 minute. Vercel builds can take a moment, especially the first time.
3. Check your note in Obsidian. Does it have dg-publish: true? (Open the Command Palette, search “Digital Garden: Add publish flag” if you are unsure.)
4. Check your Vercel dashboard. Go to vercel.com/dashboard, click your project, click “Deployments.” Is there a recent deployment? If it shows a red X, click it to see the error.
5. If none of the above works, you—yes, you—can reach out to me for help. My contact information is on my about page, or you can click the email icon at the bottom of every page.

Making It a Blog

Right now you have one page. That is not a blog, that is a business card. To make it a blog, you need multiple posts, links between them, and a way to browse them.

Making New Posts

A blog with one post is not very interesting. Each new note becomes a new page on your site.

Instructions:

1. In Obsidian, create a new note:
   • Click the “New Note” icon (page with +) or press ⌘ + N on macOS / Ctrl + N on Windows \& Linux.
2. Name it. My Second Post works for now.
3. Write something. Anything. It does not matter what—you are just practicing.
4. Save it (⌘ + S / Ctrl + S).
5. Mark it for publishing:
   • Open the Command Palette (⌘ + P / Ctrl + P).
   • Search for Digital Garden: Add publish flag and select it.
   • What this does: Adds dg-publish: true to the note’s metadata. Unlike the home page command, this does NOT set dg-home—you only have one home page.
6. Publish it:
   • Open the Command Palette again (⌘ + P / Ctrl + P).
   • Search for Digital Garden: Publish All Notes Marked for Publish and select it.
7. Wait for the “success” notification.
8. Refresh your website. Your new post is now live at your-site.vercel.app/My%20Second%20Post.

You should be able to visit your Vercel URL, append /My%20Second%20Post to the end, and see your new note. If you publish and nothing new appears, check that the note has dg-publish: true in its metadata—forgetting the publish flag is the most common mistake here.

Linking Notes Together

This is what makes a digital garden a garden instead of a pile of isolated pages. Links help readers (and you) discover related ideas.

Instructions: In Obsidian, type double square brackets to link to another note:

[[My Second Post]]

When you type [[, Obsidian shows a dropdown list of all your notes. This is autocomplete—press Enter or click the note you want.

For different display text (the clickable words the reader sees), add a pipe:

[[My Second Post|click here to read more]]

To edit a link after creating it, click inside the brackets and add the pipe and text.

Rules:

• The linked note must also be published (dg-publish: true). If you link to an unpublished note, the link will be broken on your website.
• Do not worry about file paths or folders. Just use the note name. The Digital Garden plugin handles the rest.
• To link to a specific section within a note, add # and the heading name:
  [[My Second Post#Conclusion]]

On your live website, the link appears as blue, clickable text. Clicking it takes you to the linked note. If the link is broken, check two things: did you publish the linked note (look for dg-publish: true), and did you spell the note name exactly right in the link? Obsidian’s autocomplete helps prevent typos, but manual edits can introduce them.

Enabling the Sidebar

By default, visitors can only get around by clicking links in your notes. The sidebar gives them a browsable table of contents.

Instructions:

1. In Obsidian, open Settings (gear icon → scroll down to Community plugins → click Digital Garden).
2. Click “Manage note settings” (or “Note settings” depending on version).
3. Find “Show filetree sidebar” and toggle it on.
4. Click “Save” or close the settings.

When you visit your website, you should see a sidebar (usually on the left) listing your published notes. The sidebar mirrors your Obsidian vault’s folder structure, so create folders in your vault (right-click in the file list → “New Folder”) and move notes into them to organize it. Only published notes appear—private notes stay hidden. If you expect unpublished notes to show up, they will not. Only notes with dg-publish: true appear in the sidebar.

Customization

The default settings work, but they look generic. Changing the sitename makes it yours.

Instructions:

1. In Obsidian, open Settings → Digital Garden → “Manage appearance” (or “Appearance”).
2. Change the “Sitename” to whatever you want your blog to be called.
3. Explore other settings if you want—colors, fonts, etc.
4. After making changes, publish any note (or republish an existing one) to trigger Vercel to rebuild with the new settings.

Your website should now show your chosen sitename in the header instead of “Digital Garden.”

Optional: Get a Custom Domain

By default, you get your-garden.vercel.app. That works. If you want yourname.com:

Custom domains look more professional and are easier to remember and share.

• Recommended registrars: Porkbun or Cloudflare.
  • Why these: They are cheap, do not upsell you nonsense, and respect your privacy.
• Cost: Usually \$10–\$20/year, depending on the domain extension (.com, .net, etc.).
• How:
  1. Buy the domain at your chosen registrar.
  2. Go to your Vercel project settings.
  3. Click “Domains” and add your custom domain.
  4. Vercel will give you DNS records to add at your registrar. This is usually copy-pasting a few values.
  5. Vercel has a guide for this if you get stuck.
• Note: Skip this for now if you want. Your content is not going anywhere. You can always add a domain later without breaking anything.

If your domain shows an error page after 24 hours, you probably did not configure the DNS records correctly. Double-check the DNS settings at your registrar.

Going Forward

That is it. You have a blog. Here is the workflow from now on:

1. Open Obsidian.
2. Write a note.
3. Add the publish flag with the Digital Garden plugin (Digital Garden: Add publish flag in the Command Palette).
4. Publish it (Digital Garden: Publish All Notes Marked for Publish in the Command Palette).
5. That is it. There is no step 5.

Some notes for the road:

• You do not have to publish everything. Only notes with dg-publish: true go live. Everything else stays private on your computer.
• You can unpublish. Changed your mind? Open the note, use the Command Palette, and select Digital Garden: Remove publish flag. Then publish again.
• You can edit published notes. Just change the text in Obsidian and publish again. Vercel will update the live site within seconds.
• Back up your vault. Your notes live on your computer. If your machine dies, your notes die with it. Back up to an external drive, another computer, or a cloud sync service. Just do not lose your work.
  • Tip: The Digital Garden plugin already copies published notes to GitHub, so your published posts are backed up there. But unpublished notes are only on your machine.
• If your token stops working (publishing fails with “Unauthorized” or “Failed to publish”):
  1. Go to GitHub token settings.
  2. Find your Digital Garden token and revoke it.
  3. Go back to Step 4 in this guide and create a new token.
  4. Update the token in Obsidian’s Digital Garden settings.

This is your garden. It is small, it is simple, and it is yours. When you are ready to own the land instead of renting it, come back for the intermediate guide.

Welcome to the club. Now go write something.

Quick Reference

Important Links

• Redeploy the Template Site
• Vercel Dashboard
• Digital Garden Plugin Documentation
• GitHub Token Settings
• GitHub New Fine-grained Personal Access Token