Các phiên bản

Bạn có thể sử dụng CLI lập phiên bản để tạo phiên bản tài liệu mới dựa trên nội dung mới nhất trong thư mục. Bộ tài liệu cụ thể đó sau đó sẽ được bảo tồn và có thể truy cập được ngay cả khi tài liệu trong thư mục tiếp tục phát triển.docs``docs

cảnh báo

Hãy suy nghĩ về nó trước khi bắt đầu phiên bản tài liệu của bạn - nó có thể trở nên khó khăn cho những người đóng góp để giúp cải thiện nó!

Hầu hết thời gian, bạn không cần lập phiên bản vì nó sẽ chỉ làm tăng thời gian xây dựng của bạn và giới thiệu sự phức tạp cho cơ sở mã của bạn. Lập phiên bản phù hợp nhất cho các trang web có lưu lượng truy cập cao và thay đổi nhanh chóng đối với tài liệu giữa các phiên bản. Nếu tài liệu của bạn hiếm khi thay đổi, đừng thêm phiên bản vào tài liệu của bạn.

Để hiểu rõ hơn về cách lập phiên bản hoạt động và xem liệu nó có phù hợp với nhu cầu của bạn hay không, bạn có thể đọc phần bên dưới.

Tổng quan

Một trang web tài liệu phiên bản điển hình trông giống như dưới đây:

website
├── sidebars.json        # sidebar for the current docs version
├── docs                 # docs directory for the current docs version
│   ├── foo
│   │   └── bar.md       # https://mysite.com/docs/next/foo/bar
│   └── hello.md         # https://mysite.com/docs/next/hello
├── versions.json        # file to indicate what versions are available
├── versioned_docs
│   ├── version-1.1.0
│   │   ├── foo
│   │   │   └── bar.md   # https://mysite.com/docs/foo/bar
│   │   └── hello.md
│   └── version-1.0.0
│       ├── foo
│       │   └── bar.md   # https://mysite.com/docs/1.0.0/foo/bar
│       └── hello.md
├── versioned_sidebars
│   ├── version-1.1.0-sidebars.json
│   └── version-1.0.0-sidebars.json
├── docusaurus.config.js
└── package.json

Tệp là danh sách các tên phiên bản, được sắp xếp từ mới nhất đến cũ nhất.versions.json

Bảng dưới đây giải thích cách tệp phiên bản ánh xạ đến phiên bản và URL được tạo.

Con đường	Phiên bản	Địa chỉ
versioned_docs/version-1.0.0/hello.md	1.0.0	/docs/1.0.0/hello
versioned_docs/version-1.1.0/hello.md	1.1.0 (mới nhất)	/docs/xin chào
docs/hello.md	dòng	/docs/next/hello

mẹo

Các tệp trong thư mục thuộc về phiên bản docs.docs``current

