Merge local and remote histories

README.md

@@ -1 +1,372 @@
+<<<<<<< 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ư:
+
+```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.
+>>>>>>> 8b6d60f7e6de67ba718050142d1fa32b2cbfdf8f