Dưới đây là bản hướng dẫn đầy đủ để dùng Typora + self-hosted Gitea làm nơi lưu ảnh.

Mục tiêu

Khi bạn dán ảnh vào Typora, Typora sẽ gọi một script tùy chỉnh. Script đó sẽ:

1. nhận đường dẫn ảnh từ Typora
2. copy ảnh vào repo Git local
3. git add + git commit + git push lên Gitea
4. in ra URL ảnh dạng raw
5. Typora lấy URL đó để thay thế ảnh local trong file Markdown

---

Cách hoạt động của Typora

Ở chế độ Custom Command, Typora sẽ gọi script kiểu như:

/path/to/upload-image.sh "image-path-1" "image-path-2"

Script của bạn phải in ra đúng số dòng URL cuối cùng, mỗi ảnh một dòng. Ví dụ:

https://git.tltdb.com/Typora/Uploads/raw/branch/main/uploads/2026/04/a.png
https://git.tltdb.com/Typora/Uploads/raw/branch/main/uploads/2026/04/b.png

Typora sẽ lấy các dòng đó để thay ảnh local trong Markdown.

---

Phần 1 — Tạo repo trên Gitea

Bạn đã có repo này:

https://git.tltdb.com/Typora/Uploads.git

Repo này sẽ dùng để chứa ảnh.

Khuyến nghị

• Nên để repo là public nếu bạn muốn ảnh hiển thị ở mọi nơi.
• Nếu repo là private, link ảnh raw thường sẽ không hiện với người chưa đăng nhập.

---

Phần 2 — Chuẩn bị repo local trên máy

Mở Terminal và chạy:

mkdir -p ~/typora-uploads
cd ~/typora-uploads
git init -b main
echo "# Typora Uploads" > README.md
git add .
git commit -m "init: first commit"
git remote add origin https://git.tltdb.com/Typora/Uploads.git
git push -u origin main

Nếu repo đã có sẵn local rồi thì chỉ cần:

cd ~/typora-uploads
git remote remove origin 2>/dev/null || true
git remote add origin https://git.tltdb.com/Typora/Uploads.git
git branch -M main
git push -u origin main

---

Phần 3 — Thiết lập đăng nhập Gitea cho Git

Bạn có username là tltdb và có token. Cách tốt nhất là không nhét token trực tiếp vào URL remote.

Cách khuyên dùng: dùng ~/.netrc

Tạo file:

nano ~/.netrc

Dán nội dung:

machine git.tltdb.com
login tltdb
password YOUR_TOKEN_HERE

Lưu lại, rồi chạy:

chmod 600 ~/.netrc

Sau đó giữ remote sạch như sau:

git remote set-url origin https://git.tltdb.com/Typora/Uploads.git

Vì sao nên dùng .netrc

• không lộ token trong lệnh
• không lộ trong .git/config
• hợp với script tự động của Typora

---

Phần 4 — Tạo script upload cho Typora

Tạo file script:

mkdir -p ~/bin
nano ~/bin/typora-gitea-upload.sh

Dán toàn bộ nội dung này:

#!/usr/bin/env bash
set -euo pipefail

# ===== CONFIG =====
REPO_DIR="$HOME/typora-uploads"
BASE_URL="https://git.tltdb.com/Typora/Uploads/raw/branch/main"
UPLOAD_ROOT="uploads/$(date +%Y/%m)"

# ===== CHECK =====
if [ ! -d "$REPO_DIR/.git" ]; then
  echo "ERROR: Repo not found at $REPO_DIR" >&2
  exit 1
fi

cd "$REPO_DIR"

# Ensure repo is on main
git checkout main >/dev/null 2>&1 || git checkout -b main >/dev/null 2>&1

urls=()

for src in "$@"; do
  if [ ! -f "$src" ]; then
    echo "ERROR: File not found: $src" >&2
    exit 1
  fi

  filename="$(basename "$src")"
  ext="${filename##*.}"
  stem="${filename%.*}"

  # sanitize name
  safe_stem="$(echo "$stem" | tr ' ' '-' | tr -cd '[:alnum:]._-' )"
  unique_name="${safe_stem}-$(date +%s)-$RANDOM.${ext}"

  target_dir="$REPO_DIR/$UPLOAD_ROOT"
  target_rel="$UPLOAD_ROOT/$unique_name"
  target_abs="$REPO_DIR/$target_rel"

  mkdir -p "$target_dir"
  cp "$src" "$target_abs"

  git add "$target_rel"
  urls+=("$BASE_URL/$target_rel")
