Welcome to your Personal Knowledge Management Garden!
This project publishes selected notes from an Obsidian vault on GitHub Pages.
- Introduction
- Features
- Getting Started
- Instructions To Use This Repository as a Template
- Manage Personal Access Token (PAT)
- Add Notes
- Prepare Notes To Be Published
- Test Locally
- Publish Notes
- Obsidian Graph View
- Pre-commit Git Hook
- Front Matter
- GitHub Actions Workflow
- Contributing
- License
- References
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:
Importing HTML files into Obsidian posed issues with asset references, which I plan to address later (see Issue #10).
- 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.
- 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
)
Follow step by step:
-
Start with instructions to use this repository as a template.
-
IMPORTANT: Manage your personal access token on GitHub.
-
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
-
IMPORTANT: Install Pre-commit Git Hook to enable the pre-commit hook.
-
IMPORTANT: Insert
https://<your-github-username>.github.io
in URL field in_config.yml
. -
(Optional) Configure title, description, and other settings in
_config.yml
. -
Prepare notes to be published.
-
(Optional) Test your site locally.
-
Publish notes on GitHub Pages.
- Navigate to the GitHub page.
- Use the Template:
- Click the
Use this template
button located at the top of the repository page. - Choose
Create a new repository
.
- Click the
- Create New Repository:
-
Fill out the form:
Repository name:
<your-github-username>.github.io
Replace
<your-github-username>
with your GitHub username. -
Finish by clicking
Create repository
.
-
Continue with Step 2 of Using the Repository As Template.
-
Navigate to Your GitHub Account:
- Go to your GitHub account.
-
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.
-
Generate a New Token:
- In the left sidebar, click Personal access tokens.
- Choose
Tokens (classic)
. - Click Generate new token (classic).
-
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.
- Note: Give your token a descriptive name, such as
-
Copy the Token:
-
Copy the generated token.
πYou will not be able to see it again.
-
-
Navigate to Your Repository:
- Go to the repository where you want to add the secret.
-
Access Repository Settings:
- Click on the Settings tab.
-
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.
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 }}
Continue with Step 3 of Using the Repository As Template.
π 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 yourFile 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). - Click
-
- Edit your notes in Obsidian.
Continue with Step 6 of Using the Repository As Template.
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 calledPrivate
and move the notes you want to hide there.
-
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.
Continue with Step 7 of Using the Repository As Template.
π Ensure you have both installed Ruby and Bundler.
-
Install dependencies:
bundle install
-
Run the site locally:
bundle exec jekyll serve
The site will be available at http://localhost:4000
.
π Ensure you have installed Docker and docker is running.
-
Run Docker Compose:
docker-compose up -d
The site will be available at http://localhost:4000
.
Continue with Step 8 of Using the Repository As Template.
-
Push your changes to GitHub.
π Ensure you have pushed your changes to the
main
ordevelop
branch. -
Your site will be published at
https://<your-github-username>.github.io
.
To include the Obsidian Graph View in your site, follow these steps:
- Use paid way Obsidian Publish
- Use free Cosma
A pre-commit Git hook pre-commit.sample
ensures code quality and consistency before commits are made.
-
Copy the script
pre-commit.sample
to your local.git/hooks
directory. Rename it aspre-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
.
Continue with Step 4 of Using the Repository As Template.
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:
-
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.
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.
Contributions are welcome! Follow these steps:
- Clone or fork the repository.
- Create a new branch (
git checkout -b feature/YourFeature
). - Commit your changes (
git commit -m 'Add some feature'
). - Push to the branch (
git push origin feature/YourFeature
). - Open a pull request.
This project is licensed under the MIT License. See the LICENSE file for details.