Update README.md
This commit is contained in:
parent
6849ccc3b7
commit
8b6d60f7e6
369
README.md
369
README.md
@ -1 +1,368 @@
|
||||
# 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ư:
|
||||
|
||||
```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.
|
||||
Loading…
x
Reference in New Issue
Block a user