Tổng quan Editor
Editor của SpecDown chạy trên Monaco — cùng engine với VS Code — mang lại trải nghiệm viết chuyên nghiệp ngay trong trình duyệt.
Bố cục Editor
Editor gồm ba panel chính:
- Cây file (trái) — điều hướng tài liệu và thư mục dự án
- Khung editor (giữa) — viết Markdown với syntax highlighting đầy đủ
- Khung preview (phải) — kết quả render trực tiếp, cập nhật khi bạn gõ
Bạn có thể bật/tắt các panel bằng thanh công cụ ở trên. Trên màn hình nhỏ, editor và preview xếp dọc.
Phím tắt
| Thao tác | Mac | Windows / Linux |
|---|---|---|
| Lưu tài liệu | ⌘ S | Ctrl + S |
| Đậm | ⌘ B | Ctrl + B |
| Nghiêng | ⌘ I | Ctrl + I |
| Tìm trong file | ⌘ F | Ctrl + F |
| Command palette | ⌘ Shift P | Ctrl + Shift + P |
| Chuyển comment | ⌘ / | Ctrl + / |
| Thụt dòng | Tab | Tab |
| Bỏ thụt dòng | Shift Tab | Shift + Tab |
| Nhân đôi dòng | ⌘ Shift D | Ctrl + Shift + D |
| Di chuyển dòng lên/xuống | ⌥ ↑/↓ | Alt + ↑/↓ |
Thao tác trên Toolbar
Chế độ chia đôi
Bật/tắt editor / preview / layout chia đôi
Chế độ preview
Preview render toàn màn hình
Chèn ảnh
Tải ảnh lên Cloudflare R2 CDN
Lịch sử phiên bản
Duyệt và khôi phục phiên bản cũ (Pro)
Liên kết ngược
Xem tài liệu nào đang trỏ tới tài liệu hiện tại
Đồ thị tài liệu
Xem các liên kết vào và ra quanh tài liệu hiện tại
Chia sẻ tài liệu
Tạo link chia sẻ công khai hoặc có mật khẩu
Phím tắt
Xem tất cả phím tắt
Hỗ trợ Markdown
SpecDown hỗ trợ đầy đủ CommonMark và các mở rộng sau:
- GitHub Flavored Markdown (bảng, gạch ngang, danh sách task)
- Khối diagram Mermaid (xem Mermaid Diagrams)
- Syntax highlighting cho 150+ ngôn ngữ trong code block
- Footnote
- Khối toán (LaTeX qua KaTeX)
- [ ] hoặc - [x] sẽ hiển thị thành checkbox đẹp ở bên preview. Click vào checkbox sẽ tự động đảo trạng thái trong Markdown và lưu lại, nên bạn có thể tick xong việc ngay trong chế độ xem mà không cần quay về editor. Trang share (chỉ xem) vẫn render đúng checkbox đó nhưng không cho phép tương tác.[ ] và [x] nằm giữa câu (ví dụ: "Session timeout (BR2) [ ]") cũng được render thành checkbox tương tác — tiện cho cờ Pass/Fail nằm trong dòng spec. Các vị trí được bỏ qua: bên trong code block, cú pháp link [x](url), và marker GFM ở đầu list item.<input value="..." /> hoặc <textarea>...</textarea> vào Markdown để tạo ô nhập trong tài liệu. Ở chế độ preview, chúng render thành ô input/textarea thật; gõ vào sẽ ghi thẳng nội dung trở lại Markdown nên giá trị được giữ nguyên khi quay về editor mode và đi vào version history.Liên kết giữa các tài liệu
Link trong Markdown có thể trỏ tới tài liệu khác cùng project, và click sẽ mở thẳng tài liệu đó — không reload, không mất share token.
Ba cú pháp đều được nhận diện:
- Đường dẫn tuyệt đối:
[Danh sách màn](/srs/screen-list)hoặc kèm extension(/srs/screen-list.md). - Đường dẫn tương đối:
[Spec 001](./SPEC-001)hoặc(../guides/oauth). - Wiki link:
[[/srs/SPEC-001]]hoặc có chữ hiển thị[[/srs/SPEC-001|Spec 001]].
- Link tới doc đang có render như link thường; click → chuyển doc ngay trong editor (hoặc trong session share project).
- Link tới đường dẫn không có doc nào sẽ render đỏ chấm chấm để dễ phát hiện link gãy khi review.
- URL ngoài (
https://…), anchor (#section), và nhúng file ([@/path]) không bị thay đổi.
Tài liệu HTML
SpecDown không chỉ dành cho Markdown — bạn có thể lưu tài liệu HTML thuần (.html) chung với .md. Để tạo, đổi toggle từ MD sang HTML trong form Tệp mới (hoặc gõ tên kết thúc bằng .html).
- Monaco tự động chuyển sang syntax highlight HTML.
- Khung preview render trong iframe sandbox: script, style, form trong HTML của bạn cách ly hoàn toàn với app chính.
- File HTML hiển thị icon code (màu hổ phách) trong cây file để dễ phân biệt.
- Rename hoạt động như Markdown — extension
.htmlđược giữ lại tự động.
body { height: 100vh; overflow: hidden } (thường gặp ở diagram tương tác, dashboard, hoặc mock single-page), preview sẽ khoá chiều cao iframe theo viewport thay vì cố grow theo body.scrollHeight. Điều này tránh được tình trạng iframe phình lên vô tận mỗi khi user click vào trong app — scroll nội bộ và click handler của bạn vẫn chạy bình thường..html riêng lẻ (hoặc file đính kèm .html cũ), URL share sẽ trả về chính file HTML đó làm toàn bộ trang — không header SpecDown, không khung bao, không iframe. Trình duyệt vào thẳng HTML của bạn. Share có mật khẩu thì hiện cổng nhập pass trước; sau khi pass đúng, URL phục vụ HTML thô y như vậy. Script trong HTML chạy ở origin sandbox nên không đọc được cookie SpecDown hay gọi API bằng session của người xem.Tải ảnh
Nhấn icon ảnh trên toolbar hoặc dán ảnh trực tiếp vào editor. Ảnh được tải lên Cloudflare R2 và chèn dưới dạng thẻ Markdown với URL CDN.
File đính kèm của dự án
Cây file giờ không chỉ chứa Markdown. Bạn có thể tải lên PDF, ảnh, video, CSV, và các file text/code như .json, .txt, .js,.tsx, hoặc .py dưới dạng file đính kèm của dự án.
- File Markdown vẫn mở trong editor đầy đủ
- File đính kèm mở trong tab chỉ xem trước
- Ảnh, PDF và video hiển thị bằng viewer tương ứng
- CSV hiển thị dưới dạng bảng
- File text/code hiển thị dưới dạng block code/text có thể đọc
.md lẫn PDF / ảnh / file nhị phân khác, tất cả sẽ nằm trong cùng một thư mục trên cây — không còn cảnh hai folder cùng tên đứng cạnh nhau, một cho doc và một cho attachment như trước.<img src="./flow.png" /> trong một file Markdown cùng folder, đường dẫn ấy sẽ trỏ đúng tới file flow.png đã upload.<img src="./flow.webp" />, đi sang folder bên cạnh bằng , hoặc dùng đường dẫn tuyệt đối trong project (/shared/diagram.svg). Trình xem sẽ tự viết lại src thành URL download của attachment tương ứng — hoạt động cả ở chế độ chỉnh sửa lẫn share.<img src="./…"> ở các file Markdown cùng folder vẫn trỏ đúng. Trong lúc kéo, cây file tự cuộn khi con trỏ đến gần mép trên/dưới, nên các folder ngoài tầm nhìn ở một danh sách dài vẫn với tới được..xlsx /.xls / .xlsm được parse ngay phía client và hiển thị thành các tab — mỗi sheet một tab, có giới hạn số dòng / cột để giao diện không bị treo với bảng quá lớn. File ZIP upload bình thường nhưng hiện thẻ "Download" thay vì preview.report.pdf, diagram.webp) chứ không cắt đuôi như trước — PDF, ảnh và các loại nhị phân dễ phân biệt khi nhìn lướt..html đã upload trong editor, ở góc phải-trên sẽ có nút Sửa như tài liệu. Click sẽ tạo một tài liệu HTML mới với cùng nội dung và mở trong tab mới — hữu ích cho file HTML đính kèm được tạo trước khi upload HTML mặc định thành tài liệu editable. File đính kèm gốc được giữ nguyên để các share link hiện tại không hỏng; xoá thủ công khi không cần nữa.Nhúng file đính kèm trực tiếp
Trong Markdown, bạn có thể tham chiếu một file đính kèm bằng cú pháp[@/path/to/file]. Ở chế độ preview, SpecDown sẽ resolve path đó và render file ngay trong nội dung.
[@/assets/architecture.pdf]
[@/media/demo.mp4]
[@/snippets/example.tsx]
[@/data/sample.csv]Nếu path không tồn tại, preview sẽ hiển thị warning block để bạn phát hiện reference hỏng ngay khi review.
Tự động lưu
Editor tự động lưu mỗi 2 giây sau khi bạn ngừng gõ. Bạn sẽ thấy chỉ báo "Saved" trên toolbar. Lưu thủ công với ⌘S sẽ kích hoạt lưu ngay và snapshot phiên bản nếu nội dung thay đổi.
Lịch sử phiên bản
Nhấn icon lịch sử để mở panel lịch sử phiên bản. Mỗi phiên bản hiển thị:
- Người đã lưu phiên bản
- Thời điểm lưu
- Chênh lệch kích thước so với phiên bản trước
- Nút Restore để quay lại phiên bản đó
Nhấn icon preview ở bất kỳ phiên bản nào để mở modal so sánh full nội dung. Modal so sánh phiên bản đó với phiên bản liền trước, highlight dòng thêm màu xanh, dòng xóa màu đỏ. Phiên bản đầu tiên hiện toàn bộ nội dung dưới dạng "thêm mới".
Sidebar lịch sử phiên bản có thể kéo để chỉnh chiều rộng — kéo mép trái của panel. Chiều rộng đã chọn được nhớ qua các phiên làm việc.
Chỉnh sửa cùng người khác
Một user chỉ được tính là "đang chỉnh sửa" sau khi gõ ít nhất 1 ký tự. Người chỉ đọc (mở tài liệu nhưng chưa gõ) không trigger cảnh báo — họ xuất hiện trong presence avatar nhưng không có badge bút chì.
Khi bạn mở 1 tài liệu mà có người đang thực sự chỉnh sửa (avatar có badge bút chì), SpecDown hiện modal cảnh báo. 3 lựa chọn:
- Vẫn chỉnh sửa — mở bình thường. Người đang edit nhận được toast cảnh báo bạn đã force-edit.
- Chỉ xem — mở read-only với badge "Chỉ xem". Khi người cuối cùng rời đi, nội dung mới nhất tự tải lại và bạn có thể chỉnh sửa.
- Yêu cầu quyền edit — gửi request tới người đang edit. Họ nhận toast Accept / Deny. Nếu Accept, bạn được edit ngay. Nếu Deny hoặc 30 giây không phản hồi, modal quay lại 3 nút để bạn chọn lại.
Toast bên người được hỏi giữ 60 giây. Nhiều người có thể cùng nhận request — ai Accept trước thì thắng.
Liên kết ngược
Nhấn icon backlinks trên header của editor để mở panel liệt kê các tài liệu đang link tới file hiện tại. Tính năng này giúp bạn nhìn nhanh chuỗi phụ thuộc trước khi đổi cấu trúc tài liệu, sửa một ADR, hoặc để AI rewrite một document quan trọng.
- Mỗi mục hiển thị tên tài liệu và full path
- Nhấn vào một mục để mở tài liệu đó trực tiếp trong editor
- Dùng cùng review status để đánh giá thay đổi có ảnh hưởng rộng hay không
Đồ thị dự án
Mở 1 tài liệu rồi bấm icon graph trên toolbar editor (icon hình mạng các node nhỏ) để xem toàn bộ tài liệu của dự án dưới dạng đồ thị force-directed. Mỗi node là 1 tài liệu; mỗi cạnh là 1 internal markdown link hoặc wikilink giữa 2 tài liệu.
- Click 1 node để mở tài liệu đó.
- Hover 1 node để highlight các tài liệu liền kề, làm mờ phần còn lại.
- Filter bằng cách gõ vào ô search (so khớp với tiêu đề tài liệu).
- Chỉ orphan hiển thị các tài liệu không có liên kết đi/đến.
- Toàn màn hình mở rộng dialog ra full màn hình cho graph lớn.
Node được tô màu theo thư mục cấp cao nhất mà tài liệu đó nằm trong, để cluster hiện rõ hơn. Các tài liệu ở root được nhóm lại với nhau.
Sẵn sàng bắt đầu?
Viết spec như code. Đồng bộ với Git. Chia sẻ với team.