HuongDanVietSach

Sử dụng GitHub để lưu trữ ảnh cho tài liệu

1. Tổng quan

Tài liệu này hướng dẫn các kiến thức cơ bản để giúp sử dụng GitHub làm nơi lưu trữ tài nguyên (ảnh, checklist, biểu mẫu, protocol…) làm tài liệu tham khảo cho sách. Người đọc sách sẽ được chỉ dẫn để tìm đến các tài nguyên này trên internet (được lưu trữ trên GitHub).

Nội dung file này có thể được access thông qua GitHub page https://phamthiloc.github.io/HuongDanVietSach/.

2. Khái niệm

2.1. Khái niệm về git

Git là một hệ thống quản lý phiên bản (version control system) - giống như một “hồ sơ bệnh án điện tử” cho các file và thư mục trên máy tính. Hãy tưởng tượng Git như một hệ thống lưu trữ thông minh giúp bạn:

Tác dụng của Git:

Khái niệm Repository:

Các khái niệm cơ bản:

Sơ đồ làm việc:

graph LR
    RepoA[💻 Local Repository A]
    GitHub[🌐 Remote Repository<br/>GitHub]
    RepoB[💻 Local Repository B]
    
    UserA[👤 Người dùng A]
    UserB[👤 Người dùng B]
    
    GitHub -.->|1.Pull| RepoA
    UserA -.->|2.Commit| RepoA
    RepoA -.->|3.Push| GitHub
    GitHub -.->|4.Pull| RepoB
    UserB -.->|5.Commit| RepoB
    RepoB -.->|6.Push| GitHub
    
    style UserA fill:#e1f5fe
    style UserB fill:#e1f5fe
    style RepoA fill:#f3e5f5
    style RepoB fill:#f3e5f5
    style GitHub fill:#fff3e0

Khi bạn thay đổi file trên máy tính, bạn “commit” để lưu lại. Sau đó “push” lên GitHub để chia sẻ với người khác. Người khác sẽ “pull” về để có được phiên bản mới nhất.

2.2. Khái niệm về Github

GitHub là một nền tảng lưu trữ và chia sẻ code trên internet - giống như một “thư viện y khoa trực tuyến” cho các dự án phần mềm và tài liệu. Hãy tưởng tượng GitHub như một kho lưu trữ khổng lồ trên internet:

GitHub là gì:

Tại sao sử dụng GitHub:

So sánh với Git:

GitHub sử dụng Git làm nền tảng, nhưng cung cấp thêm nhiều tính năng như giao diện web, quản lý dự án, và cộng đồng chia sẻ.

2.3. Viết tài liệu với Markdown

Markdown là một ngôn ngữ đánh dấu đơn giản để viết tài liệu - giống như một “hệ thống ghi chép thông minh” giúp bạn tạo ra văn bản có cấu trúc rõ ràng. Markdown được sử dụng rộng rãi trên GitHub để viết tài liệu hướng dẫn.

Markdown là gì:

Tại sao sử dụng Markdown:

Lưu ý khi sử dụng trên GitHub:

Hãy xem thêm “Các ký hiệu cơ bản của Markdown” trong phần phụ lục.

2.4. Vẽ hình trong Markdown với Mermaid

Mermaid là một công cụ vẽ sơ đồ bằng văn bản - giống như một “hệ thống vẽ sơ đồ thông minh” giúp bạn tạo ra các biểu đồ, sơ đồ từ những dòng chữ đơn giản. Mermaid được hỗ trợ trực tiếp trên GitHub.

Mermaid là gì:

Mermaid giúp bạn tạo ra các sơ đồ chuyên nghiệp mà không cần kỹ năng vẽ hay phần mềm phức tạp.

Hãy xem thêm “Các ký hiệu cơ bản của Mermaid” trong phần phụ lục.

2.5. GitHub Desktop

GitHub Desktop là phần mềm giúp clone, pull, commit, push data lên GitHub một cách thuận tiện.

Chi tiết cách cài đặt và sử dụng GitHub Desktop, xem Cài đặt GitHub Desktop trong phần Phụ lục.

2.6. Phần mềm soạn thảo Markdown miễn phí

Để soạn thảo file Markdown một cách thuận tiện, bạn có thể sử dụng các phần mềm editor miễn phí sau đây. Tất cả đều có chế độ preview (xem trước) và hoạt động tốt trên cả Windows và macOS:

