Publish notes trên Obsidian lên web miễn phí với Github Page

Như tiêu đề, hẳn là nhiều anh em muốn publish những ghi chú của mình lên nền tảng web khi sử dụng Obsidian nhưng vì nghèo nên không thể sử dụng công cụ Obsidian Publish của chính chủ được. Vì nó có giá lên tới 8 đô/tháng, và những người nghèo như tôi hẳn sẽ phải đắn đo.

Sau khi tìm hiểu một loạt phương pháp và thử nghiệm thì tôi thấy có một giải pháp khả dĩ nhất mà cũng rất dễ thực hiện. Dự án này có tên là Quartz, được thực hiện bởi một lập trình viên tên là Jacky.

Đây cũng là dự án với mục đích thay thế luôn Obsidian Publish kia nên nó hỗ trợ toàn bộ các tính năng của Obsidian như khi bạn đang dùng trên desktop. Hơn nữa giao diện được thiết kế đẹp gần giống với Obsidian Publish bản auth nên tôi tương đối thích nên đã mày mò và lưu lại lên đây.

Anh em có thể xem demo tại đây. Tiện thể hôm nay cũng muốn vọc thêm cái nữa nên làm bài hướng dẫn cho đỡ quên, và ngay sau đây là nội dung chính.

Đây là cái hướng dẫn đơn giản nhất cho những người mù tịt về code như tôi nên nếu ai có kinh nghiệm thì có thể skip qua một số đoạn cơ bản.

Table of Contents

Thiết lập ban đầu

Đây là hướng dẫn được thực hiện trên máy tính của tôi là window 10 nên có thể máy Mac sẽ khác đôi chút, nhưng về cơ bản là giống nhau. Anh em có thể tham khảo thêm Docs tại đây hoặc xem tại video này.

Dưới đây là những phần mềm cần cài đặt:

Nodejs: Link
VSCode: Link
Tài khoản Github.com

Chúng ta sẽ cần Nodejs làm môi trường thực thi, VSCode để thao tác dòng lệnh và để remote các repo từ xa trên tài khoản github.com. Và nếu bạn đã có tài khoản thì Login không thì đăng ký mới.

Nodejs và VSCode thì cài như các phần mềm cơ bản nên skip luôn.

Ngoài ra thì chắc chắn là cần phải có Obsidian rồi, và cũng nên có một số bản notes.md có sẵn để test.

Cài đặt Quartz 4

Thiết lập thư mục

Cái này khá là lằng nhằng nên tôi viết lên đây trước cho ae đỡ phải cài đi cài lại nhiều lần. Đại khái sau khi cài Quartz lên một thư mục nào đó, tôi gọi là Publish đi, thì nó sẽ có một thư mục mặc định là quartz, và đường dẫn nó sẽ trông như thế này D:\Work\Publish\quartz. Đây là toàn bộ mã nguồn để chạy được Quartz.

Tuy nhiên, phần nội dung để mà có thể publish lên web được lại được thiết lập mặc định là ở D:\Work\Publish\quartz\content. Nên gợi ý của tôi là:

Sau khi cài đặt, có thể đổi D:\Work\Publish\quartz thànhD:\Work\Publish\project-name trong đó project-name là tên dự án của bạn cho dễ nhớ, trong trường hợp bạn có thể có nhiều ý tưởng.

Và sau đó, khi chúng ta tạo vault mới trên Obsidian thì chúng ta có thể chọn đường dẫn là D:\Work\Publish\project-name\content cho dễ quản lý.

Cài đặt Quartz lên máy tính

Mở VSCode, chọn Terminal > New Terminal

Lúc này sẽ thấy hiện cửa sổ dòng lệnh như sau:

PS C:\> là vị trí thư mục đang mở của dòng lệnh, bạn cần phải chuyển về folder cần cài đặt để tiếp tục. Từ lúc này, các đường dẫn của tôi ở đây chỉ là ví dụ, đổi về địa chỉ thực sự bạn cần cài đặt nhé.

Từ đoạn dưới đây, bạn có thể ấn copy ngay bên phải đoạn code để copy. Trỏ chuột vào giao diện dòng lệnh, nhấn chuột phải để paste.

cd D:\Work\Publish

Kiểm tra phiên bản Nodes và NPM.

node -v
npm -v

Nếu hiện lên như này thì được, chúng ta tiếp tục.

Kéo mã nguồn từ github về local (file trong máy tính) của bạn:

git clone https://github.com/jackyzha0/quartz.git

Ra như dưới này là ok

