Skip to main content

Tạo trang Vitepress

Bắt đầu với Vitepress để tạo trang blog của bạn​

Bạn đã nghe về Vitepress chưa , nhưng bạn vẫn chưa kiểm tra nó? Vâng, trong bài viết này, chúng tôi sẽ đề cập đến thiết lập cơ bản và chia sẻ tất cả những điều ồn ào về trình tạo trang web tĩnh tuyệt vời mới này.

Nếu bạn đang tìm kiếm thứ gì đó cho phép bạn nhanh chóng tạo một trang web tĩnh có hỗ trợ Markdown, tìm kiếm, chủ đề Sáng/Tối, quảng cáo, điều hướng và nhiều tính năng khác, thì Vitepress chính là thứ bạn đang tìm kiếm.

Giả sử bạn muốn chứng minh sức mạnh của Vitepress mà không cần phải đầu tư thêm thời gian, tôi khuyên bạn nên truy cập trang web chính của Vitepress ( vitepress.dev ) và trải nghiệm những gì Vitepress có thể làm, vì trang web chính thức được xây dựng trên nền tảng Vitepress!

Trang web Vitepress

Vitepress là một trình tạo trang tĩnh mạnh mẽ do Vite cung cấp , chủ yếu được sử dụng cho Tài liệu và Blog với chủ đề mặc định và có thể tùy chỉnh để sử dụng cho bất kỳ mục đích nào bạn cần với các chủ đề tùy chỉnh và ghi đè chủ đề. Sức mạnh của Vitepress đến từ đường cong học tập thấp, cài đặt cấu hình mạnh mẽ và khả năng tùy chỉnh dễ dàng.

Ví dụ, tính năng quốc tế hóa được tích hợp sẵn, tính năng chuyển đổi chủ đề được tích hợp sẵn và thậm chí tìm kiếm toàn bộ trang web cũng chỉ cần một dòng duy nhất trong cấu hình để thiết lập.

Điều làm cho Vitepress trở nên mạnh mẽ chính là cấu hình mở rộng và khả năng tùy chỉnh bằng cách ghi đè lên chủ đề hiện có, tự tạo chủ đề của riêng bạn hoặc chỉ cần nâng cao các trang bằng mã Vue tùy chỉnh.

Điều kiện tiên quyết​

Để chạy thành công bản demo sau, bạn sẽ cần:

  • Node.js phiên bản 18 trở lên.
  • Thiết bị đầu cuối để truy cập VitePress thông qua giao diện dòng lệnh (CLI).
  • Trình soạn thảo văn bản có hỗ trợ cú pháp Markdown.
  • Nên sử dụng VSCode cùng với tiện ích mở rộng Vue chính thức.

Tạo dự án của bạn​

Để tạo dự án, chúng ta sẽ làm theo các bước được trình bày trong hướng dẫn Bắt đầu chính thức .

Nếu bạn muốn thiết lập dự án Vitepress nhanh chóng, hãy thực hiện theo các bước sau:

  • Tạo một thư mục mớimkdir vitepress-tutorial
  • Truy cập vào thư mụccd vitepress-tutorial
  • Cài đặt Vitepressnpm add -D vitepress
  • Chạy trình hướng dẫnnpx vitepress init
  • Trả lời các câu hỏi:
    • VitePress nên khởi tạo cấu hình ở đâu?
    • Tiêu đề trang web
    • Mô tả trang web
    • Chủ đề
    • Bạn có muốn hỗ trợ Typescript không?
  • chạynpm run docs:dev
  • Tận hưởng trang web của bạn.

Sau khi bạn thực hiện các bước trên, Vitepress của bạn sẽ sẵn sàng và chạy như hình dưới đây

Cài đặt Vitepress mới

Những gì có sẵn ngay khi mở hộp​

Trang web được thiết lập đầy đủ với đủ để bạn bắt đầu. Hãy cùng xem những tính năng nào có trong phần mềm:

  • Thanh điều hướng: Trang web có thanh điều hướng bao gồm các liên kết đến các trang blog của chúng tôi
  • Chủ đề sáng/tối: Chủ đề sáng tạo
  • Trang chủ: Bố cục trang chủ cơ bản
  • Blog: Hai bài đăng blog khác nhau với thanh điều hướng bên

