Xuất bản bài viết lên Bitbucket
Kết nối Bitbucket Cloud và xuất bản bất kỳ bài viết nào trên Clevera dưới dạng tệp Markdown, cùng với ảnh chụp màn hình, vào kho lưu trữ và thư mục bạn chọn: quyền, hạn chế nhánh, tên tệp, hình ảnh, cập nhật và thông báo lỗi.
Kết nối Bitbucket một lần và bạn có thể xuất bản bất kỳ bài viết nào trên Clevera vào một kho lưu trữ Bitbucket dưới dạng tệp Markdown, sẵn sàng cho trang tài liệu hoặc một thư mục docs/ bên cạnh mã nguồn của bạn. Bài viết này bao gồm việc kết nối, chọn kho lưu trữ và thư mục, tệp trông như thế nào và cách thức hoạt động của các bản cập nhật.
Trước khi bạn bắt đầu
- Gói: việc xuất bản lên Bitbucket là một phần của gói Pro và Custom. Trên gói Free và Starter, tab Xuất bản hiển thị "Việc xuất bản lên các công cụ của bạn đã được bao gồm trong gói Pro". Xem Chọn gói.
- Vai trò trong Clevera: chỉ chủ sở hữu không gian làm việc hoặc Quản trị viên mới có thể kết nối hoặc ngắt kết nối Bitbucket. Sau khi đã kết nối, bất kỳ ai có quyền chỉnh sửa bài viết đều có thể xuất bản bài viết đó.
- Chỉ dành cho Bitbucket Cloud: Clevera kết nối với bitbucket.org. Bitbucket Data Center và Server không được hỗ trợ.
- Quyền truy cập trong Bitbucket: tài khoản kết nối phải có khả năng đóng góp vào các kho lưu trữ mà bạn muốn xuất bản, với quyền ghi vào nhánh chính.
- Một bài viết: bạn xuất bản bài viết thuộc về một video hoặc bản ghi. Hãy tạo bài viết trước; xem Chuyển bản ghi thành bài viết.
Việc xuất bản không sử dụng tín dụng.
Kết nối Bitbucket
Mở Tích hợp
Trong thanh bên, hãy mở menu không gian làm việc và chọn Tích hợp. Tìm Bitbucket trong mục Tích hợp khả dụng (hoặc tab Phát triển) và nhấp vào Kết nối.
Cấp quyền truy cập trong Bitbucket
Đăng nhập vào Bitbucket nếu bạn chưa đăng nhập. Bitbucket sẽ yêu cầu bạn cấp quyền truy cập cho Clevera:
Quyền Bitbucket Lý do Tài khoản: đọc Để hiển thị tên Bitbucket của bạn trong Clevera Kho lưu trữ: đọc Để liệt kê các kho lưu trữ và kiểm tra xem tệp đã tồn tại hay chưa Kho lưu trữ: ghi Để commit tệp Markdown và hình ảnh của nó Nhấp vào Cấp quyền truy cập.
Kiểm tra kết nối
Bạn sẽ quay lại trang Tích hợp với thông báo "Bitbucket đã kết nối thành công với" theo sau là tên Bitbucket của bạn. Bitbucket sẽ chuyển sang danh sách Đã kết nối với huy hiệu Đã kết nối. Trước khi bạn xuất bản bất cứ thứ gì, nó sẽ hiển thị "Chưa có nội dung nào được xuất bản".
Xuất bản bài viết
Mở tab Xuất bản
Trong trình chỉnh sửa, nhấp vào Chia sẻ và mở tab Xuất bản. Trong mục Xuất bản bài viết, nhấp vào ô Bitbucket trong phần Sẵn sàng xuất bản.
Bài viết được xuất bản bằng ngôn ngữ bạn đang mở trong trình chỉnh sửa. Hãy chuyển đổi ngôn ngữ ở thanh trên cùng trước nếu muốn xuất bản bản dịch.
Chọn kho lưu trữ và thư mục
Trong mục Nơi lưu trữ, hãy chọn:
Trường Nội dung cần chọn Ghi chú Kho lưu trữ Kho lưu trữ Bitbucket cho tệp Các kho lưu trữ bạn có quyền đóng góp, trên các không gian làm việc Bitbucket của bạn, sắp xếp theo cập nhật gần nhất. Kho lưu trữ đầu tiên được chọn mặc định cho bạn Thư mục Đường dẫn như docshoặcarticles/guides"Tệp Markdown được tạo tại đây. Để trống nếu muốn lưu ở thư mục gốc của kho lưu trữ." Bắt đầu là docs. Các thư mục chưa tồn tại sẽ được tạo mớiClevera sẽ ghi nhớ lựa chọn của bạn cho lần sau.
Xuất bản
Nhấp vào Xuất bản lên Bitbucket. Bạn sẽ thấy "Đang tìm bản sao hiện có trong Bitbucket", sau đó là Đang ghi trang. Khi hoàn tất, bạn sẽ thấy "Đã xuất bản lên Bitbucket." Nhấp vào Mở trong Bitbucket để xem tệp.
Bạn có thể đóng cửa sổ Chia sẻ trong khi quá trình đang chạy; một thông báo sẽ cho bạn biết khi hoàn tất.
Nơi tệp được lưu
- Nhánh: nhánh chính của kho lưu trữ (thường là
mainhoặcmaster). Clevera commit trực tiếp vào nhánh này; nó không mở pull request và bạn không thể chọn nhánh khác. - Tên tệp: tiêu đề viết thường, với các khoảng trắng được thay bằng dấu gạch nối, kết thúc bằng
.md. "Create your first invoice" trở thànhcreate-your-first-invoice.md. Các tiêu đề bằng ngôn ngữ khác hoặc có dấu sẽ được chuyển sang ký tự Latin trước ("Créer une facture" trở thànhcreer-une-facture.md). Một tiêu đề không còn ký tự nào để chuyển đổi, ví dụ như chỉ gồm biểu tượng cảm xúc, sẽ nhận được một mã ngắn cố định (article-cộng với 8 ký tự). Tên tệp được cắt bớt ở 80 ký tự. - Hình ảnh: ảnh chụp màn hình của bài viết nằm trong
assets/<file name>/bên trong cùng thư mục, trong cùng một commit. - Thông báo commit:
Add article: <title>, hoặcUpdate article: <title>khi bạn cập nhật tệp hiện có. - Tác giả commit: tài khoản Bitbucket đã kết nối tích hợp.
Hạn chế nhánh
Nếu kho lưu trữ có hạn chế nhánh trên nhánh chính (ví dụ: chỉ thay đổi thông qua pull request, hoặc quyền ghi giới hạn cho một số người nhất định), commit của Clevera sẽ bị từ chối, ví dụ với thông báo "Bạn cần quyền ghi để commit vào kho lưu trữ Bitbucket này." Hãy thêm tài khoản đã kết nối vào danh sách những người có quyền ghi vào nhánh trong Cài đặt kho lưu trữ → Hạn chế nhánh, hoặc xuất bản vào một kho lưu trữ không có quy tắc đó.
Tệp trông như thế nào
Clevera viết Markdown thuần túy mà trình xem tệp của Bitbucket có thể hiển thị, với một khối front matter ngắn ở trên cùng. Nó không chứa HTML thô vì Bitbucket không hiển thị HTML.
---
title: "Create your first invoice"
created_at: "2026-10-12T09:30:00+00:00"
updated_at: "2026-10-12T10:05:00+00:00"
source: "Clevera"
---
| Trong bài viết Clevera | Trong tệp Markdown |
|---|---|
| Tiêu đề, in đậm, in nghiêng, gạch ngang, mã nội dòng | Markdown tiêu chuẩn |
| Liên kết | Được giữ nguyên. Các liên kết đến các trang Clevera khác chỉ giữ lại văn bản, vì chúng sẽ không hoạt động trong kho lưu trữ |
| Danh sách dấu đầu dòng, đánh số và lồng nhau | Danh sách Markdown tiêu chuẩn |
| Danh sách kiểm tra | Danh sách tác vụ (- [ ] / - [x]); Bitbucket có thể hiển thị các ô dưới dạng văn bản |
| Bảng | Bảng Markdown |
| Khối mã | Khối mã có rào chắn với ngôn ngữ; tiêu đề mã trở thành một dòng in đậm phía trên |
| Chú thích | Một trích dẫn bắt đầu bằng biểu tượng cảm xúc và tiêu đề chú thích in đậm: info ℹ️, tip 💡, warning ⚠️, note 📝, success ✅, danger 🚨 |
| Các bước đánh số | Danh sách đánh số: tiêu đề của mỗi bước in đậm, nội dung được lồng bên dưới |
| Tab | Nhãn của mỗi tab in đậm, theo sau là nội dung của nó |
| Toggles | Tóm tắt in đậm, theo sau là nội dung, luôn mở |
| Thẻ (Cards) | Danh sách các liên kết với mô tả của chúng; biểu tượng thẻ bị lược bỏ |
| Highlight, chỉ số trên, chỉ số dưới | Văn bản thuần túy |
| Phương trình | Khối toán học dưới dạng khối mã math, phương trình nội dòng dưới dạng mã nội dòng (Bitbucket không hiển thị toán học) |
| Ảnh chụp màn hình và hình ảnh | Các tệp hình ảnh được commit vào kho lưu trữ, với chú thích in nghiêng |
| Video và nội dung nhúng | Một poster hoặc hình thu nhỏ YouTube liên kết đến video, cộng với liên kết ▶ kèm tiêu đề của nó |
Video gốc của bài viết không được thêm vào tệp. Một video Clevera được đặt bên trong bài viết sẽ trở thành liên kết đến trình phát của nó, chỉ khi liên kết chia sẻ của video đó đang bật. Xem Hiển thị video trong bài viết.
Hình ảnh
Ảnh chụp màn hình được commit vào kho lưu trữ của bạn bên cạnh tệp, và các liên kết Markdown trỏ đến chúng theo đường dẫn tương đối (assets/<file name>/…). Chúng vẫn hoạt động mà không cần Clevera, và trong một kho lưu trữ riêng tư, chúng vẫn giữ tính riêng tư như phần còn lại của kho lưu trữ.
Tệp video bạn đã tải lên bài viết không được commit. Nó vẫn là một liên kết đến Clevera và sẽ hết hạn sau một thời gian; hãy xuất bản lại để gia hạn.
Sử dụng với trang tài liệu
Nếu trình tạo trang tĩnh (như MkDocs, Docusaurus hoặc Hugo) xây dựng tài liệu của bạn từ kho lưu trữ, hãy trỏ Thư mục vào thư mục mà nó đọc. Mỗi lần xuất bản là một commit bình thường, vì vậy Bitbucket Pipelines hoặc các bản dựng khác của bạn sẽ chạy như bình thường. Hầu hết các trình tạo đều đọc title từ front matter và bỏ qua các trường chúng không biết.
Cập nhật bài viết bạn đã xuất bản
Việc xuất bản chỉ diễn ra một chiều. Các chỉnh sửa bạn thực hiện trong Clevera sẽ ở lại Clevera cho đến khi bạn xuất bản lại, và các thay đổi đối với tệp trong Bitbucket sẽ không bao giờ quay lại Clevera.
Khi bạn xuất bản vào cùng kho lưu trữ và thư mục, Clevera sẽ tìm tệp có cùng tên và hiển thị "Bài viết này đã có trong Bitbucket." Nhấp vào Xem tệp để mở tệp hiện có, sau đó chọn:
| Tùy chọn | Điều gì xảy ra trong Bitbucket | Nút |
|---|---|---|
| Cập nhật bài viết hiện có | Tệp cũ và hình ảnh của nó bị ghi đè trong một commit mới. | Cập nhật trong Bitbucket |
| Tạo bài viết mới | "Giữ nguyên tệp cũ và thêm bài viết này dưới tiêu đề mới." Clevera gợi ý một Tiêu đề mới như "Create your first invoice (2)", tệp này sẽ trở thành một tệp mới. | Tạo bài viết mới |
Nếu tiêu đề thay đổi trong Clevera, tên tệp cũng thay đổi, vì vậy việc xuất bản sẽ tạo ra một tệp mới bên cạnh tệp cũ. Hãy tự xóa hoặc đổi tên tệp cũ trong Bitbucket. Không có gì trong Clevera tự động xóa tệp khỏi kho lưu trữ của bạn.
Ngắt kết nối Bitbucket
- Mở Tích hợp, nhấp vào menu ⋯ trên hàng Bitbucket và chọn Ngắt kết nối (hoặc nhấp vào Bitbucket rồi chọn Ngắt kết nối).
- Xác nhận. "Bạn không thể xuất bản lên đó từ trình chỉnh sửa nữa. Nội dung bạn đã xuất bản vẫn nằm trong Bitbucket."
Việc ngắt kết nối sẽ xóa các token của Clevera. Để thu hồi quyền truy cập của Clevera trên Bitbucket, hãy mở Cài đặt cá nhân Bitbucket của bạn, đi tới Ủy quyền ứng dụng và thu hồi quyền của Clevera.
Khắc phục sự cố
| Bạn thấy gì | Việc cần làm |
|---|---|
| "Integrations are included in Pro and Custom plans." | Nâng cấp không gian làm việc lên gói Pro. Xem Chọn gói dịch vụ. |
| Không có nút Kết nối trên trang Tích hợp | Chỉ chủ sở hữu hoặc Quản trị viên mới có thể kết nối. Hãy nhờ một trong số họ. |
| "You can view this item but not publish it. Ask someone who can edit it." | Bạn cần quyền chỉnh sửa bài viết để xuất bản nó. |
| "Connect Bitbucket on the Integrations page first." | Bitbucket chưa được kết nối trong không gian làm việc này. Hãy nhờ chủ sở hữu hoặc Quản trị viên kết nối. |
| "No repositories in this account." | Tài khoản được kết nối không thể đóng góp vào bất kỳ kho lưu trữ nào. Hãy cấp quyền truy cập hoặc kết nối lại bằng tài khoản khác. |
| Một kho lưu trữ bị thiếu trong danh sách | Kiểm tra xem tài khoản được kết nối có thể đóng góp vào đó không. Danh sách chứa tối đa 1.000 kho lưu trữ, ưu tiên các kho được cập nhật gần đây nhất. |
| "Couldn’t load your Bitbucket locations" | Nhấp vào Thử lại. Nếu tình trạng này tiếp diễn, hãy kết nối lại Bitbucket. |
| "You need write access to commit to this Bitbucket repository." | Thường là do hạn chế nhánh hoặc thiếu quyền ghi. Xem Hạn chế nhánh. |
| "Bitbucket rejected the commit." kèm theo lý do từ Bitbucket | Đọc lý do của Bitbucket, sửa lỗi trong kho lưu trữ, sau đó nhấp vào Thử lại. |
| "The Bitbucket repository was not found, or you no longer have access to it." | Kho lưu trữ đã bị di chuyển hoặc xóa, hoặc tài khoản đã mất quyền truy cập. Chọn kho lưu trữ khác hoặc sửa quyền truy cập trong Bitbucket. |
| "Bitbucket rejected the access token. Please reconnect Bitbucket." hoặc "No refresh token available. Please reconnect your Bitbucket account." | Nhấp vào Kết nối lại, hoặc mở Tích hợp và nhấp vào Kết nối lại trên hàng Bitbucket. |
| "Failed to refresh Bitbucket token. Please reconnect." | Quyền truy cập đã bị thu hồi trong Bitbucket. Hãy kết nối lại. |
| "Bitbucket rate limit reached. Please wait a moment and try again." | Đợi một phút, sau đó nhấp vào Thử lại. |
| "Connection failed:" kèm theo lý do từ Bitbucket | Bạn đã từ chối quyền truy cập hoặc Bitbucket đã từ chối. Nhấp vào Kết nối lần nữa và cấp quyền truy cập. |
| "Invalid authorization state. Please try again." hoặc "Authorization expired. Please try again." | Việc đăng nhập mất quá nhiều thời gian hoặc được thực hiện trong tab khác. Bắt đầu lại từ Kết nối. |
| "Article content is empty or invalid." | Bài viết không có nội dung bằng ngôn ngữ này. Hãy tạo hoặc viết nội dung, sau đó xuất bản lại. |
| "No article found. Please generate an article first." | Video không có bài viết bằng ngôn ngữ bạn đang mở. Hãy tạo bài viết hoặc chuyển đổi ngôn ngữ. |
| "Too many publish attempts. Please wait a moment before trying again." | Bạn có thể xuất bản tối đa 20 lần mỗi phút. Hãy đợi một phút. |
| "Failed to publish to Bitbucket. Please try again." | Nhấp vào Thử lại. Nếu vẫn thất bại, hãy kết nối lại Bitbucket và liên hệ bộ phận hỗ trợ. |
| Kết nối hiển thị Cần chú ý hoặc Lỗi | Nhấp vào Kết nối lại trên hàng đó và cấp lại quyền truy cập. |