done

git commit -m "upload image(s) from Typora: $(date '+%Y-%m-%d %H:%M:%S')" >/dev/null 2>&1 || true
git push origin main >/dev/null

for url in "${urls[@]}"; do
  echo "$url"
done

Lưu lại, rồi cấp quyền chạy:

chmod +x ~/bin/typora-gitea-upload.sh

---

Phần 5 — Cấu hình Typora

Trong Typora:

Preferences / Settings → Image

Chọn:

• When Insert Local Images → Upload Image
• Image Uploader → Custom Command

Ô command nhập:

/Users/YOUR_MAC_USERNAME/bin/typora-gitea-upload.sh

Ví dụ nếu user macOS của bạn là z:

/Users/z/bin/typora-gitea-upload.sh

Sau đó bấm Test Uploader.

---

Phần 6 — URL ảnh sẽ có dạng gì

Sau khi upload, ảnh sẽ có link kiểu:

https://git.tltdb.com/Typora/Uploads/raw/branch/main/uploads/2026/04/ten-anh-123456.png

Typora sẽ thay ảnh local trong Markdown bằng link đó.

---

Phần 7 — Cách test thủ công

Bạn có thể test script trước khi dùng trong Typora:

~/bin/typora-gitea-upload.sh "/path/to/test-image.png"

Nếu thành công, script sẽ in ra 1 dòng URL ảnh.

Sau đó bạn mở URL đó trên browser để kiểm tra ảnh có hiện không.

---

Phần 8 — Những lỗi hay gặp

1. Authentication failed

Nguyên nhân:

• token sai
• .netrc sai format
• quyền token không đủ

Cách xử lý:

• kiểm tra lại ~/.netrc
• kiểm tra lại token
• thử push tay:

cd ~/typora-uploads
git push origin main

---

2. remote contains work that you do not have locally

Chạy:

cd ~/typora-uploads
git pull --rebase origin main
git push origin main

---

3. Repo đang ở master thay vì main

Chạy:

cd ~/typora-uploads
git branch -M main
git push -u origin main

---

4. Ảnh không hiện trên website / Markdown viewer

Nguyên nhân thường là repo đang private.

Cách xử lý:

• đổi repo sang public
• hoặc dùng một host raw/static khác

---

5. Typora test không chạy

Kiểm tra:

• script có quyền chạy chưa
• đường dẫn script có đúng không
• thử chạy tay ngoài terminal trước

---

Phần 9 — Cấu trúc repo khuyên dùng

Repo sẽ trông như sau:

Uploads/
├── README.md
└── uploads/
    └── 2026/
        └── 04/
            ├── image-a.png
            ├── image-b.jpg
            └── image-c.webp

Cách này gọn, dễ quản lý theo tháng.

---

Phần 10 — Khuyến nghị bảo mật

Không nên dùng kiểu này lâu dài:

https://username:token@git.tltdb.com/Typora/Uploads.git

Vì token dễ lộ trong:

• shell history
• screenshot
• file config git

Nên dùng .netrc như hướng dẫn ở trên.

Nếu token hiện tại đã từng bị dán công khai, nên tạo token mới và thu hồi token cũ.

---

Tóm tắt ngắn gọn

Bạn cần làm đúng 5 việc:

1. tạo repo Gitea Typora/Uploads
2. clone hoặc tạo repo local tại ~/typora-uploads
3. cấu hình đăng nhập bằng ~/.netrc
4. tạo script ~/bin/typora-gitea-upload.sh
5. trỏ Typora sang script đó bằng Custom Command

Sau khi xong, mỗi lần dán ảnh vào Typora:

• ảnh sẽ được copy vào repo local
• git tự commit + push lên Gitea
• Typora tự thay bằng URL ảnh raw

Nếu bạn muốn, tôi có thể viết tiếp cho bạn bản đã điền sẵn toàn bộ path theo đúng máy Mac của bạn, chỉ để copy-paste chạy luôn.