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ư:

```bash
/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ụ:

```text
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:

```text
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:

```bash
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:

```bash
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:

```bash
nano ~/.netrc
```

Dán nội dung:

```text
machine git.tltdb.com
login tltdb
password YOUR_TOKEN_HERE
```

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

```bash
chmod 600 ~/.netrc
```

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

```bash
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:

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

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

```bash
#!/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:

```bash
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:

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

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

```bash
/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:

```text
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:

```bash
~/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:

```bash
cd ~/typora-uploads
git push origin main
```

------

### 2. `remote contains work that you do not have locally`

Chạy:

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

------

### 3. Repo đang ở `master` thay vì `main`

Chạy:

```bash
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:

```text
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:

```bash
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.