Lúc này chúng ta sẽ có một thư mục vừa được tạo ra trông như thế này D:\Work\Publish\quartz. Đây là lúc bạn nên đổi tên dự án cho dễ quản lý, mình sẽ đổi tên trực tiếp bằng Explore trên win cho nhanh.

Thư mục mới có tên là a101s đi. Và đường dẫn D:\Work\Publish\quartz bên trên sẽ thành D:\Work\Publish\a101s

Quay lại cửa sổ dòng lệnh trên VSCode, điều hướng về thư mục dự án vừa tạo.

cd D:\Work\Publish\a101s

Chạy tiếp lệnh:

npm i

Hiện ra như trên là được, như tôi chắc cốp nên chạy thêm lệnh gợi ý ở trên:

npm audit fix

Thế là xong, chạy tiếp lệnh sau để cài Quartz.

npx quartz create

Bảng lệnh sau sẽ hiện lên, ấn phím lên – xuống để chọn.

◆ Choose how to initialize the content in `D:\Work\Publish\a101s\content` │ ● Empty Quartz │ ○ Copy an existing folder │ ○ Symlink an existing folder

Nên chọn cái mặc định luôn là Empty Quartz vì mấy cái kia trên window hơi khó thực hiện, tôi thử rồi mà không được. Và dù sao đằng nào chúng ta cũng thiết lập Vault trên Obsidian sau nên không quan tâm lắm.

Bạn nào thích vọc sâu thì tự nghịch.

Choose how Quartz should resolve links in your content. This should match Obsidian's link format. You can change this later in `quartz.config.ts`

Chọn tiếp Treat links as shortest path ((default)). Cái này tôi cũng dùng mặc định cho nhanh, mấy tùy chọn khác thì để vọc sau cho đỡ lỗi.

Hiện lên thông báo này là đã cài xong, bạn có thể cho chạy thử luôn bằng trình duyệt web sau khi dùng lệnh npx quartz build --serve.

npx quartz build --serve

Đợi chạy xong hiện lên như bên dưới là được.

Lúc này bạn có thể paste đường dẫn http://localhost:8080 kia vào trình duyệt web để xem thử.

Và Tada ~~

Tới đây đã coi như xong 1/3 chặng đường rồi. Sau này, khi phát triển thêm nội dung hoặc tùy chỉnh trang web, bạn có thể dùng lệnh npx quartz build --serve tiếp để chạy thử trên local.

Sửa lỗi hoàn thiện xong thì chúng ta hãy publish lên web. Vì quá trình publish lên web sẽ mất thời gian hơn chạy trên local. Nhưng cũng không quá lâu đâu, với web nhỏ như của tôi trung bình sau khoảng 2 phút là có thể xem được sự thay đổi rồi.

Để tắt đi thì chúng ta quay lại giao diện dòng lệnh của VS Code ấn Ctrl + C để thoát chương trình đang chạy. Dòng thông báo này hiện lên Terminate batch job (Y/N)?, chọn y + Enter để thoát hẳn.

Kết nối Local lên Remote trên github

Sau khi đã cho chạy thử trên local thành công, nếu bạn thích thì có thể thêm một số notes của Obsidian dưới định dạng .md vào thư mục D:\Work\Publish\a101s\content để có thể xem thử.

Còn không thì có thể tới luôn bước này để publish online lên nhìn cho thích.

Lúc này bạn đăng nhập tài khoản tại github.com, tạo repository mới với tên tùy chọn, tuy nhiên có một lưu ý nhỏ.

Nếu bạn đơn giản đặt tên là a101s thôi chẳng hạn thì đường dẫn website của bạn sẽ có dạng username.github.io/repository-name. Trong đó username là tên tài khoản của bạn và repository-name là tên repository vừa tạo. Như ở ví dụ này thì sẽ là tuyenman.github.io/a101s.

Vì thế bạn nên đặt tên repository sao cho phù hợp với dự án mà không bị trùng như sau thì đường dẫn ra sẽ đẹp hơn.

Lúc này nếu publish lên thì địa chỉ web sẽ chính xác như tên của repo là a101studio.github.io.

Đoạn notes này viết ra sau khi cái tut này gần xong. Bằng một cách ngớ ngẩn nào đó mà tôi không biết, thì tôi chỉ vào được website bằng địa chỉ https://tuyenman.github.io/a101studio.github.io/ mà không phải như tôi nói trên kia.

Nhưng vì đoạn tut này viết dài quá và cũng chụp ảnh rồi nên ngại sửa nên anh em cứ đặt tên như bình thường nhé. Sau đó chúng ta custom domain sau. :))

