Uploads/README.md at 8b6d60f7e6de67ba718050142d1fa32b2cbfdf8f

Typora/Uploads

Fork 0

thanhtl 8b6d60f7e6 Update README.md

2026-04-01 17:17:40 +07:00

7.3 KiB

Raw Blame History

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

nhận đường dẫn ảnh từ Typora
copy ảnh vào repo Git local
git add + git commit + git push lên Gitea
in ra URL ảnh dạng raw
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:

tạo repo Gitea Typora/Uploads
clone hoặc tạo repo local tại ~/typora-uploads
cấu hình đăng nhập bằng ~/.netrc
tạo script ~/bin/typora-gitea-upload.sh
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.

7.3 KiB Raw Blame History