Triển khai tài liệu

Hướng dẫn cơ bản về việc triển khai tài liệu của bạn tới nhiều nhà cung cấp dịch vụ lưu trữ khác nhau

---

Trang GitHub

Nếu bạn lưu trữ mã nguồn cho một dự án trên GitHub , bạn có thể dễ dàng sử dụng GitHub Pages để lưu trữ tài liệu cho dự án của mình. Có hai loại trang GitHub Pages cơ bản : trang Project Pages và trang User and Organization Pages. Chúng gần như giống hệt nhau nhưng có một số khác biệt quan trọng, đòi hỏi quy trình làm việc khác nhau khi triển khai.

Trang dự án

Các site Project Pages đơn giản hơn vì các tệp site được triển khai đến một nhánh trong kho lưu trữ dự án ( gh-pagestheo mặc định). Sau khi bạn đến checkoutnhánh làm việc chính (thường là master) của kho lưu trữ git nơi bạn duy trì tài liệu nguồn cho dự án của mình, hãy chạy lệnh sau:

mkdocs gh-deploy

Vậy là xong! Về cơ bản, MkDocs sẽ xây dựng tài liệu của bạn và sử dụng công cụ ghp-import để commit chúng vào gh-pagesnhánh và đẩy gh-pagesnhánh đó lên GitHub.

Sử dụng mkdocs gh-deploy --helpđể có danh sách đầy đủ các tùy chọn có sẵn cho gh-deploylệnh.

Xin lưu ý rằng bạn sẽ không thể xem lại trang web đã xây dựng trước khi nó được đẩy lên GitHub. Do đó, bạn có thể muốn xác minh bất kỳ thay đổi nào bạn thực hiện đối với tài liệu trước bằng cách sử dụng lệnh buildhoặc servevà xem lại các tệp đã xây dựng cục bộ.

Cảnh báo

Bạn không bao giờ nên chỉnh sửa các tệp trong kho lưu trữ trang của mình bằng tay nếu bạn đang sử dụng gh-deploylệnh vì bạn sẽ mất công sức vào lần chạy lệnh tiếp theo.

Cảnh báo

Nếu có các tệp chưa theo dõi hoặc công việc chưa được cam kết trong kho lưu trữ cục bộ nơi mkdocs gh-deploychạy, những tệp này sẽ được đưa vào các trang được triển khai.

Tổ chức và Trang người dùng

Các trang User Pages và Organization Pages không bị ràng buộc với một dự án cụ thể và các tệp site được triển khai đến masternhánh trong một kho lưu trữ chuyên dụng được đặt tên bằng tên tài khoản GitHub. Do đó, bạn cần các bản sao làm việc của hai kho lưu trữ trên hệ thống cục bộ của chúng tôi. Ví dụ, hãy xem xét cấu trúc tệp sau:

my-project/ mkdocs.yml docs/ orgname.github.io/

Sau khi thực hiện và xác minh các bản cập nhật cho dự án, bạn cần thay đổi thư mục orgname.github.iolưu trữ và gọi mkdocs gh-deploylệnh từ đó:

cd ../orgname.github.io/ mkdocs gh-deploy --config-file ../my-project/mkdocs.yml --remote-branch master

Lưu ý rằng bạn cần trỏ rõ ràng đến mkdocs.ymltệp cấu hình vì nó không còn trong thư mục làm việc hiện tại nữa. Bạn cũng cần thông báo cho tập lệnh triển khai để cam kết với masternhánh. Bạn có thể ghi đè mặc định bằng cài đặt cấu hình remote_branch , nhưng nếu bạn quên thay đổi thư mục trước khi chạy tập lệnh triển khai, nó sẽ cam kết với master nhánh của dự án của bạn, điều mà bạn có thể không muốn.

Tên miền tùy chỉnh

GitHub Pages bao gồm hỗ trợ sử dụng Miền tùy chỉnh cho trang web của bạn. Ngoài các bước được GitHub ghi lại, bạn cần thực hiện thêm một bước nữa để MkDocs có thể hoạt động với miền tùy chỉnh của bạn. Bạn cần thêm một CNAMEtệp vào thư mục gốc của docs_dir . Tệp phải chứa một miền trống hoặc miền phụ duy nhất trên một dòng (xem tệp CNAME của MkDocs làm ví dụ). Bạn có thể tạo tệp theo cách thủ công hoặc sử dụng giao diện web của GitHub để thiết lập miền tùy chỉnh (trong mục Cài đặt / Miền tùy chỉnh). Nếu bạn sử dụng giao diện web, GitHub sẽ tạo tệp CNAMEcho bạn và lưu tệp đó vào thư mục gốc của nhánh "pages" của bạn. Để tệp không bị xóa vào lần triển khai tiếp theo, bạn cần sao chép tệp vào docs_dir. Với tệp được bao gồm đúng cách trong docs_dir, MkDocs sẽ bao gồm tệp đó trong trang web đã xây dựng của bạn và đẩy tệp đó vào nhánh "pages" của bạn mỗi khi bạn chạy gh-deploylệnh.

Nếu bạn gặp sự cố khi sử dụng tên miền tùy chỉnh, hãy xem tài liệu của GitHub về Khắc phục sự cố tên miền tùy chỉnh .

Đọc Tài liệu