Các tùy chọn khác để mặc định, không thay đổi gì cả. Ấn Create repo.

Lúc này một bảng Quick setup hiện ra, lưu luôn địa chỉ repo của bạn để tiếp tục các bước sau. Ở đây của tôi là https://github.com/tuyenman/a101studio.github.io.git.

Quay lại giao diện dòng lệnh, thực hiện thao tác sau để lấy quyền điều khiển repo trên remote (tức là trên github) về local (máy tính) để chỉnh sửa.

git remote add origin https://github.com/tuyenman/a101studio.github.io.git

Thay tên username và tên repo tương ứng của bạn.

Lúc này nếu bạn chưa từng chạy thì sẽ có dòng thông báo của VS Code hiện lên, nó sẽ mở trình duyệt để đăng nhập github phê duyệt quyền truy cập. Cứ chọn đồng ý là được.

Ấn Enter để chạy. Lúc này sẽ hiện lên báo lỗi error: remote origin already exists.

Nhập lệnh git remote -v để kiểm tra.

git remote -v

Hiện lên như thế kia là ok. Nhập tiếp lệnh sau để xóa origin cũ.

git remote rm origin

Sau đó chạy lại.

git remote add origin https://github.com/tuyenman/a101studio.github.io.git

Không hiện lên thông báo gì là ok. Chạy tiếp ..

npx quartz sync --no-pull

Đến lúc này hiện lên Done là tất cả đã xong. Giờ tiếp tục setup trên github để tạo workflow cho quá trình sync giữa local và remote sau này.

Update

Nếu xuất hiện lỗi [Error: EPERM: operation not permitted, rmdir 'D:\Quartz\universe\quartz\.quartz-cache\content-cache\Daily Notes'] {
errno: -4048,
code: 'EPERM',
syscall: 'rmdir',
path: 'D:\\Quartz\\universe\\quartz\\.quartz-cache\\content-cache\\Daily Notes'
}

Chạy thêm lệnh git push để đảm bảo đẩy lên được git.

Cái này tôi làm mò vì không hiểu git lắm, nhưng nó work :v

Trên VSCode chọn File > Add Folder to Workspace

Tìm đến thư mục có tên dự án của bạn là được, ở ví dụ này là a101s.

Hiện ra như này là ok.

Đến đây thì chúng ta thiết lập Github Pages để cho nó online. Các bạn có nhu cầu sử dụng các phương thức khác như Cloudflare Pages, Vercel … thì xem thêm tại đây.

Trong thư mục dự án, lần lượt tìm đến folder .github > workflows. Chuột phải vào folder workflows chọn thêm file mới. Đặt tên file là deploy.yml.

Copy đoạn mã sau vào nội dung file deploy.yml

name: Deploy Quartz site to GitHub Pages
 
on:
  push:
    branches:
      - v4
 
permissions:
  contents: read
  pages: write
  id-token: write
 
concurrency:
  group: "pages"
  cancel-in-progress: false
 
jobs:
  build:
    runs-on: ubuntu-22.04
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0 # Fetch all history for git info
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - name: Install Dependencies
        run: npm ci
      - name: Build Quartz
        run: npx quartz build
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: public
 
  deploy:
    needs: build
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Ấn Ctrl + S để lưu lại. Như ảnh sau là được.

Quay lại trang repo trên github, chọn Setting > Pages > Source > Chọn Github Action như ảnh.

Chọn thế là xong. Quay lại giao diện dòng lệnh trên VSCode chạy đoạn mã sau.

npx quartz sync

Ting ting~~ Hiện lên như sau là đã ok. Web đã lên sóng rồi đấy.

Vào ngó thử luôn! Thế là OK rồi đó.

Vào phần Actions trên menu của repo để kiểm tra.

Như vậy cả quá trình chưa tới 1 phút để online lên web.

Thiết lập Vault trong Obsidian để sử dụng

Và sau khi đã hoàn thành những bước trên, toàn bộ nội dung trong đường dẫn D:\Work\Publish\a101s\content sẽ được sử dụng làm nội dung trên website của bạn.

Để không phải viết note ở một nơi và khi nào cần thì lại cop sang để publish lên web thì bây giờ chúng ta mở luôn Vault mới trên thư mục content kia.

Bật Obsidian > Chọn Open folder as Vault, tìm đến vị trí file content và chọn nó.

Lúc này khi Obsidian hiện lên thì chúng ta chỉ thấy một file index.md. Bạn không được xóa nó vì đấy là nội dung trang chủ. Bạn có thể viết gì tùy thích lên trang chủ của mình bằng file này.

