Personal Knowledge Management Garden

Welcome to your Personal Knowledge Management Garden!

This project publishes selected notes from an Obsidian vault on GitHub Pages.

Table of Contents

• Introduction
• Features
• Getting Started
  • Prerequisites
  • Using the Repository As Template
• Create Personal Access Token
  • Step 1: Create a Personal Access Token (PAT)
  • Step 2: Add the PAT as a Secret in Your GitHub Repository
  • (Only when secret name is not ACTIONS_PAT) Update Your GitHub Actions Workflow YAML
• Add Notes
  • Exclude Notes From Being Published
• Prepare Notes To Be Published
• Test Locally
  • Jekyll
  • Docker
• Publish Notes
• Obsidian Graph View
• Pre-commit Git Hook
• Front Matter
• GitHub Actions Workflow
• Contributing
• License
• References

Introduction

In May 2024 I started to use Obsidian as a note taking app.

I aimed to publish my notes on GitHub Pages to share them with others, starting with the Jekyll Garden Theme.

Having used Notion extensively, my notes were structured around the Personal Knowledge Management (PKM) system by Tiago Forte - building a second brain.

Migrating my Notion notes to Obsidian involved exporting them as HTML files due to issues with Markdown and CSV exports. Additionally, I had to use 7-Zip on Windows 11 to unzip the files properly.

In Obsidian, I utilize plugins like:

• DataView
• MAKE.md
• Importer

