Cách xây dựng hệ thống tài liệu với Vue và VuePress
Tài liệu tốt là một phần quan trọng của một dự án thành công, nhưng một hệ thống tài liệu đầy đủ có thể liên quan nhiều hơn dự án mà bạn yêu cầu. Trong trường hợp này, các trang tĩnh thường hoạt động tốt. Trong bài đăng này, ta sẽ xây dựng một trang web tài liệu tĩnh, đây cũng là một ứng dụng trang đơn bằng cách sử dụng trình tạo trang web tĩnh được cấp nguồn Vue , VuePress .Trang web tĩnh
Trang web tĩnh là trang web được phục vụ khi chúng được lưu trữ. Không có sự tương tác trực tiếp giữa client - server ngoại trừ từ các ứng dụng của bên thứ ba được nhúng. Các trình tạo trang tĩnh có rất nhiều trên internet và mỗi loại đều khác với những phần mềm khác. Một số ưu tiên tốc độ và thời gian tải hơn là tính linh hoạt, và một số khác thì quảng cáo chức năng mở rộng. Các trang web tĩnh được ưa thích hơn vì tốc độ tăng của chúng và việc không có server sẽ giảm thiểu khả năng xảy ra lỗi bảo mật.
VuePress có tính năng tạo trang web tĩnh cũng như chủ đề mặc định phù hợp để nhanh chóng xây dựng các trang web tài liệu. Trong hướng dẫn này, ta sẽ sử dụng chủ đề tài liệu mặc định để xây dựng hệ thống của ta .
VuePress
Theo mặc định, các file đánh dấu VuePress Parses được cấu trúc trong các folder thành các file HTML sẽ được phân phát. VuePress tàu ra khỏi hộp với Vue, Vue Router để tạo các tuyến đường riêng, và webpack cho bundling tài sản. Trong quá trình xây dựng, mỗi file đánh dấu được tạo được phân tích cú pháp dưới dạng mẫu Vue, trong khi nội dung được gói bởi webpack. Việc phân tích cú pháp các file đánh dấu thành các mẫu Vue tạo ra một lối đi mà bạn có thể sử dụng để chuyển trong các tập lệnh Vue root ở dạng các thành phần file duy nhất.
VuePress thân thiện với SEO và theo mặc định cung cấp một phương tiện để triển khai theo dõi phân tích bằng cách sử dụng Google analytics trên các trang web . Ngoài ra, VuePress cung cấp một hệ thống tìm kiếm tối thiểu lập index tất cả các tiêu đề trên trang web và hiển thị chúng khi tìm kiếm.
Mặc dù VuePress đi kèm với bố cục đáp ứng mặc định cho tài liệu, nó cũng hỗ trợ bố cục tùy chỉnh để tạo kiểu. Đối với bài đăng này, ta sẽ xây dựng một hệ thống tài liệu tối thiểu bằng cách sử dụng chủ đề mặc định cũng như triển khai tính năng Vue in Markdown , bằng cách xây dựng một bộ đếm đơn giản thành một file đánh dấu.
Yêu cầu
Đối với hướng dẫn này, bạn phải có kiến thức cơ bản về HTML, CSS và JavaScript. Kiến thức về Vue cũng hữu ích nhưng không bắt buộc.
Cài đặt
Đối với dự án này, bạn sẽ yêu cầu Node và trình quản lý gói npm của nó. Kiểm tra xem bạn đã cài đặt nó trên terminal của bạn chưa bằng lệnh:
node -v && npm -v Điều này hiển thị các version đã cài đặt của nút và npm tương ứng. Nếu bạn chưa cài đặt, bạn có thể download từ đây .
Tiếp theo, tạo một dự án mới. Tạo một folder mới và thay đổi thành folder đó:
mkdir vuepress && cd $_ Khởi tạo một dự án nút mới trong folder vuepress :
npm init -y Thao tác này nhanh chóng tạo ra một dự án mới và tạo file package.json.
Tiếp theo, ta cài đặt VuePress local với:
npm install -D vuepress Sau khi VuePress được cài đặt trong dự án, bạn có mọi thứ bạn cần, vì VuePress đi kèm với chủ đề tài liệu mặc định được sử dụng cho dự án này. Tuy nhiên, ta muốn tùy chỉnh tài liệu cho phù hợp với yêu cầu của ta , vì vậy tiếp theo bạn sẽ tạo các folder và file với văn bản giả.
Tạo folder và file
Hãy cẩn thận khi tạo folder trong VuePress, vì nó đánh giá các folder và file đánh dấu theo cách sắp xếp của chúng. Mỗi file đánh dấu trong một folder sẽ biên dịch thành một trang HTML với đường dẫn là folder mẹ.
Đầu tiên, hãy tạo một folder docs để chứa tất cả nội dung tài liệu và cấu hình:
mkdir docs && cd $_ Trong folder docs, hãy tạo folder .vuepress và các folder tài liệu chứa các file - bộ counter và guide .
Để các tuyến này hoạt động, chúng yêu cầu file
README.mdtrong mỗi folder . Điều này phục vụ như một tuyến đường về nhà đến tiểu mục cụ thể đó.
Thư mục bộ counter chứa các file đánh dấu sẽ được phân tích cú pháp cũng như các file README.md mặc định cho trang chủ. Thư mục guide chứa các nội dung tương tự như folder bộ counter .
Thư mục .vuepress folder thành phần, folder dist được tạo trên bản dựng và file config.js được sử dụng để cấu hình hệ thống tổng thể.
Tạo các thành phần Vue
Đối với dự án này, ta sẽ xây dựng một bộ đếm đơn giản bằng cách sử dụng Vue. Tạo hai thành phần Vue với hậu tố .vue có tên là counter.vue và my-header.vue . Các thành phần này sẽ đóng role là một thành phần bộ đếm và một tiêu đề đơn giản tương ứng. Trong my-header.vue , hãy chỉnh sửa tập lệnh vue:
<template> <div> <h1>This Header is actually a Vue Template</h1> </div> </template> <script> </script> <style scoped> </style> Chỉnh sửa tập lệnh counter.vue như thế này:
<template> <div class="counter"> <h1>{{number}}</h1> <button @click = "increment">Increment</button> <button @click = "decrement">Decrement</button> </div> </template> <script> export default { data(){ return{ number: 0, } }, methods:{ increment(){ if(this.number >= 0){ this.number++ } }, decrement(){ if(this.number > 0){ this.number -- } } } } </script> <style scoped> .counter{ display: inline-block; margin-left: 30%; } button{ display: inline-block; padding: 20px; margin: 10px; font-weight: bold; border-radius: 5px; box-shadow: 0px 0px 5px 0px rgb(11, 11, 114); } h1{ text-align: center; } </style> Thành phần này chứa mọi thứ bạn cần cho bộ đếm. Các thành phần Vue hiện đã sẵn sàng để sử dụng.
Tạo file Markdown
Tiếp theo, tạo file đánh dấu trong bộ counter và folder guide . Xem các file đánh dấu để biết bộ đếm và hướng dẫn . Frontmatter được sử dụng để đặt động tiêu đề của các trang riêng lẻ. Thành phần <counter/> cũng được đặt trong file đánh dấu.
Các file này sau đó sẽ được chuyển thành các trang tĩnh. Đối với trang web của ta , ta cũng sẽ đòi hỏi một README.md file markdown để phục vụ như trang chủ. Frontmatter trong các file đánh dấu được sử dụng để đặt một số thuộc tính động của trang chủ. Tạo file README.md trong folder docs và chỉnh sửa nó thành:
--- home: true actionText: See Counter App actionLink: /counter/counter-app features: - title: Embedded Vue Counter details: A Vue counter developed using Vue is embedded in this doc, now that's the power of VuePress! - title: Fun Docs made with VuePress details: This entire doc was basically made with VuePress which parsed markdown files and corresponding assets using webpack. footer: Developed using VuePress by William Imoh --- Tiếp theo, đặt thành phần my-header Vue trong tuyến chính. Chỉnh sửa file README.md để bao gồm thành phần:
--- home: true actionText: See Counter App actionLink: /counter/counter-app features: - title: Embedded Vue Counter details: A Vue counter developed using Vue is embedded in this doc, now that's the power of VuePress! - title: Fun Docs made with VuePress details: This entire doc was basically made with VuePress which parsed markdown files and corresponding assets using webpack. footer: Developed using VuePress by William Imoh --- <my-header></my-header> Đến đây bạn có tất cả các file Markdown cần thiết. Hãy tiến hành cấu hình chuyển và thanh bên bằng .vuepress/config.js .
Cấu hình bố cục
Tệp config.js được sử dụng để tùy chỉnh hệ thống tài liệu. Khi tạo hệ thống tùy chỉnh này, ta xuất một đối tượng chứa các trường bắt buộc:
module.exports = { title: 'VuePress', description: "A demo documentation using VuePress", themeConfig:{ nav: [ { text: 'COUNTER', link: '/counter/' }, { text: 'GUIDE', link: '/guide/' }, ], sidebar: [ { title: 'Counter', collapsable: false, children: [ '/counter/counter-app' ] }, { title: 'API Guide', collapsable: false, children: [ '/guide/guide', '/guide/api' ] } ] } } Đầu tiên, ta chỉ định tiêu đề của trang web và gán cho nó một mô tả, điều này rất tốt cho SEO. Tiêu đề và mô tả này tự động cung cấp hệ thống tìm kiếm được lập index trên trang web với thanh tìm kiếm.
Tiếp theo trong script là đối tượng themeConfig , đối tượng này nhận các tham số cần thiết để triển khai một số chức năng trên chủ đề. Để tạo thanh chuyển , ta tạo một mảng nav chứa các đối tượng chỉ định văn bản hiển thị và tuyến đường của mỗi phần tử chuyển . Bạn có thể xem thêm về cách cấu hình chủ đề mặc định tại đây .
Ta đã sử dụng các thanh bên được group lại để user có thể xem nhanh menu bất kỳ lúc nào trong tài liệu. Menu sidebar có thể được cài đặt để sụp đổ theo mặc định bằng cách sử dụng collapsable tài sản trên group thanh bên. Bạn có thể tìm thêm trên thanh bên ở đây .
Bây giờ ta đã cài đặt mọi thứ, để bắt đầu một server phát triển, hãy chạy:
vuepress dev docs Server nhà phát triển local được lưu trữ trên cổng 8080. VuePress đi kèm với tính năng reload nóng, thực hiện bất kỳ thay đổi nào được thực hiện đối với ứng dụng trong quá trình phát triển.
Khởi động lại server phát triển là bắt buộc nếu các thành phần Vue được tạo trong khi server phát triển local đang hoạt động.
Bây giờ ta có một server nhà phát triển đang chạy, mục tiêu là để triển khai trang web. Để dọn dẹp mọi thứ một chút, hãy chỉnh sửa file package.json để bao gồm các lệnh phát triển cũng như các lệnh xây dựng. Chỉnh sửa file package.json thành:
{ "name": "vuepress", "version": "1.0.0", "description": "", "main": "index.js", "scripts": { "test": "echo \"Error: no test specified\" && exit 1", "docs:dev": "vuepress dev docs", "docs:build": "vuepress build docs" }, "keywords": [], "author": "", "license": "MIT", "devDependencies": { "vuepress": "^0.5.0" } } Để tạo các file tĩnh, bây giờ ta có thể chạy:
npm run docs:build Quá trình này có thể mất một lúc để tạo, sau đó bạn có thể tìm thấy các file tĩnh được tạo trong .vuepress/dist
Thay đổi kiểu
VuePress hỗ trợ các file tĩnh cũng như nội dung webpack và cẩn thận đảm bảo rằng URL được chỉ định cho nội dung trong markdown là chính xác trước khi xây dựng. Đối với trường hợp của ta , ta chỉ cần chỉnh sửa lại màu cơ bản một chút. Ta sẽ overrides các màu mặc định bằng cách sử dụng các kiểu.
Tạo một file mới có tên override.styl trong docs/.vuepress . Trong khi sử dụng các tên biến được chỉ định cho màu như đã nêu trong tài liệu chính thức, ta chỉnh sửa tập lệnh override.styl để thay đổi accentColor bằng:
$accentColor = #cfa809 $textColor = #2c3e50 $borderColor = #eaecef $codeBgColor = #282c34 Khởi động lại server phát triển với:
npm run docs:dev Lưu ý các thay đổi được thực hiện đối với file kiểu được phản ánh trong trình duyệt ngay lập tức.
Hiện ta đã hoàn thiện hệ thống tài liệu với các trang riêng lẻ.
Triển khai để Netlify
Tiếp theo, bạn sẽ triển khai trang web tĩnh bằng Netlify . Netlify cung cấp tùy chọn tích hợp liên tục bằng cách triển khai từ Github hoặc bất kỳ nhà cung cấp dịch vụ kiểm soát version được lưu trữ được hỗ trợ nào khác. Làm theo các bước sau để triển khai trang web với Netlify:
Bước 1
Tạo account trên Github và Netlify. Đẩy mã của bạn bằng Git lên Github.
Bước 2
Đăng nhập account Netlify của bạn và chọn tùy chọn 'Trang web mới từ Git'. Chọn Github làm nhà cung cấp phát triển liên tục và chọn kho chứa tài liệu.
Bước 3
Chỉ định nhánh để triển khai dưới dạng chính hoặc chọn bất kỳ nhánh nào bạn muốn triển khai. Đặt lệnh xây dựng thành npm run docs: build và folder xuất bản thành docs / .vuepress / dist. Nhấp vào 'Triển khai trang web'. Trang web sẽ được triển khai trong thời gian ngắn và một URL công khai được cung cấp để truy cập nó.
Đây là phiên bản đã triển khai của hướng dẫn này trên Netlify.
Kết luận
Các trang web tĩnh được coi là hữu ích về tốc độ, bảo mật và khả năng bảo trì của chúng. Trong hướng dẫn này, ta đã phát triển một trang web tài liệu tĩnh, cũng là một ứng dụng được phân trang duy nhất, sử dụng VuePress. VuePress cung cấp sự linh hoạt trong việc viết các tập lệnh Vue bên trong các file Markdown để đưa tính năng động vào các trang web tĩnh. Vui lòng sửa đổi dự án để bao gồm một số folder và file đánh dấu tương ứng. Chúc bạn viết mã vui vẻ!
Các tin liên quan
