VuePress: trình sinh trang tĩnh dùng Vue

VuePress là gì?

VuePress là một trình sinh trang tĩnh biên dịch các file Markdown thành một site chạy trên Vue, do Evan You — chính là người tạo ra Vue.js — đứng tên creator/lead theo danh sách contributor trên GitHub. Repo này được gắn topic tag vừa là docs-generator vừa là blog-engine, đúng với cách v1 thường được dùng trong thực tế: một đầu là tài liệu dự án, đầu kia là blog cá nhân hoặc blog nhóm.

Các tính năng cốt lõi của VuePress

• ✓Render dựa trên Vue — chính mô tả trên GitHub gọi đây là 'minimalistic Vue-powered static site generator', nghĩa là các trang được biên dịch qua Vue chứ không qua một lớp template chung chung.
• ✓Hai topic tag trên GitHub, docs-generator và blog-engine, bao trọn hai kiểu nội dung mà dự án này sinh ra để phục vụ.
• ✓SEO là một trong sáu topic gắn cho repo, cùng với static-site-generator, vue và vuepress.
• ✓Cấp phép MIT, nên việc fork hay vendor lại source code không vướng rào cản license nào.
• ✓Repo có sẵn một ví dụ thực tế: lệnh `yarn dev` trong hướng dẫn đóng góp chính là lệnh chạy site docs của VuePress — được build bằng chính VuePress.
• ✓Có một showcase cộng đồng thật: danh sách Awesome VuePress và trang vuepress.tools, do Ahmad Mostafa xây dựng, đều liệt kê các site và plugin thực tế.

Bạn có thể xây dựng gì với VuePress

• •Site tài liệu — repo được gắn tag docs-generator, và chính docs của VuePress cũng được build bằng VuePress (lệnh `yarn dev` trong hướng dẫn đóng góp phục vụ đúng site docs này).
• •Blog — được gắn tag blog-engine riêng, dành cho team muốn bài viết Markdown chạy qua cùng pipeline dựa trên Vue như phần docs.
• •Bất cứ thứ gì cộng đồng đã chứng minh được — danh sách Awesome VuePress và thư mục vuepress.tools do cộng đồng vận hành liệt kê các site thực tế, vượt ra ngoài khuôn khổ docs/blog mà các tag trên GitHub gợi ý.

Lựa chọn thay thế cho VuePress

Ai nên vẫn cân nhắc dùng VuePress v1

Phù hợp nhất với những team đang chạy sẵn một site VuePress v1 và cần nó tiếp tục hoạt động, không phải team đang bắt đầu dự án mới. Nếu bạn đang duy trì một dự án có docs nằm trên VuePress v1, tiếp tục dùng thêm một thời gian là hợp lý vì trình sinh trang vẫn hoạt động tốt, còn lộ trình nâng cấp (VitePress hoặc VuePress v2) là một dự án migrate thật sự chứ không phải thay thế kiểu drop-in. Nếu bạn đang chọn công cụ docs cho một dự án Vue mới, chính thông báo bảo trì trong README đã là câu trả lời: hãy bắt đầu với VitePress.

Câu hỏi thường gặp

Vấn đề mà VuePress giải quyết

Các team Vue.js muốn có site docs hoặc blog xây dựng từ bên trong chính hệ sinh thái của mình — thay vì kéo thêm một trình sinh trang dựa trên React như Gatsby hay Docusaurus — cần một lựa chọn chạy trên Vue, và VuePress chính là lựa chọn đó, được Evan You xây dựng và dẫn dắt ban đầu. Cùng chính repo này giờ lại nói thẳng rằng cách tiếp cận của v1 đã bị thay thế: phần đầu README là một thông báo bảo trì trỏ sang VitePress và VuePress v2, nên bài toán mà VuePress v1 giải hôm nay hẹp hơn nhiều so với lúc Evan You xây dựng nó — chủ yếu là giữ cho các site docs Vue cũ tiếp tục chạy, chứ không phải để bắt đầu site mới.

Cách cài đặt / dùng thử

Các bước cài đặt để thêm VuePress vào dự án của bạn không nằm trong README này — nó chỉ hướng dẫn cách setup chính repo VuePress để đóng góp code (`yarn install`, sau đó `yarn dev` để chạy site docs của VuePress bằng chính VuePress, và `yarn test` để chạy bộ test). Còn cách dùng thực tế như một dependency thì README trỏ sang site docs riêng tại vuepress.vuejs.org thay vì liệt kê lệnh npm hay yarn ở đây. Nếu không muốn clone code về máy, README cũng có sẵn một môi trường Gitpod để xem source ngay trên trình duyệt.

Cách sử dụng

Cách dùng hằng ngày — viết Markdown, cấu hình theme, chạy build — cũng không được ghi trong README này; nội dung đó nằm ở site docs riêng được link từ repo. Điều README có ghi là quy trình đóng góp: chạy bộ test bằng `yarn test` trước khi gửi thay đổi, và nếu bạn đề xuất một thay đổi 'substantial' cho chính VuePress hoặc phần docs của nó, dự án yêu cầu bạn viết RFC trước thay vì mở pull request trực tiếp.

Repo liên quan