Importing HTML files into Obsidian posed issues with asset references, which I plan to address later (see Issue #10).

Features

• Notes: Use Obsidian to create and manage notes.
• Front Matter: Automatically adds front matter to markdown files.
• Linting: Lints markdown files using markdownlint-cli2.
• GitHub Actions: Automates the build and deployment of the Jekyll site to GitHub Pages.
• Jekyll Integration: Generates static pages using Jekyll.
• Docker Support: Includes Docker configuration for easy development and deployment.

Getting Started

Prerequisites

• Ruby
• Bundler
• Docker (optional, for containerized setup)
• markdownlint-cli2
• GitHub Token named ACTIONS_PAT (used in repository's GitHub Actions workflow build-and-deploy-github-pages.yml)

Using the Repository As Template

Follow step by step:

1. Click on the Use this template button at the top of the repository page.

2. Choose Create a new repository.

3. Name the repository as <your-github-username>.github.io.

4. Manage your personal access token on GitHub.

5. Clone your repository.

   For example:

   git clone https://github.com/<your-github-username>/<your-github-username>.github.io.git
   cd <your-github-username>.github.io

6. Install Pre-commit Git Hook to enable the pre-commit hook.

7. Configure title, description, and other settings in _config.yml.

8. Add Notes.

9. Prepare notes to be published.

10. (Optional) Test your site locally.

11. Publish notes on GitHub Pages.

Manage Personal Access Token (PAT)

Step 1: Create a Personal Access Token (PAT)

1. Navigate to Your GitHub Account:

   • Go to your GitHub account.

2. Access Developer Settings:

   • In the upper-right corner of any page, click your profile photo, then click Settings.
   • In the left sidebar, click Developer settings.

3. Generate a New Token:

   • In the left sidebar, click Personal access tokens.
   • Click Generate new token.

4. Configure the Token:

   • Note: Give your token a descriptive name, such as ACTIONS_PAT.
   • Expiration: Set an appropriate expiration date. A shorter period is more secure, but you will need to renew it periodically.
   • Select Scopes: Check the following scopes:
     • repo (for full control of private repositories)
     • workflow (for updating GitHub Actions workflows)
     • admin:org (if deploying to organizational repositories)
   • Click Generate token.

5. Copy the Token:

   • Copy the generated token. You will not be able to see it again.

Step 2: Add the PAT as a Secret in Your GitHub Repository

1. Navigate to Your Repository:

   • Go to the repository where you want to add the secret.

2. Access Repository Settings:

   • Click on the Settings tab.

3. Add a New Secret:

   • In the left sidebar, click Secrets and variables and then click Actions.
   • Click New repository secret.
   • In the Name field, type ACTIONS_PAT.
   • In the Value field, paste the copied PAT.
   • Click Add secret.

(Only if the Secret's Name is not ACTIONS_PAT) Update Your GitHub Actions Workflow YAML

Ensure the GitHub Actions workflow file build-and-deploy-github-pages.yml references the secret you created.

If you used a different secret name, replace ACTIONS_PAT in the workflow file with the name of your secret.

For example, if your secret is named MY_SECRET_PAT, update the token field as follows:

with:
  token: ${{ secrets.MY_SECRET_PAT }}

Add Notes

🔔 Avoid having too long markdown file names and extensive folder hierarchies to prevent issues with the site generation.

🔔 Importing notes from another note taking app can be a time-consuming process to fulfill your requirements. You should check the rules in .markdownlint.jsonc before to adjust the linting rules to your needs.

Steps to add an Obsidian vault to be published:

• Open Obsidian and create a vault in the _notes/Public directory.
• (Optional) Delete the Welcome note in Obsidian.
• Install plugin MAKE.md in Obsidian.
• Enable plugin MAKE.md in Obsidian.
• Create your notes in Obsidian.

If you want to import notes from another note taking app:

• Install plugin Importer in Obsidian.
• Enable plugin Importer in Obsidian.
• Import your notes with the Importer plugin.

  • Open Importer and choose your File format.

  • If needed Choose file to import.

  • Leave Output folder blank to output to vault root.

  • Optionally choose other settings.

    • Click Import.

    Assets like pictures etc. are stored in the Public directory by default. Linking of assets in the markdown files is not supported yet (see Issue #10).

• Edit your notes in Obsidian.

Exclude Notes From Being Published

You can hide a note from the feed by changing the front matter of the note.

Here's how:

---
title: Note Title
feed: hide # before it was --- feed: show
---

Another way to hide notes from the feed is to move them to the _notes/Private directory.

• Create a new directory in the _notes directory called Private and move the notes you want to hide there.

Prepare Notes To Be Published

• Add your changes to the repository with the Version Control System of your choice.

• Commit your changes.

  A Python script, executed by the pre-commit hook, will add front matter to the notes in the _notes/Public directory and all its sub-directories.

  After that it will lint the markdown files using markdownlint-cli2. If linting fails, the commit will be aborted. You can fix the linting issues manually or by editing the .markdownlint.jsonc file to adjust the linting rules to your needs.

  After fixing commit again.

Test Locally

Jekyll

🔔 Ensure you have both installed Ruby and Bundler.

1. Install dependencies:

   bundle install

2. Run the site locally:

   bundle exec jekyll serve

The site will be available at http://localhost:4000.

Docker

🔔 Ensure you have installed Docker and docker is running.

1. Run Docker Compose:

   docker-compose up -d

The site will be available at http://localhost:4000.

Publish Notes

1. Push your changes to GitHub.

   🔔 Ensure you have pushed your changes to the main or develop branch.

2. Your site will be published at https://<your-github-username>.github.io.

Obsidian Graph View

To include the Obsidian Graph View in your site, follow these steps:

• Use paid way Obsidian Publish
• Use free Cosma

IMPORTANT: Pre-commit Git Hook

A pre-commit Git hook pre-commit.sample ensures code quality and consistency before commits are made.

1. Copy the script pre-commit.sample to your local .git/hooks directory. Rename it as pre-commit. Make sure it is executable.

   For example:

   cp pre-commit.sample .git/hooks/pre-commit
   chmod +x .git/hooks/pre-commit # may not be necessary

The hook performs the following tasks:

• Tries to locate the Python executable on your system.
• Changes to the repository root.
• Checks for new or modified markdown files in the _notes/Public directory and its sub-directories.
• Executes the Python script to add necessary front matter to these files.
• Tries to locate the markdownlint-cli2 executable on your system.
• Lints the markdown files using markdownlint-cli2.

Front Matter

A Python script is included to automate certain tasks, such as adding front matter to markdown files.

The script ensures that all markdown files in the _notes/Public directory have the necessary front matter. Necessary front matter includes the title and feed fields.

It is automatically executed by the pre-commit Git hook.

To use the script manually:

1. Run the script with the list of added or modified markdown files as arguments:

   python add_front_matter.py _notes/Public/your_note.md _notes/Public/another_note.md

The script checks if the file already has front matter and adds it if necessary.

It also logs the process for each file.

GitHub Actions Workflow

This repository uses a GitHub Actions workflow to automate the build and deployment of the Jekyll site to GitHub Pages upon a push to the main and develop branch or by manual trigger.

The workflow consists of the following key steps:

• Permissions: Sets GITHUB_TOKEN to read contents, write pages, and generate ID tokens.
• Concurrency: Ensures only one deployment is processed at a time.
• Build Job:
  • Checks out the repository.
  • Sets up Ruby and Bundler.
  • Installs dependencies and builds the site.
  • Uploads the build artifact.
• Deploy Job: Deploys the site to GitHub Pages using the uploaded artifact.

Contributing

Contributions are welcome! Follow these steps:

1. Clone or fork the repository.
2. Create a new branch (git checkout -b feature/YourFeature).
3. Commit your changes (git commit -m 'Add some feature').
4. Push to the branch (git push origin feature/YourFeature).
5. Open a pull request.

License

This project is licensed under the MIT License. See the LICENSE file for details.

References

• Jekyll Garden Theme
• markdownlint-cli2
• Ruby
• Bundler
• Jekyll
• Obsidian
• Obsidian Publish
• Notion
• GitHub Pages
• Docker
• Front Matter
• Liquid
• GitHub Actions
• Tiago Forte - building a second brain
• DataView
• MAKE.md
• Importer
• Cosma
• Issue #10