1. MarkText

2. Visual Studio Code (VS Code)

3. Quy trình làm việc với github

Xem thêm “Commit và Push” trong phần Phụ lục.

4. Quy tắc đặt tên file ảnh

Tên file ảnh: chia vào các thư mục <Nhóm việc>/<number>_<Chú thích>.<extension>

Ví dụ

5. Làm việc với Github

5.1. Tạo repository

Với mỗi một dự án/quyển sách, chúng ta tạo cho nó một repository. Chi tiết xem trong phần “Tạo repository trên GitHub.com” trong Phụ lục.

5.2. Clone repository về máy tính

Chi tiết về việc clone repository từ GitHub.com về máy tính, xem nội dung “Clone repository” trong Phụ lục.

5.3. Tạo file LICENSE

Nên tạo file LICENSE để tạo cơ sở pháp lý bảo về quyền sở hữu của mình trước các tranh chấp trong tương lai.

Với các tài liệu viết sách, ta nên lựa chọn giấy phép Creative Commons Attribution-NonCommercial-NoDerivatives (CC BY-NC-ND).

Xem nội dung chi tiết về giấy phép CC BY-NC-ND trong phụ lục.

5.4. Tạo file README.md

File README.md là file được tự động hiển thị lên mỗi khi ta mở một thư mục trên GitHub. Ta nên để các hướng dẫn tổng quan liên quan đến các nội dung chứa trong thư mục này trong file README.md.

5.5. Thiết lập GitHub page

TBD

6. Tạo QR code

Để tạo QR code cho URL của GitHub repository, giúp người đọc dễ dàng truy cập tài liệu, bạn có thể sử dụng các dịch vụ và phần mềm miễn phí sau đây. Tất cả đều tạo QR code thuần, không có redirect:

1. Dịch vụ Online miễn phí:

QR Code Generator (qr-code-generator.com):

QRCode Monkey:

GoQR.me:

2. Phần mềm Offline miễn phí:

QR Code Studio (Windows):

QR Code Generator (Desktop):

Khuyến nghị:

Lưu ý quan trọng:

7. Tạo trang web danh sách file ảnh

Hãy xem các ví dụ

8. Làm việc với file ảnh

8.1. Tạo watermark

Để bảo vệ bản quyền ảnh khi chia sẻ trên GitHub, bạn có thể sử dụng các phần mềm tạo watermark sau đây. Tất cả đều hỗ trợ batch processing (xử lý nhiều ảnh cùng lúc) và tạo watermark trong suốt ở giữa ảnh:

1. IrfanView - Khuyến nghị cho Windows:

2. XnView - Đa nền tảng:

3. GIMP - Miễn phí hoàn toàn:

4. ImageMagick - Dòng lệnh (Command Line):

Khuyến nghị:

Lưu ý quan trọng:

8.2. Tạo ảnh đen trắng

Để chuyển đổi ảnh màu sang đen trắng (grayscale) cho mục đích in ấn hoặc tiết kiệm dung lượng, bạn có thể sử dụng các phần mềm sau đây. Tất cả đều hỗ trợ batch processing và hoạt động tốt trên Windows, macOS:

1. IrfanView - Khuyến nghị cho Windows:

2. XnView - Đa nền tảng:

3. GIMP - Miễn phí hoàn toàn:

4. ImageMagick - Dòng lệnh (Command Line):

Khuyến nghị:

Lưu ý quan trọng:

9. Phụ lục

9.1. Giấy phép CC BY-NC-ND

CC BY-NC-ND là loại giấy phép hạn chế nhất trong số các giấy phép Creative Commons. Nó cho phép người khác sử dụng tác phẩm của bạn, nhưng đi kèm với ba điều kiện chính:

Tóm lại, giấy phép CC BY-NC-ND cho phép người khác chia sẻ tác phẩm của bạn, nhưng chỉ khi họ ghi công bạn, không sử dụng cho mục đích thương mại và không thay đổi tác phẩm gốc.

9.2. Các ký hiệu cơ bản của Markdown

Xem chi tiết hơn trên GitHub

Tiêu đề:

# Tiêu đề lớn nhất
## Tiêu đề nhỏ hơn
### Tiêu đề nhỏ hơn nữa