Theo mặc định, phiên bản docs được gắn nhãn là và được lưu trữ trong , nhưng nó hoàn toàn có thể định cấu hình để phù hợp với vòng đời phát hành của dự án của bạn.current``Next``/docs/next/*

Thuật ngữ

Lưu ý thuật ngữ chúng tôi sử dụng ở đây.

Phiên bản hiện tại

Phiên bản được đặt trong thư mục../docs

Phiên bản mới nhất / phiên bản mới nhất

Phiên bản được phân phát theo mặc định cho các mục docs navbar. Thường có đường dẫn ./docs

Phiên bản hiện tại được xác định bởi vị trí hệ thống tệp, trong khi phiên bản mới nhất được xác định bởi hành vi điều hướng. Chúng có thể là cùng một phiên bản hoặc không! (Và cấu hình mặc định, như được hiển thị trong bảng trên, sẽ coi chúng là khác nhau: phiên bản hiện tại tại và mới nhất tại .)/docs/next``/docs

Hướng dẫn

Gắn thẻ phiên bản mới

1. Trước tiên, hãy đảm bảo rằng phiên bản docs hiện tại (thư mục) đã sẵn sàng để được đóng băng../docs
2. Nhập số phiên bản mới.

• Npm
• Sợi
• PNPM

npm run docusaurus docs:version 1.1.0

Khi gắn thẻ phiên bản mới, cơ chế lập phiên bản tài liệu sẽ:

• Sao chép toàn bộ nội dung thư mục vào một thư mục mới.docs/``versioned_docs/version-[versionName]/
• Tạo tệp thanh bên phiên bản dựa trên cấu hình thanh bên hiện tại của bạn (nếu có) - được lưu dưới dạng .versioned_sidebars/version-[versionName]-sidebars.json
• Nối số phiên bản mới vào .versions.json

Tạo tài liệu mới

1. Đặt tệp mới vào thư mục phiên bản tương ứng.
2. Bao gồm tham chiếu đến tệp mới trong tệp thanh bên tương ứng theo số phiên bản.

• Cấu trúc phiên bản hiện tại
• Cấu trúc phiên bản cũ hơn

# The new file.
docs/new.md

# Edit the corresponding sidebar file.
sidebars.js

mẹo

Các tệp thanh bên được phiên bản, giống như các tệp thanh bên tiêu chuẩn, liên quan đến gốc nội dung cho phiên bản nhất định - vì vậy đối với ví dụ trên, tệp thanh bên được phiên bản của bạn có thể trông giống như:

{
  "sidebar": [
    {
      "type": "autogenerated",
      "dirName": "."
    }
  ]
}

hoặc đối với thanh bên thủ công:

{
  "sidebar": [
    {
      "type": "doc",
      "id": "new",
      "label": "New"
    }
  ]
}

Cập nhật phiên bản hiện có

Bạn có thể cập nhật nhiều phiên bản tài liệu cùng một lúc vì mỗi thư mục trong đại diện cho các tuyến cụ thể khi được xuất bản.versioned_docs/

1. Chỉnh sửa bất kỳ tệp nào.
2. Cam kết và thúc đẩy thay đổi.
3. Nó sẽ được xuất bản lên phiên bản.

Ví dụ: Khi bạn thay đổi bất kỳ tệp nào trong , nó sẽ chỉ ảnh hưởng đến tài liệu cho phiên bản.versioned_docs/version-2.6/``2.6

Xóa phiên bản hiện có

Bạn cũng có thể xóa / xóa các phiên bản.

1. Xóa phiên bản khỏi tệp .versions.json

Ví dụ:

[
  "2.0.0",
  "1.9.0",
- "1.8.0"
]

2. Xóa thư mục docs phiên bản. Ví dụ:.versioned_docs/version-1.8.0
3. Xóa tệp thanh bên đã lập phiên bản. Ví dụ:.versioned_sidebars/version-1.8.0-sidebars.json

Cấu hình hành vi lập phiên bản

Phiên bản "hiện tại" là tên phiên bản cho thư mục. Có nhiều cách khác nhau để quản lý lập phiên bản, nhưng hai mẫu rất phổ biến là:./docs

• Bạn phát hành v1 và bắt đầu làm việc ngay lập tức trên v2 (bao gồm cả tài liệu của nó). Trong trường hợp này, phiên bản hiện tại là v2, nằm trong thư mục nguồn và có thể được duyệt tại . Phiên bản mới nhất là v1, nằm trong thư mục nguồn và được hầu hết người dùng của bạn duyệt tại ../docs``example.com/docs/next``./versioned_docs/version-1``example.com/docs
• Bạn phát hành v1 và sẽ duy trì nó một thời gian trước khi nghĩ về v2. Trong trường hợp này, phiên bản hiện tại và phiên bản mới nhất đều sẽ trỏ đến v1, vì tài liệu v2 thậm chí còn chưa tồn tại!

Mặc định Docusaurus hoạt động tốt cho trường hợp sử dụng đầu tiên. Chúng tôi sẽ gắn nhãn phiên bản hiện tại là "tiếp theo" và thậm chí bạn có thể chọn không xuất bản nó.

Đối với trường hợp sử dụng thứ 2: nếu bạn phát hành v1 và không có kế hoạch làm việc trên v2 sớm, thay vì phiên bản v1 và phải duy trì các tài liệu trong 2 thư mục ( + ), bạn có thể xem xét "giả vờ" rằng phiên bản hiện tại là phiên bản cắt bằng cách cung cấp cho nó một đường dẫn và nhãn:./docs``./versioned_docs/version-1.0.0

docusaurus.config.js

export default {
  presets: [
    '@docusaurus/preset-classic',
    docs: {
      lastVersion: 'current',
      versions: {
        current: {
          label: '1.0.0',
          path: '1.0.0',
        },
      },
    },
  ],
};

Các tài liệu trong sẽ được phục vụ tại thay vì , và sẽ trở thành phiên bản mặc định mà chúng tôi liên kết đến trong trình đơn thả xuống navbar và bạn sẽ chỉ cần duy trì một thư mục duy nhất../docs``/docs/1.0.0``/docs/next``1.0.0``./docs

Chúng tôi cung cấp các tùy chọn plugin sau để tùy chỉnh hành vi lập phiên bản:

• disableVersioning: Vô hiệu hóa rõ ràng lập phiên bản ngay cả với các phiên bản. Điều này sẽ làm cho trang web chỉ bao gồm phiên bản hiện tại.
• includeCurrentVersion: Bao gồm phiên bản hiện tại (thư mục) của tài liệu của bạn../docs
  • Mẹo: hãy tắt tính năng này nếu phiên bản hiện tại đang trong quá trình thực hiện, chưa sẵn sàng để phát hành.
• lastVersion: Đặt phiên bản "phiên bản mới nhất" (tuyến đường) đề cập đến./docs
  • Mẹo: có ý nghĩa nếu phiên bản hiện tại của bạn đề cập đến một phiên bản chính liên tục được vá và phát hành. Đường dẫn cơ sở tuyến đường thực tế và nhãn của phiên bản mới nhất có thể định cấu hình.lastVersion: 'current'
• onlyIncludeVersions: Định nghĩa một tập hợp con các phiên bản từ sẽ được triển khai.versions.json
  • Mẹo: giới hạn ở 2 hoặc 3 phiên bản trong bản xem trước dành cho nhà phát triển và triển khai để cải thiện thời gian khởi động và xây dựng.
• versions: Từ điển siêu dữ liệu phiên bản. Đối với mỗi phiên bản, bạn có thể tùy chỉnh như sau:
  • label: nhãn hiển thị trong menu thả xuống và biểu ngữ phiên bản.
  • path: đường dẫn cơ sở tuyến đường của phiên bản này. Theo mặc định, phiên bản mới nhất có và phiên bản hiện tại có ./``/next
  • banner: một trong , , và . Xác định những gì được hiển thị ở đầu mỗi trang tài liệu. Bất kỳ phiên bản nào trên phiên bản mới nhất sẽ là "chưa phát hành" và bất kỳ phiên bản nào bên dưới sẽ là "không được duy trì".'none'``'unreleased'``'unmaintained'
  • badge: Hiển thị huy hiệu có tên phiên bản ở đầu tài liệu của phiên bản đó.
  • className: thêm một tùy chỉnh vào phần tử của các trang doc của phiên bản đó.className``<html>

Xem cấu hình plugin docs để biết thêm chi tiết.

Các mục thanh điều hướng

Chúng tôi cung cấp một số mục thanh điều hướng để giúp bạn nhanh chóng thiết lập điều hướng mà không phải lo lắng về các tuyến đường được phiên bản.

• doc: liên kết đến tài liệu.
• docSidebar: liên kết đến mục đầu tiên trong thanh bên.
• docsVersion: một liên kết đến tài liệu chính của phiên bản hiện đang xem.
• docsVersionDropdown: danh sách thả xuống chứa tất cả các phiên bản có sẵn.

Tất cả các liên kết này sẽ tìm kiếm một phiên bản thích hợp để liên kết đến, theo thứ tự sau:

1. Phiên bản hoạt động: phiên bản mà người dùng hiện đang duyệt, nếu cô ấy đang ở trên một trang được cung cấp bởi plugin doc này. Nếu cô ấy không ở trên trang tài liệu, hãy quay lại...
2. Phiên bản ưa thích: phiên bản mà người dùng xem lần cuối. Nếu không có lịch sử, hãy quay trở lại...
3. Phiên bản mới nhất: phiên bản mặc định mà chúng tôi điều hướng đến, được định cấu hình bởi tùy chọn.lastVersion

Các phương pháp được đề xuất

Chỉ lập phiên bản tài liệu của bạn khi cần

Ví dụ: bạn đang xây dựng tài liệu cho gói npm của mình và bạn hiện đang ở phiên bản 1.0.0. Sau đó, bạn phát hành một phiên bản vá cho một bản sửa lỗi nhỏ và bây giờ là 1.0.1.foo

Bạn có nên cắt một phiên bản tài liệu mới 1.0.1? Bạn có lẽ không nên. Tài liệu 1.0.1 và 1.0.0 không nên khác nhau tùy theo SEMVER vì không có tính năng mới!. Cắt một phiên bản mới cho nó sẽ chỉ tạo ra các tệp trùng lặp không cần thiết.

Giữ số lượng phiên bản nhỏ

Theo nguyên tắc chung, hãy cố gắng giữ số lượng phiên bản của bạn dưới 10. Bạn rất có thể sẽ có rất nhiều tài liệu phiên bản lỗi thời mà thậm chí không ai đọc nữa. Ví dụ: Jest hiện đang ở phiên bản và chỉ duy trì một số phiên bản tài liệu mới nhất với phiên bản thấp nhất là . Giữ cho nó nhỏ 😊27.4``25.X

Lưu trữ các phiên bản cũ hơn

Nếu bạn triển khai trang web của mình trên nhà cung cấp Jamstack (ví dụ: Netlify), nhà cung cấp sẽ lưu từng bản dựng sản xuất dưới dạng ảnh chụp nhanh dưới một URL bất biến. Bạn có thể bao gồm các phiên bản đã lưu trữ sẽ không bao giờ được xây dựng lại dưới dạng liên kết bên ngoài đến các URL bất biến này. Trang web Jest và trang web Docusaurus đều sử dụng mô hình như vậy để giữ số lượng phiên bản được xây dựng tích cực ở mức thấp.

Sử dụng tính năng nhập tuyệt đối trong tài liệu

Không sử dụng đường dẫn tương đối nhập trong tài liệu. Bởi vì khi chúng tôi cắt một phiên bản, các đường dẫn không còn hoạt động nữa (mức độ lồng nhau là khác nhau, trong số các lý do khác). Bạn có thể sử dụng bí danh được cung cấp bởi Docusaurus trỏ đến thư mục. Ví dụ:@site``website

- import Foo from '../src/components/Foo';
+ import Foo from '@site/src/components/Foo';

Liên kết tài liệu theo đường dẫn tệp

Tham khảo các tài liệu khác theo đường dẫn tệp tương đối với phần mở rộng để Docusaurus có thể viết lại chúng thành đường dẫn URL thực tế trong quá trình xây dựng. Các tệp sẽ được liên kết với phiên bản tương ứng chính xác..md

The [@hello](hello.mdx#paginate) document is great!

See the [Tutorial](../getting-started/tutorial.mdx) for more info.

Tài sản collocated toàn cầu hoặc phiên bản

Bạn nên quyết định xem các nội dung như hình ảnh và tệp là mỗi phiên bản hay được chia sẻ giữa các phiên bản.

Nếu nội dung của bạn nên được lập phiên bản, hãy đặt chúng trong phiên bản tài liệu và sử dụng đường dẫn tương đối:

![img alt](./myImage.png)

[download this file](./file.pdf)

Nếu nội dung của bạn là toàn cầu, hãy đặt chúng vào và sử dụng đường dẫn tuyệt đối:/static

![img alt](/myImage.png)

[download this file](/file.pdf)