Giới thiệu về VitePress

Bất kỳ dự án nào được các nhà phát triển khác sử dụng đều cần có tài liệu hướng dẫn chi tiết.

Điều quan trọng nhất đối với bất kỳ tài liệu nào là được duy trì tốt.

Vue 3 và công cụ xây dựng Vite mới cung cấp cho chúng ta một cách khác để phát triển nhanh chóng các trang web tĩnh.

Giới thiệu về VitePress.

Trong hướng dẫn nhanh này, chúng ta sẽ xem cách sử dụng VitePress để nhanh chóng tạo tài liệu cho ứng dụng Vue.

Đây là những gì chúng ta sẽ có khi hoàn thành ứng dụng.

Hào hứng?

Tôi cũng vậy. Chúng ta cùng bắt đầu nhé.

Vậy VitePress là gì?

VitePress là trình tạo trang web tĩnh chạy bằng Vue được xây dựng dựa trên Vite.

Được gọi là “em trai của Vuepress” trong tài liệu hướng dẫn (sử dụng VitePress), nó có một số ưu điểm so với đối thủ của mình.

Được xây dựng trên Vite chứ không phải webpack nên thời gian khởi động, tải lại nhanh hơn, v.v.
Sử dụng Vue 3 để giảm tải JS
Nhẹ hơn

Một lý do khiến VitePress có thể đạt được những mục tiêu này là vì nó có quan điểm riêng và cụ thể hơn nhiều so với VuePress – vốn ngày càng phức tạp hơn theo thời gian.

Mặc dù không có ý định thay thế hoàn toàn VuePress với tư cách là trình tạo trang tĩnh của Vue, VitePress cung cấp một giải pháp thay thế nhẹ hơn. Đối với hầu hết các dự án như tài liệu và các trang web đơn giản, tính cụ thể và tối giản của Vitepress sẽ giúp việc phát triển trở nên dễ dàng.

Được rồi – chúng ta hãy tạo dự án VitePress của chúng ta

Để bắt đầu sử dụng VitePress, điều đầu tiên chúng ta muốn làm là tạo thư mục.

mkdir vite-hello-world
cd vite-hello-world

Sau đó, chúng ta muốn khởi tạo trình quản lý gói và thêm VitePress – đối với hướng dẫn này, tôi sẽ sử dụng npm.

npm init
npm i --save-dev vitepress

Tiếp theo, chúng ta sẽ muốn thêm tập lệnh VitePress vào tệp package.json.

gói.json

{
    "scripts": {
        "docs:dev": "vitepress dev docs",
        "docs:build": "vitepress build docs",
        "docs:serve": "vitepress serve docs"
    }
}

Được rồi – hãy tạo một docsthư mục và tạo tệp markdown đầu tiên.

Hãy chạy ứng dụng của chúng ta.

mkdir docs
echo '# Hello World' > docs/index.md

Chúng tôi đã tạo trang web của mình! Nếu chúng tôi điều hướng đến http://localhost:3000, chúng tôi sẽ thấy tệp markdown của mình được hiển thị trên trang web!

Thật thú vị! Hãy bắt đầu tùy chỉnh trang web của chúng ta và sử dụng nhiều tính năng hơn của VitePress.

Tùy chỉnh trang web VitePress của chúng tôi

Điều hướng VitePress

Việc thêm nhiều trang vào trang VitePress của bạn cũng dễ như việc tạo thêm tệp markdown cho dự án của bạn.

Hãy tạo một vài trang và thư mục con trong dự án của chúng ta – docs/thư mục của chúng ta bây giờ sẽ trông như thế này.

Khi VitePress tạo điều hướng SPA của chúng tôi, nó sử dụng đường dẫn của từng tệp markdown để tạo tuyến đường. Ngoài ra, các tệp được đặt tên index.mdtrong bất kỳ thư mục nào cũng có thể được tham chiếu bằng /.

Ví dụ, cấu trúc tệp của chúng tôi được dịch thành các tuyến đường sau:

tài liệu/index.md

## Routing!

[docs/index.md](/) -> /

[docs/contact.md](/contact) -> /contact

[about/index.md](/about/) -> /about/

[about/our-story.md](/about/our-story) -> /about/our-story

Trong các tệp markdown của chúng tôi, chúng tôi có ba cách liên kết đến các tuyến đường. Chúng tôi có thể sử dụng url cơ sở, thêm .mdhoặc .html– tất cả sẽ liên kết đúng đến thành phần bên phải.

tài liệu/index.md

### All these options work!

[docs/contact](/contact) |
[docs/contact.md](/contact.md) |
[docs/contact.html](/contact.html)

Thêm thanh điều hướng và thanh bên vào trang web của chúng tôi

VitePress cung cấp cho chúng ta một chủ đề mặc định tuyệt vời. Nó tối giản nhưng mạnh mẽ và dễ tùy chỉnh.

Đầu tiên, chúng ta hãy thêm một số chức năng điều hướng vào trang web của mình bằng thanh bên và thanh điều hướng.

Để thực hiện việc này, chúng ta cần tạo một tệp cấu hình – chúng ta có thể thực hiện việc này bên trong một /docs/.vitepress/thư mục chứa các tệp VitePress cụ thể của chúng ta. Tệp của chúng ta sẽ được gọi ./vitepress/config.jsvà chỉ cần xuất một đối tượng JS.

.vitepress/config.js

module.exports = {
    title: 'VitePress Tutorial', // appended to all page titles
}

Bên trong đối tượng này, hãy thêm một thuộc tính có tên themeConfigtrông giống như thế này.

.vitepress/config.js

module.exports = {
    // ...
    themeConfig: {
        nav: [],
        sidebar: [],
    },
}