Văn bản:

*In nghiêng* hoặc _In nghiêng_
**In đậm** hoặc __In đậm__
`Mã code`

Danh sách:

- Mục 1
- Mục 2
  - Mục con 2.1
  - Mục con 2.2

1. Mục số 1
2. Mục số 2

Liên kết và ảnh:

[Liên kết](https://github.com)
![Mô tả ảnh](đường_dẫn_ảnh.png)

Trích dẫn:

> Đây là phần trích dẫn
> Có thể viết nhiều dòng

Mã code:

`Mã ngắn`

Mã dài nhiều dòng

Dòng 1
Dòng 2
Dòng 3

9.3. Các ký hiệu cơ bản của Mermaid

Xem chi tiết hơn trên GitHub

Các loại sơ đồ cơ bản:

Sơ đồ luồng (Flowchart):

```mermaid
graph LR
    A[Khám bệnh] --> B[Chẩn đoán]
    B --> C[Điều trị]
    C --> D[Theo dõi]


Kết quả

```mermaid
graph LR
    A[Khám bệnh] --> B[Chẩn đoán]
    B --> C[Điều trị]
    C --> D[Theo dõi]

Sơ đồ trình tự (Sequence):

```mermaid
sequenceDiagram
    participant BS as Bác sĩ
    participant BN as Bệnh nhân
    BS->>BN: Khám bệnh
    BN->>BS: Mô tả triệu chứng
    BS->>BS: Chẩn đoán
    BS->>BN: Kê đơn thuốc


Kết quả

```mermaid
sequenceDiagram
    participant BS as Bác sĩ
    participant BN as Bệnh nhân
    BS->>BN: Khám bệnh
    BN->>BS: Mô tả triệu chứng
    BS->>BS: Chẩn đoán
    BS->>BN: Kê đơn thuốc

Sơ đồ tổ chức (Organization):

```mermaid
graph TD
    A[Khoa Nội] --> B[Phòng khám 1]
    A --> C[Phòng khám 2]
    A --> D[Phòng xét nghiệm]
    B --> E[Bác sĩ A]
    B --> F[Bác sĩ B]


Kết quả

```mermaid
graph TD
    A[Khoa Nội] --> B[Phòng khám 1]
    A --> C[Phòng khám 2]
    A --> D[Phòng xét nghiệm]
    B --> E[Bác sĩ A]
    B --> F[Bác sĩ B]

Tại sao sử dụng Mermaid:

Lưu ý khi sử dụng:

Ví dụ đơn giản:

```mermaid
graph LR
    A[👤 Bệnh nhân] --> B[🏥 Bệnh viện]
    B --> C[💊 Thuốc]
    C --> A


Kết quả

```mermaid
graph LR
    A[👤 Bệnh nhân] --> B[🏥 Bệnh viện]
    B --> C[💊 Thuốc]
    C --> A

9.4. Cài đặt GitHub Desktop

  1. Mở trang Download GitHub Desktop, click Download GitHub Desktop button. 01_Download.png
  2. Click Download now button. 02_DownloadNow.png
  3. Click Download for Window button. 03_DownloadForWindows.png
  4. Sau khi download chương trình cài đặt (GitHubDesktopSetup-x64.exe trên Windows PC), chạy nó, click vào button “Sign in to GitHub.com” 05_Signin.png
  5. Web browser sẽ mở ra, login vào GitHub bằng account đã đăng ký. Màn hình hiển thị có thể khác tùy vào trạng thái bạn đang login GitHub trên web như thế nào. 04_Authorize.png
  6. Sau khi login vào GitHub trên web, click button “Authorize desktop” 06_AuthorizeGitHubDesktop.png
  7. Click button “Confirm” 07_ConfirmAccess.png
  8. Khi được hỏi có mở chương trình “GitHubDesktop” hay không, click button “Open” 08_OpenGitHubDesktop.png
  9. Trên màn hình “GitHub Desktop”, click button “Finish” 09_ConfigureGit.png
  10. Đến đây, việc cài đặt GitHub Desktop hoàn tất 10_LetsGetStarted.png

9.5. Tạo repository trên GitHub.com

9.6. Clone repository

9.7. Commit và Push

This site is open source. Improve this page.