Read the Docs cung cấp dịch vụ lưu trữ tài liệu miễn phí. Bạn có thể nhập tài liệu của mình bằng hệ thống kiểm soát phiên bản Git. Read the Docs hỗ trợ MkDocs ngay khi cài đặt. Làm theo hướng dẫn trên trang web của họ để sắp xếp các tệp trong kho lưu trữ của bạn đúng cách, tạo tài khoản và trỏ đến kho lưu trữ công khai của bạn. Nếu được cấu hình đúng cách, tài liệu của bạn sẽ được cập nhật mỗi khi bạn đẩy các cam kết lên kho lưu trữ công khai của mình.

Các nhà cung cấp khác

Bất kỳ nhà cung cấp dịch vụ lưu trữ nào có thể phục vụ các tệp tĩnh đều có thể được sử dụng để phục vụ tài liệu do MkDocs tạo ra. Mặc dù không thể ghi lại cách tải tài liệu lên mọi nhà cung cấp dịch vụ lưu trữ ngoài kia, nhưng các hướng dẫn sau đây sẽ cung cấp một số hỗ trợ chung.

Khi bạn xây dựng trang web của mình (sử dụng mkdocs buildlệnh), tất cả các tệp được ghi vào thư mục được chỉ định cho tùy chọn cấu hình site_dir (mặc định là "site") trong mkdocs.yamltệp cấu hình của bạn. Nói chung, bạn chỉ cần sao chép nội dung của thư mục đó vào thư mục gốc của máy chủ của nhà cung cấp dịch vụ lưu trữ. Tùy thuộc vào thiết lập của nhà cung cấp dịch vụ lưu trữ, bạn có thể cần sử dụng máy khách ftp , ssh hoặc scp đồ họa hoặc dòng lệnh để chuyển các tệp.

Ví dụ, một tập hợp lệnh điển hình từ dòng lệnh có thể trông giống như thế này:

mkdocs build scp -r ./site user@host:/path/to/server/root

Tất nhiên, bạn sẽ cần thay thế userbằng tên người dùng bạn có với nhà cung cấp dịch vụ lưu trữ và hostbằng tên miền phù hợp. Ngoài ra, bạn sẽ cần điều chỉnh /path/to/server/rootđể phù hợp với cấu hình hệ thống tệp của máy chủ.

Hãy xem tài liệu của máy chủ để biết thông tin chi tiết. Bạn có thể muốn tìm kiếm tài liệu của họ để tìm "ftp" hoặc "uploading site".

Tệp tin cục bộ

Thay vì lưu trữ tài liệu trên máy chủ, bạn có thể phân phối trực tiếp các tệp, sau đó có thể xem chúng trong trình duyệt bằng cách sử dụng file:// lược đồ này.

Lưu ý rằng, do các thiết lập bảo mật của tất cả các trình duyệt hiện đại, một số thứ sẽ không hoạt động giống nhau và một số tính năng có thể không hoạt động. Trên thực tế, một số thiết lập sẽ cần được tùy chỉnh theo những cách rất cụ thể.

• URL trang web :

  Phải site_urlđặt thành chuỗi rỗng, chuỗi này sẽ hướng dẫn MkDocs xây dựng trang web của bạn sao cho nó có thể hoạt động với file://lược đồ.

  site_url: ""

• sử dụng_url_thư_mục :

  Đặt use_directory_urlsthành false. Nếu không, các liên kết nội bộ giữa các trang sẽ không hoạt động bình thường.

  use_directory_urls: false

• tìm kiếm :

  Bạn sẽ cần phải vô hiệu hóa plugin tìm kiếm hoặc sử dụng plugin tìm kiếm của bên thứ ba được thiết kế riêng để hoạt động với file:// lược đồ. Để vô hiệu hóa tất cả các plugin, hãy đặt pluginscài đặt thành danh sách trống.

  plugins: []

  Nếu bạn đã bật các plugin khác, hãy đảm bảo rằng plugin đó searchkhông có trong danh sách.

Khi viết tài liệu của bạn, điều bắt buộc là tất cả các liên kết nội bộ phải sử dụng URL tương đối như đã ghi chép . Hãy nhớ rằng, mỗi người đọc tài liệu của bạn sẽ sử dụng một thiết bị khác nhau và các tệp có thể sẽ ở một vị trí khác nhau trên thiết bị đó.

Nếu bạn mong muốn tài liệu của mình được xem ngoại tuyến, bạn cũng có thể cần phải cẩn thận về chủ đề bạn chọn. Nhiều chủ đề sử dụng CDN cho nhiều tệp hỗ trợ khác nhau, yêu cầu kết nối Internet trực tiếp. Bạn sẽ cần chọn một chủ đề bao gồm tất cả các tệp hỗ trợ trực tiếp trong chủ đề.

Khi bạn xây dựng trang web của mình (sử dụng mkdocs buildlệnh), tất cả các tệp được ghi vào thư mục được chỉ định cho tùy chọn cấu hình site_dir (mặc định là "site") trong mkdocs.yamltệp cấu hình của bạn. Nói chung, bạn chỉ cần sao chép nội dung của thư mục đó và phân phối cho người đọc của mình. Ngoài ra, bạn có thể chọn sử dụng công cụ của bên thứ ba để chuyển đổi các tệp HTML sang một số định dạng tài liệu khác.

404 Trang

Khi MkDocs xây dựng tài liệu, nó sẽ bao gồm tệp 404.html trong thư mục xây dựng . Tệp này sẽ được tự động sử dụng khi triển khai lên GitHub nhưng chỉ trên miền tùy chỉnh. Các máy chủ web khác có thể được định cấu hình để sử dụng nó nhưng tính năng này sẽ không phải lúc nào cũng khả dụng. Xem tài liệu cho máy chủ bạn chọn để biết thêm thông tin.