Xây dựng trang Vitepress
Bởi Victor Eke
https://www.freecodecamp.org/news/how-to-build-a-modern-documentation-site-with-vitepress/
Tài liệu là một kh ía cạnh quan trọng của phát triển phần mềm. Nhưng các nhà phát triển thường bỏ qua nó vì nó có thể gây phiền toái khi duy trì. Đây là lý do tại sao việc sử dụng các công cụ giúp đơn giản hóa quy trình này lại quan trọng.
Trong hướng dẫn này, bạn sẽ học cách xây dựng một trang web tài liệu hoàn chỉnh một cách nhanh chóng bằng cách sử dụng một công cụ hiện đại có tên là VitePress.
VitePress là gì?
VitePress là trình tạo trang web tĩnh đơn giản và hiệu quả được xây dựng trên Vite cho phép bạn tạo tài liệu trong vài phút. Nó được hỗ trợ bởi V uejs và Vite với các thành phần tùy chỉnh tích hợp.
VitePress hỗ trợ một số trang web tài liệu phổ biến như Vuejs, V itest , faker.js và Vite.
Điều kiện tiên quyết
Để thực hiện theo hướng dẫn này, bạn cần có hiểu biết cơ bản về những điều sau:
- Cú pháp Markdown
- Hiểu biết cơ bản về NPM và Vite
Dưới đây là ảnh chụp màn hình về những gì bạn sẽ xây dựng vào cuối hướng dẫn này:
Bạn muốn thử nghiệm nó không? Hãy xem bản demo trực tiếp . Ngoài ra, mã nguồn cho việc này có thể được tìm thấy trên GitHub .
Bước 1: Tạo một dự án mới
Nếu bạn đã tạo thư mục, bạn có thể bỏ qua bước này và chuyển sang bước tiếp theo. Nếu chưa, hãy sử dụng lệnh sau để tạo thư mục dự án và di chuyển vào thư mục đó.
mkdir project-name
cd project-name
Tiếp theo, bạn cần khởi tạo dự án bằng trình quản lý gói ưa thích của mình. Tôi sẽ sử dụng NPM cho phần còn lại của hướng dẫn này.
npm init
// or use this command if you want to skip all the questions
npm init -y
Nếu bạn sử dụng lệnh đầu tiên, bạn sẽ được nhắc trả lời một số câu hỏi nhất định, vì vậy hãy hoàn thành chúng một cách phù hợp.
Sau khi thực hiện thành công, bạn sẽ có một package.jsontệp trong thư mục gốc. Đây là nơi VitePress dev dependency sẽ được cài đặt.
Bước 2: Cài đặt VitePress
Bước tiếp theo là thêm VitePress và Vue làm phụ thuộc dev vào dự án của bạn, như thế này:
npm install --dev vitepress vue
Bạn đã cài đặt thành công VitePress và Vue và thêm chúng vào như các phụ thuộc dev. Bây giờ bạn có thể bắt đầu tạo các tệp doc tương ứng của mình.
Nhưng trước khi làm điều đó, tôi tin rằng điều cần thiết là phải giải thích cách thức hoạt động của VitePress.
VitePress Vork hoạt động như thế nào?
VitePress sử dụng .mdcác tệp Markdown để đánh dấu, tự động chuyển đổi thành HTML tĩnh. Để làm việc này, một thư mục đặc biệt có tên docsđược tạo trong thư mục gốc.
Thư mục này hoạt động tương tự như pagesthư mục trong NextJS, trong đó bất kỳ .jstệp nào được tạo trong thư mục đều được tự động coi là trang web. Trong trường hợp này, tệp được gọi index.mdsẽ được coi là index.htmlvà đóng vai trò là gốc của mẫu tài liệu của bạn.
Bây giờ bạn đã hiểu cách thức hoạt động của nó, bạn có thể tạo các tệp tài liệu tương ứng.
Bước 3: Tạo các tệp tài liệu tương ứng
Bạn có thể tạo thư mục docs và index.mdtệp theo cách thủ công hoặc có thể thực hiện bằng thiết bị đầu cuối như một hacker.
mkdir docs && echo '# Hello VitePress' > docs/index.md
Lệnh này chỉ tạo một thư mục có tên docsvà thêm một index.mdtệp chứa phần tử h1có nội dung "Hello World".
Với điều này, bạn có thể khởi động môi trường phát triển của mình để xem những gì đã được tạo cho đến nay.
Bước 4: Khởi động môi trường phát triển của bạn
Để chạy tài liệu cục bộ, bạn cần thêm các tập lệnh sau vào package.jsontệp. Chỉ cần sao chép mã bên dưới và thay thế "script"đối tượng bằng mã đó:
// package.json
"scripts": {
"docs:dev": "vitepress dev docs",
"docs:build": "vitepress build docs",
"docs:serve": "vitepress serve docs"
},
Cuối cùng, trang web tài liệu có thể được phục vụ trên máy chủ cục bộ bằng cách chạy lệnh bên dưới:
npm run docs:dev
Thao tác này sẽ khởi động một máy chủ phát triển tải lại nóng tại http://localhost:5173, và bạn có thể truy cập vào đó để xem trang tài liệu của mình.
Sau đây là kết quả:
Tất cả những gì bạn phải làm là thêm đánh dấu và VitePress sẽ xử lý giao diện từ công cụ mẫu của nó. Trong phiên tiếp theo, bạn sẽ tìm hiểu cách tùy chỉnh tài liệu để phù hợp với nhu cầu của mình.
Cách tùy chỉnh tài liệu của bạn với VitePress
Đầu tiên, hãy tạo một .vitepressthư mục bên trong thư mục docs mà bạn đã tạo trước đó. Đây là nơi chứa tất cả các tệp dành riêng cho VitePress.
Bên trong thư mục mới này, bạn cần một config.jstệp. Một lần nữa, bạn có thể sử dụng lệnh terminal như sau:
mkdir .vitepress && touch .vitepress/config.js
Để kiểm tra tệp cấu hình này, bạn có thể bắt đầu bằng cách thay đổi tiêu đề meta và mô tả của trang tài liệu của bạn. Sao chép đánh dấu này và dán vào config.jstệp:
// .vitepress/config.js
export default {
title: 'Adocs',
description: 'An awesome docs template built by me'
}
Nếu bạn kiểm tra công cụ phát triển, bạn sẽ thấy những thay đổi trong tiêu đề meta và mô tả.
Cách cập nhật Tiêu đề và Logo
Để thay đổi tiêu đề logo và thêm hình ảnh, hãy sao chép đánh dấu bên dưới và dán vào đối tượng mới có tên bên themeConfigtrong cùng một config.jstệp. Thao tác này sẽ ghi đè lên tiêu đề hiện tại và thêm logo vào trang tài liệu của bạn.
// config.js
export default {
themeConfig: {
logo: "/logo.svg",
siteTitle: "Adocs",
},
};
Đối với nguồn hình ảnh, bạn có thể truyền vào URL hình ảnh hoặc chỉ định đường dẫn đến hình ảnh cục bộ. Để thực hiện cục bộ, hãy đảm bảo bạn đặt hình ảnh trong publicthư mục.
Sau đây là kết quả:
Lưu ý rằng các tệp trong thư mục public được phục vụ tại đường dẫn gốc. Vì vậy, thay vì ../public/logo.svg, chỉ cần sử dụng /logo.svg.
Cách tùy chỉnh thanh điều hướng
Tùy chỉnh Navbarcũng là một quá trình khá đơn giản. Bên trong themeConfigtệp của bạn, hãy dán mã đánh dấu bên dưới. Ở đây chúng ta có một đối tượng chứa hai thuộc tính: văn bản neo textvà đường dẫn linkxác định đường dẫn URL.
// .vitepress/config.js
{
// ...
nav: [
{ text: "About", link: "/about" },
{ text: "Contact", link: "/contact" },
{ text: "Guide", link: "/guide" },
{ text: "Configs", link: "/configs" },
{ text: "Changelog", link: "https://github.com/..." },
],
// ...
}
Về cơ bản, điều hướng đến localhost:5173/about sẽ đưa bạn đến trang giới thiệu (mặc dù chúng tôi vẫn chưa tạo trang đó).
Sau đây là kết quả:
Liên kết điều hướng cũng có thể là menu thả xuống. Để thêm một menu, chỉ cần thay thế bất kỳ thuộc linkstính nào bằng đối tượng items chứa một mảng liên kết.
// .vitepress/config.js
{
text: "Changelog",
items: [
{ text: "v0.0.1", link: "/item-1" },
{ text: "v0.0.2", link: "/item-2" },
{ text: "v0.0.3", link: "/item-3" },
],
},
Bây giờ nhật ký thay đổi sẽ trở thành menu thả xuống với các liên kết tương ứng mà bạn đưa vào bên trong.
Sau đây là kết quả:
Cách Thêm Biểu Tượng Mạng Xã Hội
Menu điều hướng thường có các biểu tượng mạng xã hội mà khách truy cập có thể sử dụng để truy cập nền tảng mạng xã hội của bạn. Để thêm chúng, hãy xác định một đối tượng mới có tên là socialLinksinside themeConfigvà chỉ cần truyền vào biểu tượng mạng xã hội và liên kết bạn muốn nó điều hướng đến.
// .vitepress/config.js
socialLinks: [
{ icon: "github", link: "https://github.com/Evavic44/adocs" },
{ icon: "twitter", link: "https://twitter.com/victorekea" },
{ icon: "discord", link: "..." },
]
Theo mặc định, chỉ có 8 biểu tượng (Discord, Facebook, GitHub, Instagram, LinkedIn, Slack, Twitter và YouTube) được cung cấp. Nếu bạn muốn thêm biểu tượng tùy chỉnh, hãy sử dụng thuộc tính SVG để xác định hình ảnh svg. Bạn có thể lấy biểu tượng miễn phí từ icones.js.org .
Ví dụ, đây là một đoạn trích của applebiểu tượng.
{
icon: {
svg: '<svg role="img" width="26.01" height="32" viewBox="0 0 256 315"><path d="M213.803 167.03c.442 47.58 41.74 63.413 42.197 63.615c-.35 1.116-6.599 22.563-21.757 44.716c-13.104 19.153-26.705 38.235-48.13 38.63c-21.05.388-27.82-12.483-51.888-12.483c-24.061 0-31.582 12.088-51.51 12.871c-20.68.783-36.428-20.71-49.64-39.793c-27-39.033-47.633-110.3-19.928-158.406c13.763-23.89 38.36-39.017 65.056-39.405c20.307-.387 39.475 13.662 51.889 13.662c12.406 0 35.699-16.895 60.186-14.414c10.25.427 39.026 4.14 57.503 31.186c-1.49.923-34.335 20.044-33.978 59.822M174.24 50.199c10.98-13.29 18.369-31.79 16.353-50.199c-15.826.636-34.962 10.546-46.314 23.828c-10.173 11.763-19.082 30.589-16.678 48.633c17.64 1.365 35.66-8.964 46.64-22.262"/></svg>',
},
link: "https://www.apple.com/",
},
Đối với các biểu tượng SVG tùy chỉnh, hãy đảm bảo bạn thêm role="img"thuộc tính vào svgthẻ, vì điều này cho phép chuỗi chuyển đổi biểu tượng đúng cách.
Sau đây là kết quả:
Cách thêm thanh bên
VitePress cũng đi kèm với các thành phần tích hợp như menu thanh bên. Để thêm thanh bên, hãy tạo một đối tượng có tên sidebarvà bên trong nó, thêm các đối tượng lồng nhau có ba giá trị: tiêu đề lồng nhau, chức năng thu gọn (mặc định được đặt thành true) và các liên kết lồng nhau.
// .vitepress/config.js
sidebar: [
{
text: "Section A",
collapsible: true,
items: [
{ text: "Introduction", link: "/introduction" },
{ text: "Getting Started", link: "/getting-started" },
],
},
{
text: "Section B",
collapsible: false,
items: [
{ text: "Introduction", link: "/introduction" },
{ text: "Getting Started", link: "/getting-started" },
],
},
{
text: "Section C",
collapsible: true,
items: [
{ text: "Introduction", link: "/introduction" },
{ text: "Getting Started", link: "/getting-started" },
],
},
],
Bằng cách thêm collapsible: "true"vào đối tượng thanh bên, nó sẽ hiển thị nút chuyển đổi để ẩn/hiện từng phần. Bạn có thể tạo bao nhiêu phần tùy thích.
Sau đây là kết quả:
Bạn có thể thấy phần B không thể thu gọn được và chúng ta có nút trang tiếp theo ở cuối trang.
Cách thiết lập định tuyến trang
Như đã giải thích trước đó, VitePress tự động chuyển đổi mọi .mdtệp bên trong thư mục gốc của docs thành HTML tĩnh có thể truy cập được trong thanh địa chỉ. Ví dụ, index.mdđược chuyển đổi thành index.html, và about.md, about.htmlv.v.
Vì bạn đã tạo các liên kết điều hướng và trỏ chúng đến các URL tương ứng, bạn có thể dễ dàng truy cập các trang này bằng cách tạo chúng.
docs/
├── .vitepress/
│ └── config.js
├── public/
│ └── logo.svg
├── about.md
├── contact.md
├── guide.md
├── configs.md
└── get-started.md
Tạo các tệp này bên trong thư mục docs của bạn và thêm một đánh dấu đơn giản bên trong chúng chỉ để xem cách thức hoạt động. Trang này là markdown cơ bản nên tất cả cú pháp markdown của bạn như liên kết, khối mã, tiêu đề, v.v. đều hoạt động ở đây.
Chỉ để thử nghiệm, hãy sao chép nội dung đánh dấu này và dán vào bất kỳ .mdtệp nào bạn vừa tạo:
# About
Welcome to the about page.
This markdown supports html elements like the `p` tag coupled with inline styles
<p style="color: #ff7340; border: 1px solid rgba(255, 135, 23, 0.25); border-radius:5px; padding: 1rem;">Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s.</p>
Even satire code snippets with syntax highlighting are also supported. 😅
```js
const lang = prompt("What is your favorite programming language?");
(lang === "JavaScript") | (lang === "javascript") | (lang === "js")
? alert("JavaScript to the world! 🚀🟡")
: alert(`We don't permit such languages here 💩`);
Tất nhiên, hình ảnh cũng không bị bỏ sót.
Here's the output:
Great! You've set-up the docs, added a navigation menu with a dropdown feature, added a sidebar, and customized the links to navigate to different pages. Next up, let's work on the home page.
## How to Customize the Homepage
Just like every other component, VitePress provides us with markup for building the homepage. I've broken it down into three parts: Hero, features, and footer section.
### The Hero Section
First, we'll start with the hero section. Replace the Hello World text in the `index.md` page with the following markup:
```yml
# docs/index.md
---
layout: home
hero:
name: Adocs
text: Static docs template built with VitePress.
image:
src: /logo-big.svg
alt: Adocs logo
tagline: A free to use template for creating docs for your projects
actions:
- theme: brand
text: Get Started
link: /get-started
- theme: alt
text: View on GitHub
link: https://github.com/evavic44/adocs-template
---
Phần Tính năng
Ngoài ra, bạn có thể thêm phần tính năng sau phần hero. Chỉ cần dán mã bên dưới vào bên dưới các đối tượng hero:
# /docs/index.md
---
link: https://github.com/evavic44/adocs-template
features:
- icon: ⚡️
title: Adocs, The DX that can't be beat
details: Lorem ipsum...
- icon: 🎉
title: Power of Vue meets Markdown
details: Lorem ipsum...
- icon: 🔥
title: Simple and minimal, always
details: Lorem ipsum...
- icon: 🎀
title: Stylish and cool
details: Lorem ipsum...
---
Sau đây là kết quả:
Phần Chân trang
Bạn có thể thêm thông báo ở cuối trang, nhưng thông báo này chỉ hiển thị trên trang chủ.
Theo tài liệu của VitePress :
Lưu ý rằng phần chân trang sẽ không được hiển thị khi SideBar hiển thị.
Để thêm thành phần chân trang, hãy vào config.jstệp và dán mã đánh dấu vào bên trong themeConfigđối tượng:
// .vitepress/config.js
footer: {
message: "Released under the MIT License.",
copyright: "Copyright © 2022-present Adocs",
},
Sau đây là kết quả:
Ngoài đánh dấu, bạn cũng có thể tùy chỉnh các thành phần bằng cách sử dụng CSS tùy chỉnh để thay đổi những thứ như phông chữ, màu sắc, bố cục, V.V.
Cách thêm CSS tùy chỉnh
Chủ đề mặc định CSSđược tùy chỉnh bằng cách ghi đè các biến CSS cấp gốc. Nếu muốn, bạn có thể xem danh sách đầy đủ các biến CSS có thể tùy chỉnh .
Để bắt đầu, hãy tạo một .vitepress/themethư mục và bên trong thư mục chủ đề này, thêm tệp index.jsvà custom.css. Nếu bạn đã theo dõi, bạn có thể sử dụng lệnh terminal bên dưới để thực hiện việc này một cách nhanh chóng:
mkdir docs/.vitepress/theme && touch docs/.vitepress/theme/index.js && touch docs/.vitepress/theme/custom.css
Nếu bạn gặp bất kỳ sự cố nào với lệnh terminal, chỉ cần tạo tệp theo cách thủ công và chuyển sang bước tiếp theo.
Sau đây là tổng quan về cấu trúc thư mục:
docs/
├── .vitepress/
│ ├── config.js
│ └── theme/
│ ├── index.js
│ └── custom.css
├── public/
│ └── logo.svg
├── about.md
├── contact.md
├── guide.md
├── configs.md
└── get-started.md
Sau khi tạo các tệp này, .vitepress/theme/index.jshãy dán lệnh nhập vào bên trong tệp:
// .vitepress/theme/index.js
import DefaultTheme from "vitepress/theme";
import "./custom.css";
export default DefaultTheme;
Chủ đề màu sắc
Màu sắc được điều khiển bởi các biến CSS. Bạn có thể dễ dàng thay thế chúng bằng bất kỳ màu nào bạn muốn.
Lưu ý rằng màu này có chế độ sáng và tối. Vì vậy, hãy đảm bảo bạn thay đổi chúng cho phù hợp.
Sau đây là một ví dụ về màu tùy chỉnh của tôi:
/* .vitepress/theme/custom.css */
:root {
--vp-c-brand: rgb(255, 115, 64);
--vp-c-brand-light: rgb(255, 87, 25);
--vp-c-brand-lighter: rgb(255, 115, 64);
--vp-c-brand-dark: #FF622D;
--vp-c-brand-darker: rgb(226, 60, 0);
--vp-c-sponsor: #fd1d7c;
}
Nếu bạn không thấy hiệu quả ngay lập tức, hãy thử dừng máy chủ và khởi động lại.
Ngoài chủ đề màu sắc, bạn cũng có thể ghi đè những thứ khác như họ phông chữ, kiểu chữ, bố cục, điểm ngắt, v.v.
Cách sử dụng phông chữ tùy chỉnh
Bạn có thể nhập phông chữ Google vào tệp CSS để ghi đè lên phông chữ mặc định.
@import url(https://fonts.googleapis.com/css?family=Space+Mono:regular,italic,700,700italic);
@import url(https://fonts.googleapis.com/css?family=Space+Grotesk:regular,italic,700,700italic);
:root {
--vp-c-brand: #ff7340;
--vp-c-brand-light: #ff5719;
--vp-c-brand-lighter: #ff7340;
--vp-c-brand-lighter: rgba(255, 135, 23, 0.25);
--vp-c-brand-dark: #ff622d;
--vp-c-brand-darker: #e23c00;
--vp-c-sponsor: #fd1d7c;
/* Typography */
--vp-font-family-base: "Space Grotesk", "Inter var experimental", "Inter var",
-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen, Ubuntu,
Cantarell, "Fira Sans", "Droid Sans", "Helvetica Neue", sans-serif;
/* Code Snippet font */
--vp-font-family-mono: "Space Mono", Menlo, Monaco, Consolas, "Courier New",
monospace;
}
Với --vp-font-family-basebiến này, bạn có thể thay đổi phông chữ chính và --vp-font-family-monophông chữ cho đoạn mã.
Sau đây là kết quả:
Bạn đã tùy chỉnh thành công chủ đề và thay đổi họ phông chữ bằng CSS. Mặc dù bạn có thể làm nhiều hơn nữa về kiểu dáng, nhưng tại thời điểm này, tôi hy vọng bạn đã hiểu rõ cách tùy chỉnh tài liệu của mình bằng CSS.
Chúng ta hãy thảo luận về lưu trữ ở phần tiếp theo.
Cách lưu trữ trang web tài liệu của bạn
Bạn có thể xuất bản hoặc lưu trữ trang web tài liệu của mình trên nhiều nền tảng khác nhau như Netlify , Vercel , AWS Amplify , v.v.
Đầu tiên, chạy lệnh build:
npm run docs:build
Thao tác này sẽ tạo một distthư mục mới chứa tất cả các tệp tĩnh trong tài liệu của bạn.
Khi quyết định sử dụng dịch vụ lưu trữ nào, bạn có thể chọn bất kỳ tùy chọn nào tôi đã đề cập trước đó nhưng chúng tôi sẽ sử dụng Vercel trong hướng dẫn này. Ngoài ra, hãy thoải mái xem xét các lựa chọn thay thế khác theo lựa chọn của bạn.
Nếu bạn không có tài khoản Vercel, hãy làm theo hướng dẫn này để tạo một tài khoản và cấu hình nhà cung cấp Git trước khi chuyển sang bước tiếp theo.
Giả sử bạn đã thiết lập tài khoản thành công và tải trang web tài liệu của mình lên Vercel, hãy điều hướng đến dự án > cài đặt > cài đặt xây dựng và triển khai và dán các lệnh sau vào trường tương ứng:
- Xây dựng lệnh:
npm run docs:build - Thư mục đầu ra:
docs/.vitepress/dist
Sau khi chỉnh sửa cài đặt, hãy lưu lại và triển khai trang web của bạn!
Phần kết luận
Trong hướng dẫn này, bạn sẽ thiết lập một trang web tài liệu đầy đủ và tùy chỉnh nó bằng CSS và các thành phần tích hợp của VitePress.
Chỉ cần lưu ý rằng hướng dẫn này chỉ đề cập đến một phần nhỏ những gì có thể thực hiện được với VitePress. Để tìm hiểu thêm, hãy xem tài liệu VitePress .
Đọc thêm
Sau đây là một số điều không được đề cập trong bài viết này mà tôi nghĩ cũng đáng để xem xét:
Tài nguyên
Nếu bạn là người hâm mộ mã nguồn mở như tôi hoặc bạn thích nghe về những dự án thú vị như vậy, hãy theo dõi tôi trên mạng xã hội để bạn không bỏ lỡ bài đăng tiếp theo của tôi. Trân trọng. 🍷