<<<<<<< HEAD

Typora Uploads

======= 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ũ.

---

FIX POSSIBLE Issues

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

---

Issues → Solutions (compact)

1. No upstream (tracking) branch

   git branch -u origin/main
   

2. Wrong pull syntax

   git pull origin main
   

3. Divergent branches (no strategy set)

   git config pull.rebase false
   

4. Unrelated histories

   git pull origin main --allow-unrelated-histories
   

---

Final working sequence

git branch -u origin/main
git config pull.rebase false
git pull origin main --allow-unrelated-histories
git push