Tổng kết các bước cần làm khi push lên Github
Dưới đây là tổng kết các bước cần thực hiện khi "deploy" dự án Docusaurus lên Github Pages. Cần thực hiện đầy đủ các bước này để quá trình push dự án lên Github với sự hỗ trợ của "Github Desktop" và "Github Actions" được hoàn tất tốt đẹp!
CÁC BƯỚC CHUẨN BỊ VỚI DỰ ÁN
1)Nhờ sử dụng "Github Desktop" ta không cần chạy thủ công các lệnh "git add ." để đăng ký các tệp vào ".git" từ Terminal...
Chạy "npm run build" chỉ để tự kiểm tra xem hệ thống ổn định, hay bị báo lỗi gì không mà thôi!
2)Để kiểm tra dự án trước khi push lên Github ta chạy các lệnh sau:
(Xóa bỏ folder "node_modules" và tập tin "package-lock.json")
npm cache clean --force (dọn dẹp môi trường)
npm install --production (Cài đặt lại các phụ thuộc cần thiết)
hoặc lệnh này: (được sử dụng để cài đặt các gói phụ thuộc trong dự án Node.js, nhưng bỏ qua các gói được liệt kê trong devDependencies)
npm install --omit=dev
3)Ở bước này ta cập nhật các gói phụ thuộc lên phiên bản mới nhất bằng lệnh:
npm update
4)Xóa bộ nhớ đệm và xây dựng lại dự án qua định dạng HTML bằng cách chạy lệnh sau:
npm run clear
(Chạy "npm run clear" là sẽ xóa folder ".docusaurus" trong dự án và xây dựng lại khi chạy "npm run build")
npm run build --verbose
5)Trước khi push lên Github ta edit lại file ".gitignore" để bỏ qua không "push" lên các tệp và thư mục không cần thiết! Tệp ".git" này, nếu chưa có ta tạo ra bằng lệnh:
touch .gitignore
Sau đó ta thêm vào tệp này những file và folder cần bỏ qua, ví dụ:
# Dependencies
/node_modules
# Production
/build
# Generated files
.docusaurus
.cache-loader
# Misc
.DS_Store
.env.local
.env.development.local
.env.test.local
.env.production.local
npm-debug.log*
yarn-debug.log*
yarn-error.log*
hoặc:
# Bỏ qua thư mục node_modules
node_modules/
# Bỏ qua thư mục .docusaurus
.docusaurus/
# Bỏ qua tệp tạm thời
*.tmp
Rồi nếu chạy thủ công thì ta push tệp ".gitignore" bằng lệnh(hoặc để file này trong dự án rồi sau push tất cả lên bằng "Github Desktop")
git add .gitignore
git commit -m (Thêm tệp .gitignore để bỏ qua các thư mục không cần thiết)
HOÀN THÀNH BƯỚC NÀY TRƯỚC KHI KẾT NỐI VỚI "GITHUB DESKTOP"
6)Hiệu chỉnh file "docusaurus.config.js"
trong dự án Docusaurus để bảo đảm khai báo đúng PATH theo thực tế,trước khi sao chép tất cả vào "repository". Cụ thể:
-Hiệu chỉnh lại file "docusaurus.config.js"
module.exports = {
url: 'https://tm.github.io', // Ví dụ username Github là "tm"
baseUrl: '/', // Nếu repository của bạn là "tm.github.io"
projectName: 'tm.github.io',
organizationName: 'tm',
trailingSlash: false, // Đảm bảo không có slash ở cuối URL
};
Điều chỉnh path "docsRouteBasePath" đúng với thực tế, cụ thể thay vì '/' phải sửa lại là:
docsRouteBasePath: '/docs', // Base URL của tài liệu, thay đổi nếu cần
KẾT NỐI "GITHUB DESKTOP VỚI REPOSITORY TRÊN GITHUB
7)Mở GitHub Desktop và đăng nhập vào tài khoản GitHub
Vào menu File > Clone repository.
Chọn tab URL và dán URL của repository ta đã tạo trên GitHub
Chọn thư mục trên máy tính để lưu dự án và nhấn Clone.
(sẽ thấy folder ".git" trong thư mục dự án) -Tạo foder ".github"/workflow". Trong folder "workflow" tạo file "deploy.yml" (NẾU DÙNG GITHUB ACTIONS thì không cần chạy "npm run build" và "npm run deploy")
8)Thêm mã nguồn vào repository
Mở thư mục dự án Docusaurus của ta trong Laptop
Sao chép tất cả các tệp trong d ự án Docusaurus và dán vào thư mục của repository vừa clone.(không chép folder ".git")
(Trong góc trên bên trái của cửa sổ GitHub Desktop, nhấp vào menu thả xuống và chọn kho lưu trữ ta muốn thực hiện commit và push.)
Quay lại GitHub Desktop, ta sẽ thấy các tệp đã được thêm vào trong Changes tab Trong tab "Changes", danh sách các tệp đã thay đổi. Đánh dấu chọn các tệp mà ta muốn đưa vào commit. Nhập thông điệp commit vào ô "Summary" (Tóm tắt). Nhấp vào nút "Commit to main" (Hoặc tên nhánh hiện tại) để thực hiện commit. Đẩy (push) các thay đổi lên GitHub: Sau khi commit, nhấp vào nút "Push origin" ở góc trên bên phải để đẩy các thay đổi lên kho lưu trữ trên GitHub
4)Dùng "GitHub Action" để triển khai trang web
Bật trải nghiệm này trong GitHub.com -> Kho lưu trữ -> Cài đặt -> Trang -> Xây dựng và triển khai -> Nguồn bằng cách chọn GitHub Actions thay vì tùy chọn Triển khai từ nhánh cũ .
Trong GitHub.com -> Kho lưu trữ -> Cài đặt -> Môi trường, ta sẽ thấy môi trường GitHub có tên là github-pages
Vào edit file workflow/deploy.yml
...//github.com/tm.io/new/main
Nội dung file "deploy.yml" tương tự như:
name: Triển khai Docusaurus lên GitHub Pages
on:
push:
branches:
- main # Thay 'main' bằng tên nhánh chính của bạn nếu khác
pull_request:
branches:
- main
jobs:
build:
runs-on: ubuntu-latest
steps:
# Bước 1: Kiểm tra mã nguồn
- name: Checkout code
uses: actions/checkout@v3
# Bước 2: Thiết lập Node.js (Đảm bảo phiên bản phù hợp với Docusaurus)
- name: Setup Node.js
uses: actions/setup-node@v3
with:
node-version: '22.14.0' # Sử dụng Node.js >= 18.17.0
# Bước 3: Xóa cache npm
- name: Clear npm cache
run: npm cache clean --force
# Bước 4: Cài đặt dependencies
- name: Install dependencies
run: npm install
# Bước 5: Xây dựng dự án Docusaurus
- name: Build Docusaurus
run: npm run build
# Bước 6: Triển khai lên GitHub Pages
- name: Deploy to GitHub Pages
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./build # Thư mục đầu ra của Docusaurus
Nếu ta không thấy nhánh gh-pages trong repository của mình, có thể là do nhánh này chưa được tạo. ta có thể tạo nhánh gh-pages bằng cách:
Sử dụng lệnh Git:
git checkout --orphan gh-pages
git rm -rf .
git commit --allow-empty -m "Initial gh-pages commit"
git push origin gh-pages
Nếu "build" dự án thủ công, không dùng "Github Actions" thì ta chạy lệnh sau từ Terminal:
npm run build
Đảm bảo rằng các thông số organizationName, projectName, và deploymentBranch trong tệp docusaurus.config.js được cấu hình chính xác:
module.exports = {
// ...
organizationName: '55tm', // Tên người dùng hoặc tổ chức GitHub
projectName: '55tm.github.io', // Tên kho lưu trữ(ví dụ...)
deploymentBranch: 'gh-pages', // Nhánh triển khai
// ...
};
Sau lệnh này ta có thể chạy lệnh triển khai lên "GitHub Pages":
USE_SSH=true GIT_USER=55tm npm run deploy (ví dụ Acc Github=55tm)
hoặc:
GIT_USER=55tm npm run deploy
Lệnh này sẽ build trang web của ta và đẩy nội dung đã build lên nhánh gh-pages của kho lưu trữ GitHub. Sau đó, GitHub Pages sẽ phục vụ nội dung từ nhánh này