Từ đây mọi thiết lập khác trên Obsidian bạn cứ thực hiện như bình thường.

Tuy nhiên, trong Vault này cũng có thể có những folder hoặc notes bạn không muốn public, vì thế nên thiết lập một template với nội dung đại loại như sau.

---
title: 
draft: true
tags:
---

title: Tiêu đề của Notes sẽ hiển thị trên web, nếu bạn không đặt tên cho nó, nó sẽ tự động lấy tên gốc của notes.
draft: chọn true nếu không muốn public, nếu không để false, hoặc tick luôn trên Obsidian
tags: tùy bạn

Vậy là xong cơ bản, bạn có thể thêm các notes và folder như bình thường, hoặc copy sang cho nhanh để trải nghiệm.

Và từ bây giờ, bạn nhớ là mỗi khi thay đổi gì trên Obsidian và muốn hiển thị lên web, hãy chạy lệnh này trước để test trên local ở địa chỉ http://localhost:8080/

npx quartz build --serve

Sau đó nếu không hiện lỗi gì thì đồng bộ lên web bằng lệnh.

npx quartz sync

Gõ địa chỉ web và tận hưởng thành quả thôi!

Custom domain cho Github Pages

Cái này là tùy chọn, nếu bạn muốn mình có một bộ mặt xịn xò, chanh sả một chút trên internet thì tiếp tục vọc thôi.

Bạn có thể vào bất cứ nhà cung cấp domain nào tại Việt Nam để mua domain, mình thì hay mua trên iNet vì quen rồi. DNS của bên này cũng nhanh nên trỏ tên miền các thứ nhanh hơn mấy chỗ trước tôi hay mua.

Đợt này có bán domain cấp 2 Việt Nam dạng .io.vn phải nói là rẻ thối ra. 30k/năm cho năm đầu và gia hạn hàng năm là 50k. Vâng ạ, là 50k/năm cho một cái domain đấy ạ. Trước tôi hay mua domain .vn giá 450k/năm với .com 250k/năm nên giờ thấy rẻ quá.

Anh em nếu cần thì có thể click vào link này mua domain cho tôi có vài đồng cafe, còn không thì cứ tùy nghi xử lý.

Ok có tên miền rồi thì chúng ta có 2 lựa chọn. Trỏ về chính nhà cung cấp domain hoặc trỏ về Cloudflare.

Cái hay của việc trỏ về Cloudflare là bên này có CDN ở khắp thế giới nên truy cập cũng nhanh hơn. Còn lại vẫn tùy bạn, tôi hướng dẫn cả hai.

Thiết lập trong Github pages

Vẫn trong phần thiết lập Github pages phía bên trên, nhập vào domain của bạn. Ở đây của tôi là architecture101studio.com, ấn Save.

Lúc này có đoạn chữ vàng hiện lên DNS Check in Progress thì cứ kệ nó vì chúng ta chưa thiết lập ở nhà cung cấp domain.

Trỏ DNS lên Cloudflare

Nếu bạn trỏ domain về Cloudflare thì bạn sẽ trỏ về hai địa chỉ Namesever dưới đây.

henry.ns.cloudflare.com

melinda.ns.cloudflare.com

Vào Dashboard của Cloudflare, thêm tên miền vào và thiết lập các bản ghi như sau.

Type: A
Name: @ (trỏ về domain chính)
Content: trỏ về 4 địa chỉ ip như sau

185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153

Trỏ thêm một cái Name là www về 185.199.108.153. Như ảnh dưới đây.

Thế là đã trỏ domain xong. Đợi một lúc, vào trong phần setting của Github Page kiểm tra, nếu hiện lên thông báo màu xanh DNS check successfullà ok.

Bây giờ bạn đã có thể truy cập note của bạn bằng địa chỉ web trên rồi.

Trỏ DNS ở nhà cung cấp domain

Ở đây tôi làm là inet, anh em tùy chọn nhưng tương tự phía trên trên.

Type: A
Name: @ (trỏ về domain chính)
Content: trỏ về 4 địa chỉ ip như sau

185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153

Trỏ thêm một cái Name là www về 185.199.108.153.

Trỏ xong đợi github cập nhật là được.

Như bên trên mặc dù đã truy cập được bình thường nhưng khi vào lại phần setting nó vẫn hiện đang check DNS nhưng kệ cụ nó. Web vào được là được.

Anh em có thể xem demo ở đây. Chúc anh em thành công.

Có gì vướng mắc cứ comment hoặc pm fb nhé!

Post Views: 30