Digital Obsidian Garden + GitHub Pages

This is the template to be used together with the Digital Garden Obsidian Plugin.

Rendering and deployment is done via GitHub Pages. So you can use the GitHub account and repository you need anyway to fully deploy your site (no Vercel, Netlify, Docker, etc. needed).

Libraries have also been updated to more recent versions. If there is any problems with this (i.e. your deployment fails), please open an issue with the specific error message.

Setup

1. Download and install the community plugin Digital Garden in Obsidian.
2. Next, you will need a GitHub account. If you don't have this, create one here.
3. Create a new repository using this one as a template (green button in the top right). Keep "Include all branches" unchecked. IMPORTANT: it's mandatory you use [your username].github.io as the name for the new repository (e.g. for me that would be foxblock.github.io) and make it public (unless you have a paid GitHub enterprise account).
   • You can also create a fork. This is slightly messier (will include all commits up to this point in history), but allows for merging updates to this template more easily.
4. Setup the plugin in Obsidian by entering the repo name ([your username].github.io), your username and an access token.
5. Back in your GitHub repository go to Settings > Pages and make sure "Deploy from a branch" and gh-pages is selected as the branch name, keep folder at /(root)
   • The gh-pages branch should be auto-generated by GitHub. You can track the progress in the "Actions" tab of the repository, look for "pages build and deployment". If you cannot select it, wait a minute, then refresh the page or come back to this step after doing the next one about publishing a note.
6. In Obsidian publish any note with the dg-home and dg-publish properties set to true to generate an index file for your site. Publishing via the plugin will automatically create a commit to the main branch of your new repo, which in turn will start the workflow generating your site.
7. After a minute or so your site should be available under https://[your username].github.io
   • If your site only shows a rendering of this readme and not your notes, go to back to Settings > Pages and make sure you have selected the gh-pages branch (click "Save" next to it)
   • If it shows a 404 page, you have not published a note as the index file (see previous step)

(this mostly follows the official Getting Started guide, just skips the steps using Vercel)

Updates

Because you are working from a fork of the original template, you cannot use the "Update template" feature of the Obisdian plugin - it would overwrite some of the changes made.

For library updates the dependabot feature is enabled by default. It will run once a week and create pull requests for library updates. Note that not all updates might be compatible and can break things. Check the actions tab for any errors during deployment after you apply updates. Also note that security alerts are disabled by default, you can enable them in the settings (see above link).

For any other update to the template you sadly will have to manually check for it and copy them over to your repository.

Custom domain

To set a custom domain, edit the .github/workflows/build.yml file and add cname: yourdomain.com to the last block (deploy parameters).
It should look like this:

      ...
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v4
        if: github.ref == 'refs/heads/main'
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./dist
          cname: yourdomain.com

After pushing, the domain should also show up in Settings > Pages > Custom domain and undergo DNS checking.
Here is the official guide on how to set it up: https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site/managing-a-custom-domain-for-your-github-pages-site (ignore steps 1 through 4 of the "Configuring an apex domain" chapter. If you set your domain in the repo settings manually, it will be reset the next time you push any changes).

Comments

GitHub allows embedding a comment feature into your site by using a plugin called Giscus. Giscus basically embeds single threads from the GitHub Discussions feature into your site. The setup is fairly straightforward:

1. Go to https://giscus.app/ and follow the instructions there
2. In the "Page to Discussions Mapping" group you have several options:
   • pathname and URL will generate a new Discussions thread based on (part of) the URL of your note. This will break when you move your notes or change their name.
   • title will work off the <title> HTML tag, which is generated from the main heading of your note (which also controls the filename). Will not break if you move your notes, but when you rename them. You can fix the title of your note using the title property, so that does not happen.
   • og:title is similar to the above method, but uses a differnt HTML tag. This by default does not work, because the tag is not generated. But you can manually create it also using Metatag properties.
   • I personally use the "title" option
3. For the other settings, chose whatever you like.
4. At the end some code will be generated for you which looks like this

<script src="https://giscus.app/client.js" 
    ... 
</script>

5. Create a new file in your repo at src/site/_includes/components/user/notes/afterContent/comment.njk
   • you can do this on GitHub in your browser with the Create new file feature, just copy the above path to the filename input box
6. Copy the generated <script> code into this new file and commit/push it to your repository
7. This will embed the comment widgit below the content in all of your notes. If you want to place it in a different location or have comments also or only on your homepage, see the documentation on custom components.

Example:

Theme switcher / previewer

Chosing the right theme is very tedious by default. You have to select the theme in the Obsidian plugin settings and wait for the site to update and deploy, which might take a minute or two.

To streamline this process I made a script to preview a theme before applying it. See the following link on how to add it to your site: oleeskild/obsidian-digital-garden#688

Docs

Docs for authoring and customizing the plugin and site are available at dg-docs.ole.dev

Credits

@mounta11n Original idea and setup work.