From cda0930013d2edbcfb5214fd4c121cfda2119b31 Mon Sep 17 00:00:00 2001 From: thanhtl Date: Thu, 23 Apr 2026 15:46:26 +0700 Subject: [PATCH] Update README.md --- README.md | 429 +++++++++++++++--------------------------------------- 1 file changed, 115 insertions(+), 314 deletions(-) diff --git a/README.md b/README.md index b5f57a6..71439f6 100644 --- a/README.md +++ b/README.md @@ -1,406 +1,207 @@ -<<<<<<< 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 +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 -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 +## 📌 Overview ------- +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 -/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 +git clone https://git.tltdb.com/Typora/Uploads.git ~/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 - -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: +Create `.netrc`: ```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 -``` +### Setup upload script -### 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: +Create 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: +Paste your upload script, then: ```bash 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: - -- **When Insert Local Images** → `Upload Image` -- **Image Uploader** → `Custom Command` - -Ô command nhập: +Command: ```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 -/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 -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: +Before using Typora: ```bash cd ~/typora-uploads +git pull origin main +``` + +After uploading images: + +```bash 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 -cd ~/typora-uploads 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 -cd ~/typora-uploads -git branch -M main -git push -u origin main +git pull --rebase origin main >/dev/null 2>&1 || true ``` ------- +--- -### 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: +## 📂 Repository Structure ```text Uploads/ ├── README.md └── uploads/ - └── 2026/ - └── 04/ - ├── image-a.png - ├── image-b.jpg - └── image-c.webp + └── YYYY/ + └── MM/ + ├── image-1.png + └── image-2.jpg ``` -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 -git branch -u origin/main -git config pull.rebase false -git pull origin main --allow-unrelated-histories +git pull --rebase origin main 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) +```