Để thêm các thành phần vào thanh điều hướng, chúng ta chỉ cần thêm các đối tượng vào navmảng với định dạng { text: 'ANCHOR-TEXT', link: 'PATH' }, hãy thêm liên kết đến trang chủ, trang liên hệ và trang giới thiệu.

.vitepress/config.js

module.exports = {
    nav: [
        { text: 'Home', link: '/' },
        { text: 'About', link: '/about/' },
        { text: 'Contact', link: '/contact' },
    ],
}

Để thêm vào thanh bên của chúng ta cũng giống như vậy. Hãy thêm liên kết vào một số tiêu đề của chúng ta.

.vitepress/config.js

module.exports = {
    sidebar: [{ text: 'Our Story', link: '/about/our-story' }],
}

Quay trở lại trình duyệt, chúng ta có thể thấy VitePress tạo ra thanh điều hướng và thanh bên khá đẹp mắt chỉ từ một vài dòng cấu hình.

Một điều thú vị mà chúng ta có thể làm với thanh bên của VitePress là thay đổi thanh bên tùy thuộc vào trang chúng ta đang truy cập.

Giả sử chúng ta muốn trang chủ hiển thị các tiêu đề, nhưng lại muốn tất cả các trang khác hiển thị thanh bên mà chúng ta vừa tạo.

Điều đầu tiên chúng ta phải làm là tạo cửa hàng our-storythanh bên dưới dạng một biến.

.vitepress/config.js

const primarySidebar = [{ text: 'Our Story', link: '/about/our-story' }]

Quay trở lại themeConfigđối tượng của chúng ta, chúng ta muốn thay đổi thanh bên thành một đối tượng có tên thuộc tính là đường dẫn và giá trị là một mảng thanh bên.

.vitepress/config.js

module.exports = {
    // ...
    sidebar: {
        '/about/': primarySidebar, // everything in the /about/ subdirectory
        '/contact': primarySidebar, // contact page

        // we don't need to do anything to index
        // because the default sidebar is created via page headings
    },
}

Bây giờ, nếu chúng ta kiểm tra trang web, chúng ta sẽ thấy trang chủ có thanh bên khác so với các trang còn lại.

Tuyệt vời.

Các thành phần tích hợp trong VitePress

VitePress hỗ trợ một số thành phần mà bạn có thể khai báo đơn giản trong dự án của mình thông qua config.js hoặc trực tiếp trong Markdown.

Tôi sẽ chỉ đề cập đến một số thành phần tôi thường dùng nhất ở đây. Nhấp vào đây để xem danh sách đầy đủ các thành phần.

Khối mã

Khi viết tài liệu tốt, ví dụ về mã là rất quan trọng. VitePress cung cấp một cách để nhanh chóng thêm các khối mã và cũng chỉ định ngôn ngữ lập trình đang sử dụng.

Mục lục

Thêm mục lục có thể là một cách tuyệt vời khác để giúp trang web tĩnh Vue của bạn dễ điều hướng

[[toc]]

Bảng kiểu GitHub

Có thể mất một chút thời gian để làm quen với bảng trong VitePress, nhưng tính đơn giản và khả năng thay đổi căn chỉnh các cột khiến nó trở nên hữu ích.

| Headings      |   Are    |    Centered |
| ------------- | :------: | ----------: |
| left align    | centered | right align |
| zebra striped |   rows   |        easy |

Cấu hình Markdown Frontmatter

Mặc dù chúng tôi có thể sử dụng bạn ./vuepress/config.jsđể tạo cấu hình cho toàn trang web, nhưng đôi khi chúng tôi sẽ cần kiểm soát nhiều hơn đối với từng trang riêng lẻ.

May mắn thay, chúng ta có thể kiểm soát từng trang bằng cách sử dụng khối YAML ở đầu các tệp markdown của mình. VitePress cho phép chúng ta khai báo khối này bằng cách bao quanh nó bằng ba đường đứt nét ( ---)

Ví dụ, giả sử chúng ta muốn thay đổi tiêu đề và xóa thanh bên khỏi trang Liên hệ.

---
title: Contact
---

# Contact

Điều hướng đến https://localhost:3000/contact– chúng ta có thể thấy nó hoạt động.

Có rất nhiều thứ khác nhau mà chúng ta có thể cấu hình ở đây. Kiểm tra tài liệu cho tất cả các tùy chọn Frontmatter.

Triển khai ứng dụng VitePress của bạn

Chúng ta đã thấy rằng chúng ta có thể tạo môi trường cục bộ của mình bằng cách sử dụng npm run docs:devnhưng còn việc xây dựng ứng dụng cho sản xuất thì sao?

Đầu tiên, chúng ta sẽ muốn xây dựng ứng dụng của bạn bằng lệnh

npm run dev:build

Theo mặc định, đầu ra của bản dựng sẽ là /docs/.vuepress/dist. Thư mục dist trong ví dụ của chúng tôi trông như thế này.

Sau đó, chúng ta có thể triển khai thư mục này disttới bất kỳ nền tảng nào chúng ta muốn.

Nếu muốn kiểm tra bản dựng của mình trông như thế nào, chúng ta có thể chạy hàm serve của Vitepress để tạo một máy chủ web tĩnh cục bộ.

npm run docs:serve

Phần kết luận

Và đó là những gì bạn thấy!

VitePress là một cách tuyệt vời để đảm bảo tài liệu của bạn luôn được cập nhật. Với thiết kế có chủ kiến, nó cung cấp cho bạn phương pháp nhanh chóng và dễ dàng để duy trì các trang web tĩnh của mình.

Tôi rất muốn biết bạn nghĩ gì về VitePress!