Reminder: Free software isn't free. Support Ole, the Digital Garden developer: Buy Ole Eskild Steensen a Coffee - oleeskild - Ko-fi

Table of Contents

• How to ask for Help !! Start here !!
• Initial Steps - Digital Garden Isn't Deploying
  • 01. Verify that your pages in Obsidian have the correct properties
  • 02. Check your GitHub Repo to make sure its populating
  • 03. Check the build and Gather Logs
• Common Problems
  • Filetree disappears when you click a folder
  • You see a bunch of Failed deployments in Cloudflare to "Filetree"
  • Obsidian Properties Passthrough and Nunjucks Scripts
  • Manually updating packages for your Digital Garden broke something

How to ask for Help

If you have gone through the steps below and you're still having trouble, then reach out on the Digital Garden Discord Help Channel with the following information:

1. A link to your GitHub repo (if it's public)
2. A link to your site
3. Screenshots or copies of any logs you're seeing

This information makes it much easier to troubleshoot the problem and get you up and running!

Initial steps - Digital Garden Isn't Deploying

Below are steps you should take BEFORE asking for help. Following this guide will get your site up and running faster, and if you need help, will get you better help sooner.

01. Verify that your pages in Obsidian have the correct properties

Only one page should have the property dg-home checked, and it also must have the dg-publish property checked. You can add these properties a couple of ways:

1. Open the Obsidian Command Palette, search for Digital Garden, and select the "Digital Garden: Add publish flag" command.
   
   If you do not have a dg-home property set, you can manually change dg-publish to dg-home and then add another publish flag to the sheet.

2. Manually add the properties

   1. Select the three-dot menu at the top-left of your note, and click "Add file property..."
      1. 
   2. Select any of the properties listed, though I recommend Alias
      1. You can also just begin typing the name of the property and skip this stype
      2. 
   3. Rename the property to dg-home or dg-publish
      1. 
   4. Select the icon to the left of the name, and change the "Property Type" to Checkbox
      1. 
   5. Check the box to enable the property, uncheck the box to disable it.
      1. 
      2. With this configuration, the note is set as the home page, but will not be published to the Digital Garden, and will result in a misconfiguration.
      3. Both dg-home and dg-publish need to be checked on the homepage.

Again, go through your pages and make sure only one page is set with dg-home, and every page you want published is marked with dg-publish

If you made any changes, publish publish your homepage using the Command Palette or the Digital Garden Publication Center and check your site.

NOTE: We only want to publish your homepage because each note counts as a deployment, and if you have a lot of pages, you might run out of deployments on your host before your site is even live.

If your site doesn't update, or your pages are marked correctly, proceed to the next step.

02. Check your GitHub Repo to make sure its populating

Log into your GitHub account, open your repository, and check src/site/notes to see if it's populated with any of your notes.

If it's not populated, it means GitHub is not receiving your notes, and this is likely caused by a fine-grained token misconfiguration, so let's just rebuild it from scratch.

NOTE: Even if you see a green checkmark in the Digital Garden plugin in Obsidian, that only checks if the token is legitimate, not that it has the correct permissions.

WARNING: The tokens are only visible immediately after creation or regeneration, and if you do not copy/paste it before you navigate away from the page, you will have to regenerate it.
This is not the end of the world, just a douleurs dans le cul, as Google Translate tells me the French say

Here's Ole's guide on creating a token from his site, but let's go through each step below.

1. Go to this page to configure the token.
   1. You can also manually navigate there by selecting your Profile icon at the top right, then Settings, then Developer Settings at the bottom of the left column, expand Personal access tokens, and then select Fine-grained tokens, and click Generate new token
2. Enter the following information:
   1. Token name
      1. This is for your reference, and must be unique among your tokens
   2. Expiration date
      1. Default is 30 days, drop-down menu allows you to select up to 90, but you can manually configure up to 1 year
   3. Description
      1. Again, up to you
   4. Repository Access
      1. Click the radio button for "Only select repositories" and choose your Digital Garden repository
3. Expand Repository permissions and configure the following permissions
   1. Contents
      1. Read and write
   2. Pull Requests
      1. Read and write
   3. NOTE: "Metadata" will automatically change to "Read-only", and this is correct and good.
4. Click Generate token
   1. Immediately copy and paste this token into the Digital Garden plugin in Obsidian, before navigating away from the page.

Once the new token has been added, publish your homepage using the Command Palette or the Digital Garden Publication Center and check your site.

If your site doesn't update, but you are seeing your notes in GitHub, proceed to the next step.

03. Check the build and Gather Logs

Will add details later, but for now, check these three things:

1. You are publishing to the "Main" branch by default
   1. Changing the default branch - GitHub Docs
   2. 
2. In GitHub, got to the Actions tab and look for Errors
   1. 
   2. 
   3. 
      1. If you see errors like this one, it means there are duplicate files in your repo or two pages marked with dg-home.
3. Host (Vercel, Cloudflare, etc.) logs
   1. These logs will look similar to the ones in GitHub.
   2. Vercel
   3. Cloudflare Pages

11ty error troubleshooting

If you're getting an 11ty error during the build you may have 2 or more files with dg-home set to true or two pages with duplicate names/links.

The first 5 or so lines of the 11ty output contain the information you want.

Sample Log; Duplicate Files

In this case, I have a problem with the file "Do I have ADHD?" which was originally uploaded from a Windows machine (which does not allow a ? in the file name) and then a Linux machine, which has no problem with question marks in file names.

DG formatted their URLs the same way, and there was a build error.

Depending on the issue, you may need to delete the file. If the issue is a syntax problem (like above) and you did a "Publish All" command, then the problem will solve itself when it deletes the (now missing) file and rebuilds the site.

Sample Log; Multiple Homepages

As an example, I set two pages to have the dg-home page checked; it references dist/index.html in the second line, indicating two or more files writing to dist/index.html, which is the home page.

While the log tells you which files are being problematic (in this case, "S16 - We Got Milk" and "Fake Character"), you can also use a Dataview table to find and review all published files.

Create a Dataview codeblock and copy/paste the code below into it. This will generate a full list of all published pages with any page that has a configured dg-home home attribute at the top, and then is sorted by file name (which can help to identify duplicate files with slight name differences).

TABLE dg-home, dg-publish
WHERE dg-home=true OR dg-publish=true
SORT dg-home DESCENDING, file.name

Common Problems

Filetree disappears when you click a folder

This happens because a folder name has an illegal character in it, most likely an apostrophe. The offending folder will likely also be fully expanded.

Remove any special characters from folder names, republish the site, and work forward from there.

You see a bunch of Failed deployments in Cloudflare to "Filetree"

1. This probably only happened if you included the branches from the template
2. Make sure the Main branch is set as "Default" in GitHub

Obsidian Properties Passthrough and Nunjucks Scripts

Scenario: You are trying display multiple Aliases (or other Obsidian Properties) on your notes. You've followed Ole's guide on adding custom components, and you've copied uroybd's 001-aliases.njk script into your repo in the right place, but nothing happens. This is because Digital Garden does not inherently pass through all frontmatter on a page; so the script you've copied has nothing to work with.

There are two possible solutions, but be careful; if your Nunjucks script is busted, your site won't deploy properly.

1. Enable the Digital Garden feature "Let all frontmatter through"
   1. This is mostly listed as a warning; enabling this without fully understanding the implication will likely break your site.
2. You need to add the property dg-pass-frontmatter to each file you want the script to work on
   1. Other properties (like aliases) will be passed through to the Repo, and the njk script will be able to work with them.

Manually updating packages for your Digital Garden broke something

You've manually updated packages in your repo and now something's busted: