Hướng dẫn tổ chức và bố cục trang chủ, sửa trang tài liệu chi tiết của Docusaurus

slash-introducing-411a16dd05086935b8e9ddae38ae9b45.svg (25 KB)

Bước tiếp theo sau khi cài đặt Docusaurus sẽ cần thực hiện tùy biến trang tài liệu theo nhu cầu sử dụng của chúng ta. Khi bạn thành thạo git và command line thì có thể sửa trên máy tính, chạy thử tại local trước khi push lên github.com để xuất bản tài liệu.

Mục tiêu chính của bài này là dành cho người mới bắt đầu nên tôi sẽ thao thác trên Github.com để cấu hình lại những thông tin quan trọng.

Cấu trúc file và thư mục của Docusaurus

your-document
├── blog
│ ├── 2020-07-21-hola.md
│ ├── 2021-05-29-hello-world.md
│ └── 2022-07-30-welcome.md
│ └── authors.yml
├── docs
│ ├── doc1.md
│ ├── doc2.md
│ ├── doc3.md
│ └── mdx.md
├── src
│ ├── css
│ │ └── custom.css
│ ├── components
│ | └── HomepageFeatures
│ | ├── index.js
│ | └── styles.module.css
│ └── pages
│ ├── markdown-page.md
│ ├── index.js
│ └── index.module.css
├── static
│ └── img
├── docusaurus.config.js
├── package.json
├── README.md
├── sidebars.js
└── yarn.lock

blog lưu ý đặt tên file có YYYY-MM-DD-ten-file.md để các bài trong mục Blog được sắp xếp theo thứ tự thời gian.
authors.yml định nghĩa thông tin tác giả tự động (người tạo bài viết trong mục tin tức)
docs chứa các file tài liệu hướng dẫn
src chứa file source để cấu hình những vùng thông tin trên trang chủ
static dùng để upload ảnh giao diện dùng cho Docusaurus
package.json là file chứa thông tin kỹ thuật để máy chủ có thể đọc và biên dịch
README.md là file index để khi vào root của repo trên Github -> sẽ hiển thị thông tin mô tả cho repo
sidebars.js là thông tin khai báo nâng cao cho menu đầu trang và menu trái

1) Khai báo lại file cấu hình docusaurus.config.js

Đầu tiên bạn cần mở repo tài liệu của bạn trên github.com => Click vào docusaurus.config.js => Màn hình mới hiện ra => Bấm tiếp vào biểu tượng bút chì để chuyển về chế độ chỉnh sửa.

Thông tin chung

title: Tiêu đề của tài liệu, đồng thời cũng xuất hiện trong vùng banner của trang chủ
tagline: Phụ đề, chỉ hiện thị dưới title, trong vùng banner của trang chủ
`url:` URL để truy cập vào tài liệu, ví dụ: bạn có thể điền là `https://doc.yourdomain.com`

Thay logo và favicon

Bạn cần upload file logo và favicon của bạn lên thư mục static -> img sau đó khai báo lại trong file docusaurus.config.js.

Ví dụ: tên file favicon là favi.png và logo là logo-sanpham.png thì chúng ta sẽ khai báo như sau:

'favicon':'img/favi.png',

Vùng logo thuộc về yếu tố giao diện nên được đặt ở dưới vùng tham số themeConfig bạn cần di chuyển xuống phía dưới để tìm đoạn thông tin này

themeConfig: {
....
logo: {
alt: 'Docs',
src: 'img/logo-sanpham.png',
},
....
},

Chuyển ngôn ngữ giao tiếp của tài liệu về tiếng Việt

Bạn tìm đoạn `i18n` và đổi thành như bên dưới

 i18n: {
defaultLocale: 'vi',
locales: ['vi'],
},

Trong tình huống bạn muốn có song ngữ thì cần để locales có giá trị là ['vi','en']

Khai báo lại thông tin đường dẫn tới repo trên github

 organizationName: 'maicamk',
projectName: 'viecketoan.com',

organizationName: bạn điền username hoặc org. name chứa repo

projectName: chứa tên repo trên github

Đổi URL để giúp người dùng sửa tài liệu

Bạn cần khai báo lại 2 đoạn editUrl, đây là link gắn với nút 'Sửa tài liệu' ở cuối mỗi file tài liệu

'editUrl: https://github.com/maicamk/viecketoan.com/tree/main/'

Thay đổi vùng thông tin chân trang

Các liên kết vùng footer sẽ có cấu trúc mặc định như bên dưới

{
.....
title: 'Docs',
items: [
{
label: 'Hướng dẫn sử dụng',
to: '/docs/intro',
},
],
.....
},

copyright: thông tin bản quyền của bạn.

2) Sửa nội dung trang chủ

Theo mẫu trình bày trang chủ gồm đoạn thông tin trên hero banner và 3 box giới thiệu tại vùng giữa trang. Cả 2 vùng này được tổ chức trong thư mục src

Bạn vào thư mục src\pages và tìm file index.js để thay đổi thông tin như bạn muốn. Ví dụ:

function HomepageHeader(){const {siteConfig}= useDocusaurusContext();
return (
<header className={clsx('hero hero--primary', styles.heroBanner)}>
<div className="container">
<h1 className="hero__title">{siteConfig.title}</h1>
<p className="hero__subtitle">{siteConfig.tagline}</p>
<div className={styles.buttons}>
<Link
className="button button--secondary button--lg"
to="/docs/intro">
Giới thiệu DigiPOS - 5min ⏱️
</Link>
</div>
</div>
</header>
);
}export default function Home(){const {siteConfig}= useDocusaurusContext();
return (
<Layout
title={`${siteConfig.title}`}description="Tài liệu hướng dẫn sử dụng DigiPOS">
<HomepageHeader />
<main>
<HomepageFeatures />
</main>
</Layout>
);
}

2.2. Thay đổi 3 box giới thiệu

Bạn vào thư mụcsrc/components/HomepageFeatures/ và tìm file index.js sau đó tiến hành sửa nội dung thông tin tương tự như sau:

const FeatureList = [
{
title: 'Dễ sử dụng',
Svg: require('@site/static/img/undraw_docusaurus_mountain.svg').default,
description: (
<>
DigiPOS was designed from the ground up to be easily installed and
used to get your website up and running quickly.
</>
),},{title: 'Bán hàng đa kênh',
Svg: require('@site/static/img/undraw_docusaurus_tree.svg').default,
description: (
<>
DigiPOS lets you focus on your docs, and we&apos;ll do the chores. Go
ahead and move your docs into the <code>docs</code> directory.
</>
),},{title: 'Công nghệ tiên tiến',
Svg: require('@site/static/img/undraw_docusaurus_react.svg').default,
description: (
<>
Extend or customize your website layout by reusing React. DigiPOS can
be extended while reusing the same header and footer.
</>
),},
];

Lưu ý:
Tại vùng này, theo trang mẫu, sẽ có 3 file hình ảnh minh họa tương ứng với 3 box bằng chuẩn SVG nên tốt nhất bạn cũng dùng ảnh SVG để thay thế nhằm đảm bảo không lỗi

Mỗi lần bạn chỉnh sửa và commit hành động, Cloudflare sẽ đọc tự động để biên dịch lại tài liệu, chúng ta có thể theo dõi tiến trình đó tại control panel của Cloudflare Pages. Vui lòng xem demo bằng hình ảnh tiến trình build tài liệu từ khi sửa đến khi Cloudflare dịch tự động:

docusaurus.gif (4.47 MB)

3. Thêm trang tài liệu chi tiết

3.1. Thêm và Sửa

3.2. Xóa tài liệu

4. Đăng tin bài trong mục blog

Trước tiên bạn cần sửa file blog/authors.yml, có cấu trúc tương tự như sau:

gobizme: // Username của bạn trên github.com
name: Vinh Phạm // Tên hiển thị
title: Founder // Chức danh, vai trò
url: https://shopply.vn/ // URL đến website
image_url: https://github.com/gobizme.png // Mặc định là username của Github.com và phần mở rộng là .png

Đơn giản khi viết bài bạn cần tạo 1 file có cấu trúc YYYY-MM-DD-ten-file.md trong thư mục blog, nội dung file này sẽ theo chuẩn markdown và phần đầu của file dành cho SEO có cấu trúc tương tự:

---
slug: changelog // đường dẫn URL
title: Nhật ký đóng gói sản phẩm // Tiêu đề
authors: // Thông tin về tác giả
name: Dzung Do // Khai báo khi tác giả không có trong danh sách authors.yml
title: OSD.VN Core Team // Khai báo khi tác giả không có trong danh sách authors.yml
url: https://github.com/saosangmo // Khai báo khi tác giả không có trong danh sách authors.yml
image_url: https://github.com/saosangmo.png // Khai báo khi tác giả không có trong danh sách authors.yml
tags: [roadmap, mkmate] 
---
# 2022-07-31, phát hành v6.5.0 // Tên bài viết

Với tình huống bạn muốn dùng tác giả trong từ điển, trường author chỉ cần khai báo 1 dòng đơn giản là author: saosangmo

Nội dung chi tiết của tin bài, bạn soạn theo chuẩn Markdown như bình thường.

Sau khi đã thành thạo các thao tác cơ bản với Docusaurus, chúng ta cần tham khảo thông tin khác trên website chính thức để mở rộng nhu cầu sử dụng đặc thù của mình.

Series bài viết Triển khai website Tài liệu sử dụng bằng Docusaurus

1) Cài đặt và triển khai Docusaurus trên Cloudflare Pages (doing)
2) Biên soạn trực tiếp file markdown tại github với prose.io
3) Hướng dẫn tổ chức lại bố cục trang chủ, sửa trang tài liệu chi tiết của Docusaurus < you are here
4) Hướng dẫn tùy biến và cài đặt 1 số plugin cần thiết cho Docusaurus (todo)