Xuất static site
Dùng npm run build hoặc công cụ tương đương. Demo phải chạy hoàn toàn phía trình duyệt.
SATA Tech Playground là nơi ý tưởng phải đi cùng cách làm, nhận định phải có dữ liệu, và lời giới thiệu tốt nhất là một sản phẩm chạy được. Chất công nghệ miền Nam: thẳng, nhanh, thực tế.
$ sata prove --with-demo
✓ Ý tưởng có bối cảnh thật
✓ Bài viết có lập luận & diagram
✓ Project có sản phẩm chạy được
→ nói ít hơn · cho xem nhiều hơn
Live Demo là static website gắn với một Post. SATA kiểm tra ZIP, admin đọc mô tả và chạy thử staging trước khi public.
Dùng npm run build hoặc công cụ tương đương. Demo phải chạy hoàn toàn phía trình duyệt.
index.html phải nằm ngay ở gốc ZIP. Đóng các file bên trong dist/, không ZIP thư mục cha.
Viết mô tả, hướng dẫn sử dụng và upload file .zip trong form Create Post.
Build mở trên preview origin riêng. Chỉ sau khi approve, demo mới xuất hiện trong Live Lab.
your-demo.zip
├── index.html ← bắt buộc
├── assets/
│ ├── app.js
│ └── app.css
├── images/
└── README.md ← khuyến khíchyour-demo/dist/index.html./assets/...; không hard-code domain local..env.index.html.
Khi làm tài liệu kỹ thuật, mình thường có khá nhiều file Markdown đi kèm với Mermaid, sơ đồ kiến trúc, flow xử lý hoặc Graphviz DOT.
Vấn đề là đôi khi mình chỉ muốn:
Mở một folder tài liệu → chọn file → đọc Markdown và xem diagram ngay.
Nhưng nhiều công cụ documentation lại yêu cầu NodeJS, package manager, build project hoặc phải chạy thêm server.
Vì vậy mình làm DocFlow Studio theo hướng ngược lại:
Không backend. Không build. Không cài đặt. Chỉ cần một file HTML.
DocFlow Studio là một documentation viewer/editor chạy hoàn toàn trên trình duyệt.
Chỉ cần mở:
docflow-studio.html
là có thể bắt đầu viết hoặc import tài liệu.
Mục tiêu của project là tạo một công cụ đủ nhẹ để có thể mang theo cùng source code, tài liệu hệ thống hoặc gửi cho người khác sử dụng ngay.
Có thể viết Markdown và xem kết quả render trực tiếp.
Hỗ trợ:
Không cần chạy Markdown server riêng.
Các block Mermaid trong Markdown được tự động nhận diện và render.
Ví dụ:
flowchart LR
User --> Browser
Browser --> Markdown
Markdown --> Mermaid
Mermaid --> Viewer
Có thể sử dụng cho:
Khá tiện khi viết tài liệu kiến trúc hoặc mô tả luồng xử lý.
Ngoài Mermaid, DocFlow Studio hỗ trợ luôn Graphviz DOT.
digraph G {
rankdir=LR;
users [label="Users / Admin"];
web [label="Web Layer"];
app [label="Application"];
users -> web [label="HTTPS / UI"];
web -> app [label="submit config"];
}
Các fenced block:
dot
graphviz
gv
đều có thể được nhận diện và render.
Với những diagram lớn, xem trực tiếp bên trong document thường khá khó.
Vì vậy mình làm thêm một viewer riêng cho diagram với:
Có thể mở riêng từng Mermaid hoặc Graphviz diagram để kiểm tra.
Đây là phần mình thấy hữu ích nhất khi dùng cho documentation thực tế.
Thay vì import từng file, có thể chọn luôn một folder chứa:
docs/
├── architecture.md
├── database.md
├── deployment.md
├── network.md
└── api.md
DocFlow Studio sẽ đọc các file:
.md
.markdown
.txt
Sau đó có thể tìm kiếm và chuyển qua lại giữa các file ngay trong workspace.
Nếu muốn đọc toàn bộ tài liệu liên tục, chỉ cần chọn:
Render All
Các file sẽ được ghép thành một document duy nhất.
Nội dung làm việc được lưu bằng Local Storage.
Khi đóng trình duyệt rồi mở lại, workspace trước đó có thể được khôi phục.
Folder đã import cũng được cache để hạn chế việc phải chọn lại sau mỗi lần refresh.
Project cố tình giữ stack đơn giản:
Không React.
Không NodeJS runtime.
Không database.
Không backend.
Mình không muốn DocFlow Studio trở thành một documentation platform lớn.
Mục tiêu đơn giản hơn:
Có một file HTML mà mình có thể bỏ vào bất kỳ project nào để đọc nhanh toàn bộ tài liệu kỹ thuật của project đó.
Đặc biệt hữu ích với repository có nhiều Markdown và diagram nhưng không muốn dựng thêm Docsify, Docusaurus, MkDocs hay một hệ thống documentation riêng.
Tải file về, mở trình duyệt và sử dụng.
Đó cũng là lý do toàn bộ ứng dụng được thiết kế để có thể hoạt động chỉ với một file HTML.
Project hiện vẫn đang được mình tiếp tục hoàn thiện.
Mình rất muốn nhận thêm góp ý, đặc biệt từ những bạn thường xuyên phải viết architecture docs, deployment docs, database docs hoặc technical diagrams.
Nếu mọi người thấy còn tính năng nào mà một tool documentation dạng single-file + offline nên có, cứ góp ý để mình bổ sung. 🚀
Duyệt bài, quản lý tài khoản và review Live Demo trước khi public.
Admin có thể tạo, khóa hoặc mở khóa tài khoản thành viên.
Mọi bài gửi publish đều phải được duyệt.
Đang tải dữ liệu...