Tất cả những điều trên đều có sẵn chỉ với 4 tệp! Hãy cùng tiến lên và xem cách tùy chỉnh ứng dụng của chúng ta.

Ghi đè trang chủ​

Đã đến lúc sửa đổi trang web của chúng ta bằng cách truy cập vào các thư mục của nó. Điều bạn có thể nhận thấy khi mở trang web là Vitepress tuân theo một cấu trúc tệp rất đơn giản, trên thực tế, một cài đặt mới chỉ bao gồm 4 tệp bổ sung trên các tệp dự kiến package.jsonvà node_modules.

Hãy cập nhật trang chủ của chúng ta để làm cho nó độc đáo hơn. Vì Vitepress tuân theo " bộ định tuyến dựa trên hệ thống tệp ", chúng ta có thể tìm thấy tệp này trong thư mục gốc của dự án trong tệp có tên là index.md. Tệp này sẽ có thể truy cập được tại "/" hoặc "/index.html" của trang web của bạn.

Nội dung của tập tin như sau:

--- # https://vitepress.dev/reference/default-theme-home-page layout: home hero: name: "Vitepress tutorial" text: "A VitePress Site" tagline: My great project tagline actions: - theme: brand text: Markdown Examples link: /markdown-examples - theme: alt text: API Examples link: /api-examples features: - title: Feature A details: Lorem ipsum dolor sit amet, consectetur adipiscing elit - title: Feature B details: Lorem ipsum dolor sit amet, consectetur adipiscing elit - title: Feature C details: Lorem ipsum dolor sit amet, consectetur adipiscing elit ---

Như bạn thấy, tệp không có mã nào trong đó và nó chỉ được điều khiển bởi cấu hình hoặc cụ thể hơn trong trường hợp này là Markdown frontmatter , tức là một tập hợp các cấu hình được các tệp markdown chấp nhận giúp bạn thiết lập các tùy chọn như tiêu đề, mô tả, og:image. Chúng tôi sẽ mô tả frontmatter chi tiết hơn ở phần sau của bài viết.

Trước khi chúng ta bắt đầu sửa đổi cấu hình của tệp, bạn nên biết rằng Vitepress có một trang tài liệu rất chi tiết và rộng rãi, nơi bạn có thể tìm thấy trợ giúp nếu bạn gặp khó khăn hoặc muốn tìm hiểu thêm. Trong trường hợp này, chúng tôi đang ghi đè trang "home", vì vậy tài liệu có thể được tìm thấy tại đây: Cấu hình chủ đề mặc định của trang chủ .

Nếu bạn đọc tệp hiện tại trong trang chủ, bạn sẽ thấy rằng nó định nghĩa "bố cục" của "trang chủ". Bố cục này hiển thị tiêu đề chính với CTA và một tập hợp các khối tính năng.

Có ba bố cục khác nhau có sẵn trong chủ đề Mặc định: "trang chủ", "tài liệu" và "trang".

Tiêu đề và mô tả đã được thiết lập từ thông tin chúng tôi cung cấp từ trình hướng dẫn cài đặt. Nhưng phần còn lại chỉ là mẫu boiler cơ bản. Hãy xem chúng ta có thể thay đổi những gì:

  1. Thêm hình ảnh anh hùng. Hình ảnh này có thể được lấy từ nguồn bên ngoài hoặc được lưu trong kho lưu trữ.
hero: name: "Vitepress tutorial" text: "A VitePress Site" tagline: My great project tagline image: src: 'assets/logo.png' alt: 'My logo'
  1. Cập nhật các nút hành động.
actions: - theme: brand text: First Blog link: /first - theme: alt text: Thisdot.co link: https://thisdot.co

Như được hiển thị ở trên, các nút Hành động có hai chủ đề "thương hiệu" hoặc "alt" và có thể chấp nhận liên kết nội bộ hoặc liên kết bên ngoài.

Vitepress đủ thông minh để thiết lập các liên kết ngoài mở trong một tab mới và thiết lập rel="noreferrer".

DOM hình ảnh của nút bên ngoài được hiển thị

  1. Thay đổi các khối tính năng:

Các khối tính năng rất tuyệt vời để thu hút người dùng và cho họ biết điều gì làm cho trang web của bạn trở nên đặc biệt. Điều này chấp nhận một biểu tượng và một số văn bản, vì vậy hãy thay đổi biểu tượng của chúng ta bằng những điều sau:

features: - icon: 🏚️ title: Your Documentation house details: This is the house of your documentation - icon: src: https://emojipedia.org/house title: This is the logo details: Nothing else to say

Trang chủ hiện đã hoàn thành và được cập nhật và sẽ trông như thế này: Trang chủ Vitepress được thiết kế lại

Xin lưu ý rằng những gì chúng tôi đã làm trên trang chủ chỉ là thay đổi phần đầu markdown của bố cục "home". Điều này có nghĩa là nếu bạn muốn, bạn có thể dễ dàng tùy chỉnh trang hơn nữa bằng cách thêm nhiều khối vào tệp bố cục hoặc thực sự bằng cách viết và định dạng phần còn lại của trang như bình thường.

Cấu hình trang web​

Ở bước này, chúng ta sẽ tìm hiểu về cấu hình trang web chính và cách sử dụng nó để tùy chỉnh trang web của mình.

Bạn có thể tìm thấy tệp cấu hình trong .vitepressthư mục có tên "config.mjs".

Giống như bố cục trang chủ, cấu hình được sử dụng trong tệp cài đặt sẵn rất dễ hiểu:

import { defineConfig } from 'vitepress' // https://vitepress.dev/reference/site-config export default defineConfig({ title: "Vitepress tutorial", description: "A VitePress Site", themeConfig: { // https://vitepress.dev/reference/default-theme-config nav: [ { text: 'Home', link: '/' }, { text: 'Examples', link: '/markdown-examples' } ], sidebar: [ { text: 'Examples', items: [ { text: 'Markdown Examples', link: '/markdown-examples' }, { text: 'Runtime API Examples', link: '/api-examples' } ] } ], socialLinks: [ { icon: 'github', link: 'https://github.com/vuejs/vitepress' } ] } })

Tệp này rất quan trọng và bạn có thể sẽ phải mở nó mọi lúc vì nó sẽ chịu trách nhiệm về bố cục của thanh điều hướng bên trong trang web của bạn.

Trong phần này, chúng ta sẽ tìm hiểu cách sử dụng tệp cấu hình Vitepress để đạt được mục đích sau:

  • Sửa đổi điều hướng thanh bên
  • Bật Tìm kiếm
  • Thêm Favicon vào trang web của bạn

Thanh bên là thành phần hiển thị ở phía bên trái của các trang blog. Thành phần này không được tạo tự động mà được thiết lập thủ công trong tệp này.

Bạn có thể có nhiều hơn một thanh điều hướng, ví dụ, bạn có thể chỉ định thanh điều hướng bên hiển thị trong các trang có "/blog/" trong đường dẫn và một thanh điều hướng khác cho tất cả các trang đánh dấu có "/tutorials/".

Hãy cùng xem cách thực hiện điều này:

{ sidebar: { '/blog/': [ { text: 'Blog', items: [ { text: 'Index', link: '/blog/' }, { text: 'One', link: '/blog/one' } ] } ], '/tutorials/': [ { text: 'Tutorial', items: [ { text: 'Index', link: '/tutorials/' }, { text: 'Two', link: '/tutorials/two' } ] } ] }, }

Với đoạn mã trên, sẽ có 2 thanh bên khác nhau. Một thanh sẽ chỉ hiển thị nếu URL bao gồm "/blog" và thanh còn lại sẽ hiển thị nếu đường dẫn bao gồm "tutorials".

Nhấp vào các mục trên sẽ đưa ra lỗi 404 vì chúng tôi không có bất kỳ trang nào ở vị trí cụ thể đó. Tuy nhiên, chúng tôi có thể dễ dàng khắc phục sự cố bằng cách tạo hai thư mục "blog" và "tutorial" và tạo các tệp cần thiết trong các thư mục này trong trường hợp của chúng tôi là "index.md" và "one.md" cho blog và "index.md" và "two.md" cho hướng dẫn.

Thanh bên có các thiết lập khác như khả năng tạo cây lồng nhau hoặc tạo menu có thể thu gọn. Bạn có thể tìm hiểu thêm bằng cách xem tài liệu chính thức về thanh bên chủ đề mặc định .

Bật Tìm kiếm​

Không có tài liệu hoặc trang blog nào được coi là hoàn chỉnh cho đến khi tìm kiếm được triển khai đầy đủ trên đó. May mắn cho chúng tôi, việc kích hoạt tìm kiếm trên toàn trang web cực kỳ đơn giản với Vitepress.

Vitepress hỗ trợ hai loại tìm kiếm khác nhau: tìm kiếm toàn văn bản bằng minisearch và tìm kiếm dựa trên Algolia .

Trong hướng dẫn này, chúng tôi sẽ bật tìm kiếm toàn văn. Tính năng này được tích hợp đầy đủ và không yêu cầu tài khoản bên ngoài.

Để bật tìm kiếm, chúng ta cần thêm tham số "Tìm kiếm" vào themeConfigvà đặt providerthành "local". Chúng ta có thể thêm tham số này ngay bên dưới socialLinks.

socialLinks: [ { icon: 'github', link: 'https://github.com/vuejs/vitepress' } ], search: { provider: 'local' } }

Chỉ cần thay đổi cấu hình đơn giản, trang web của chúng ta sẽ có chức năng tìm kiếm toàn trang hoạt động như hình dưới đây: Tìm kiếm toàn bộ trang web của Vitepress

Tài liệu tìm kiếm chính thức có thêm thông tin về giao diện và chức năng của tìm kiếm.

Thêm Favicon vào trang web của bạn​

Ngay cả khi cấu hình trang web rất rộng, vẫn có lúc bạn cần thêm một số thứ không có sẵn vào trang web.

Trong phần này chúng ta sẽ tìm hiểu cách thêm các thuộc tính cụ thể vào <head>trang web và đặc biệt là cách thêm biểu tượng yêu thích.

Để thêm các giá trị tùy chỉnh vào phần đầu, chúng ta sẽ sử dụng thuộc tính "head" có sẵn trong cấu hình Vitepress.

Cấu hình "head" là một mảng chấp nhận một mảng có kiểu phần tử (ví dụ: liên kết, tập lệnh, siêu dữ liệu) và một đối tượng bao gồm tất cả các thuộc tính cho phần tử cụ thể đó.

Ví dụ để sao chép mã HTML sau:

<link rel="icon" href="/image/favicon.ico"/>

chúng ta sẽ định nghĩa cấu hình đầu sau:

head: [ [ 'link', { rel: 'icon', href: '/images/favicon.ico' } ], ]

Chúng ta có thể sử dụng kỹ thuật này để thiết lập siêu dữ liệu và thậm chí tải phông chữ hoặc Google Analytics . Thông tin thêm trong phần đầu site-config

Viết bài đăng của bạn​

Trong phần cuối của bài viết này, chúng ta sẽ tìm hiểu cách viết một bài đăng trên blog và cách tùy chỉnh các trang bằng JS và các kiểu.

Viết trang đầu tiên của bạn​

Trong phần trước, chúng ta đã tạo một vài tệp markdown, nhưng hiện tại chúng đang trống. Hãy cùng xem cách tạo tài liệu đẹp bằng tính năng tích hợp của Vitepress.

Trong phần này, chúng ta sẽ làm việc trên tệp được lưu trữ trong /blog/index.md. Bạn có thể truy cập tệp này trong trình duyệt của mình bằng cách truy cập " http://localhost:5174/blog/index.html ".

Blog Nội dung chính​

Mỗi tệp cần có frontmatter được xác định. Điều này được sử dụng để xác định thông tin cơ bản trên trang, chẳng hạn như tiêu đề, mô tả và nhiều thông tin khác.

Để có kết quả SEO tốt nhất, cách tốt nhất là luôn xác định tiêu đề và mô tả cho trang mới. Chúng ta có thể thực hiện điều này bằng cách thêm mã sau vào đầu tệp của mình:

--- title: My Blog post title description: My unique description ---

Phần đầu trong các tệp Markdown được phân cách bằng dấu "---". Trong đoạn mã trên, chúng ta đặt tiêu đề và mô tả.

Vitepress frontmatter hỗ trợ thêm các cấu hình như lastUpdates, sidebar, outline, v.v. Bạn có thể tìm thông tin trong tài liệu frontmatter-config .

Frontmatter có một số cấu hình toàn cục, chẳng hạn như tiêu đề và mô tả, nhưng cũng có các thiết lập "cụ thể cho bố cục" chỉ khả dụng trên các bố cục cụ thể. Điều này được giải thích rõ ràng trong tài liệu.

Blog Đánh dấu​

Bây giờ phần nội dung bài đăng của chúng ta đã được thiết lập, đã đến lúc viết nội dung của nó. Việc này được thực hiện bằng cách sử dụng một công cụ đánh dấu rất rộng rãi.

Hãy bắt đầu với những điều cơ bản và viết một tiêu đề có nội dung và liên kết như hiển thị bên dưới:

## My heading one My text [link](thisdot.co)

Sau khi lưu, môi trường phát triển của chúng ta sẽ hiển thị kết quả sau:

Bài đăng trên blog với markdown cơ bản

Hãy thêm một vài tiêu đề và mục lục vào tài liệu của chúng ta bằng cách sử dụng [[toc]] ở đầu trang:

My Table of Contents: [[toc]] ## first heading My text [link](thisdot.co) ### inner heading 3 ## second heading My text [link](thisdot.co)

Phần trên sẽ tạo ra một danh sách không có thứ tự với tất cả các liên kết của chúng tôi. Mục lục

Tính năng cuối cùng mà tôi muốn chia sẻ về công cụ markdown Vitepress là trình biên tập mã. Công cụ markdown được sử dụng trong Vitepress cung cấp nhiều tính năng mở rộng khi nói đến việc kết xuất mã.

Các tính năng có sẵn là "làm nổi bật mã", "tập trung mã", tải đoạn mã bên ngoài và nhiều hơn nữa. Danh sách đầy đủ các tính năng có thể được tìm thấy trong tài liệu markdown .

Hãy triển khai một đoạn mã đơn giản với một dòng mã được tập trung. Có thể thực hiện điều này bằng cách thêm "// [!code focus]" vào cuối hàng của chúng ta. Hãy thử xem:

const myNewFunction = () => { externalApi(); const newCode = true; // [!code focus] return newCode; }

Kết quả đầu ra sẽ là:

Ví dụ về tiêu điểm mã trong Vitepress markdown

Tùy chỉnh blog của bạn với Vue​

Trong phần cuối cùng này, chúng ta sẽ học cách tùy chỉnh mã của mình bằng cách thêm logic js, kiểu và các thành phần bên ngoài.

Trước khi bắt đầu, điều quan trọng là phải hiểu rằng khi bạn sử dụng mẫu mặc định của Vitepress, các trang của bạn sẽ được hiển thị bằng Vue.

Điều này có nghĩa là chúng ta có thể mở rộng chức năng của từng trang bằng cách hiển thị các thành phần vue khác và/hoặc viết logic và kiểu trực tiếp trên trang.

Để giải thích rõ hơn khái niệm này, chúng ta sẽ tạo một trang nhóm. Tạo một tệp có tên team.mdtrong thư mục gốc của kho lưu trữ của chúng ta.

Tệp này có thể truy cập được tại " http://localhost:5174/team.html " và chỉ là một tệp Markdown đơn giản.

Đầu tiên, chúng ta thiết lập frontmatter như trước. Trong trường hợp này, chúng ta phải chỉ định một cấu hình bổ sung có tên là "layout". Điều này sẽ đảm bảo trang không có kiểu hoặc thành phần nào được tải như thanh bên hoặc bên cạnh.

--- layout: page title: My team page ---

Sau đó, chúng ta sẽ phải tạo biến nhóm, giống như một thành phần Vue thông thường; chúng ta có thể thực hiện bằng cách xác định thẻ thiết lập tập lệnh và xác định hằng số tại đó.

<script setup> import { VPTeamMembers } from 'vitepress/theme' const members = [ { avatar: 'assets/logo.png', name: 'Simone', title: 'Software Architect', links: [ { icon: 'github', link: 'https://github.com/#' }, { icon: 'Twitter', link: 'https://twitter.com/#' } ] }, { avatar: 'assets/logo.png', name: "This Dot", title: "Software Company" } ] </script>

Trong đoạn mã trên, chúng tôi đã nhập thành VPTeamMembersphần từ vitepress/themevà định nghĩa một mảng thành viên. Các giá trị được sử dụng trong mảng thành viên được mã hóa cứng, nhưng như bạn có thể mong đợi, bạn có thể tải thông tin này trực tiếp từ API.

Bây giờ chúng ta phải sử dụng biến "members" trong tệp của mình. Chúng ta có thể làm như vậy bằng cách viết JavaScript thông thường. Tệp markdown sẽ đánh giá JavaScript và hiển thị nó, vì vậy trong ví dụ sau, nó sẽ hiển thị một thành phần cụ thể.

## Our Team Say hello to our awesome team. <VPTeamMembers size="small" :members="members" />

Trước khi tiếp tục, chúng ta cần xác định một số kiểu vì trang này chưa có kiểu vì chúng ta đã tải bố cục của "trang".

Giống như những gì chúng ta đã làm với <script>thẻ, chúng ta có thể tải <style>thẻ và cập nhật kiểu của mình:

<style> h1 { color: red; } h1, p { text-align: center; } </style>

Tệp hoàn chỉnh sẽ trông như thế này:

--- layout: page title: My team page --- <script setup> import { VPTeamPage, VPTeamPageTitle, VPTeamMembers } from 'vitepress/theme' const members = [ { avatar: 'assets/logo.png', name: 'Simone', title: 'Software Architect', links: [ { icon: 'github', link: 'https://github.com/#' }, { icon: 'Twitter', link: 'https://twitter.com/#' } ] }, { avatar: 'assets/logo.png', name: "This Dot", title: "Software Company" } ] </script> <style> h2 { color: red; } h2, p { text-align: center; } </style> ## Our Team Say hello to our awesome team. <VPTeamMembers size="small" :members="members" />

Tệp tin ở trên hiện bao gồm:

  • Một trang bìa chỉ định bố cục "trang"
  • Thẻ script tải một thành phần bên ngoài và xác định một biến
  • Các kiểu để làm cho trang đẹp hơn
  • Markdown với thành phần tùy chỉnh

Trang nhóm hoàn chỉnh sẽ hiển thị như sau: Trang chủ đề tùy chỉnh trong Vitepress

Phần kết luận​

Vitepress là một trình tạo trang web tĩnh cực kỳ linh hoạt. Chủ đề mặc định của nó cung cấp cho bạn mọi thứ bạn cần để bắt đầu nhanh chóng. Khả năng tải các chủ đề bên ngoài, cải thiện chủ đề hiện tại hoặc viết mã tùy chỉnh trong trang của bạn khiến công cụ này cực kỳ mạnh mẽ.

Trong các bài viết sau, chúng ta sẽ khám phá những thành phần nào có sẵn trong Giao diện mặc định và xem làm thế nào bạn có thể tận dụng tối đa trang web Vitepress của mình nhưng vẫn phải tiếp tục viết mã.

5:11:03 AM