Typora/Uploads
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update README.md

Browse Source
This commit is contained in:
thanhtl 2026-04-23 15:46:26 +07:00
parent d23754990b
commit cda0930013
1 changed files with 115 additions and 314 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

429
README.md
View File

@ -1,406 +1,207 @@
<<<<<<< HEAD
# Typora Uploads # 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 This repository is used to store images uploaded from Typora and serve them via raw URLs.
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 ## 📌 Overview
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
------ When you paste an image into Typora:
## Cách hoạt động của Typora 1. The image is copied into this repository
2. It is committed and pushed to remote (Gitea)
3. A raw URL is generated
4. Typora replaces the local image with that URL
Ở chế độ **Custom Command**, Typora sẽ gọi script kiểu như: ---
## 🚀 Setup (First Time Only)
### Clone repository
```bash ```bash
/path/to/upload-image.sh "image-path-1" "image-path-2" git clone https://git.tltdb.com/Typora/Uploads.git ~/typora-uploads
```
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 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: > ⚠️ Do NOT run `git init`. Always use `git clone`.
```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
```
------ ### Setup authentication
## Phần 3 — Thiết lập đăng nhập Gitea cho Git Create `.netrc`:
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 ```bash
nano ~/.netrc nano ~/.netrc
``` ```
Dán nội dung:
```text ```text
machine git.tltdb.com machine git.tltdb.com
login tltdb login tltdb
password YOUR_TOKEN_HERE password YOUR_TOKEN_HERE
``` ```
Lưu lại, rồi chạy:
```bash ```bash
chmod 600 ~/.netrc chmod 600 ~/.netrc
``` ```
Sau đó giữ remote sạch như sau: ---
```bash ### Setup upload script
git remote set-url origin https://git.tltdb.com/Typora/Uploads.git
```
### Vì sao nên dùng `.netrc` Create script:
- 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 ```bash
mkdir -p ~/bin mkdir -p ~/bin
nano ~/bin/typora-gitea-upload.sh nano ~/bin/typora-gitea-upload.sh
``` ```
Dán toàn bộ nội dung này: Paste your upload script, then:
```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 ```bash
chmod +x ~/bin/typora-gitea-upload.sh chmod +x ~/bin/typora-gitea-upload.sh
``` ```
------ ---
## Phần 5 — Cấu hình Typora ### Configure Typora
Trong Typora: **Preferences → Image**
**Preferences / Settings → Image** * When Insert Local Images → `Upload Image`
* Image Uploader → `Custom Command`
Chọn: Command:
- **When Insert Local Images** → `Upload Image`
- **Image Uploader** → `Custom Command`
Ô command nhập:
```bash ```bash
/Users/YOUR_MAC_USERNAME/bin/typora-gitea-upload.sh /Users/YOUR_USERNAME/bin/typora-gitea-upload.sh
``` ```
Ví dụ nếu user macOS của bạn là `z`: ---
## 🖥️ Using on Multiple Computers
On any new machine:
```bash ```bash
/Users/z/bin/typora-gitea-upload.sh git clone https://git.tltdb.com/Typora/Uploads.git ~/typora-uploads
cd ~/typora-uploads
``` ```
Sau đó bấm **Test Uploader**. Then repeat:
------ * authentication setup (`~/.netrc`)
* upload script setup
* Typora configuration
## Phần 6 — URL ảnh sẽ có dạng gì ---
Sau khi upload, ảnh sẽ có link kiểu: ## 🔁 Daily Workflow
```text Before using Typora:
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 ```bash
cd ~/typora-uploads cd ~/typora-uploads
git pull origin main
```
After uploading images:
```bash
git push origin main git push origin main
``` ```
------ ---
### 2. `remote contains work that you do not have locally` ## ⚠️ Conflict Prevention
Chạy: If using multiple devices:
* Always run `git pull` before uploading
* Avoid working offline too long
If conflict occurs:
```bash ```bash
cd ~/typora-uploads
git pull --rebase origin main git pull --rebase origin main
git push origin main
``` ```
------ ---
### 3. Repo đang ở `master` thay vì `main` ## 🧠 Recommended Improvement (Optional)
Chạy: Add auto-sync to your script:
```bash ```bash
cd ~/typora-uploads git pull --rebase origin main >/dev/null 2>&1 || true
git branch -M main
git push -u origin main
``` ```
------ ---
### 4. Ảnh không hiện trên website / Markdown viewer ## 📂 Repository Structure
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 ```text
Uploads/ Uploads/
├── README.md ├── README.md
└── uploads/ └── uploads/
└── 2026/ └── YYYY/
└── 04/ └── MM/
├── image-a.png ├── image-1.png
├── image-b.jpg └── image-2.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ũ.
------
## 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**
```bash
git branch -u origin/main
```
2. **Wrong pull syntax**
```bash
git pull origin main
```
3. **Divergent branches (no strategy set)**
```bash
git config pull.rebase false
```
4. **Unrelated histories**
```bash
git pull origin main --allow-unrelated-histories
``` ```
--- ---
## Final working sequence ## 🌐 Image URL Format
```text
https://git.tltdb.com/Typora/Uploads/raw/branch/main/uploads/YYYY/MM/filename.png
```
---
## 🔒 Notes
* Use **public repo** if images must be accessible everywhere
* Do NOT embed token in Git remote URL
* Prefer `.netrc` for authentication
---
## 🧯 Troubleshooting
### Remote rejected (non-fast-forward)
```bash ```bash
git branch -u origin/main git pull --rebase origin main
git config pull.rebase false
git pull origin main --allow-unrelated-histories
git push git push
``` ```
---
### Authentication failed
* Check `~/.netrc`
* Verify token permissions
---
### Script not working in Typora
* Check script path
* Ensure executable (`chmod +x`)
* Test manually:
```bash
~/bin/typora-gitea-upload.sh "/path/to/image.png"
```
---
## ✅ Key Rule
```bash
git clone # correct
git init # wrong (for this project)
```