跳至主要内容

如何參與 $Li Wiki 的寫作

歡迎閱讀貢獻指南！ 👋​

感謝你對 $Li Wiki 的興趣！無論你的技術背景如何，這份指南都將幫助你快速開始貢獻。

誰應該閱讀？​

  1. 有經驗的貢獻者（熟悉 GitHub 和 Markdown） 如果你已經熟悉 GitHub 的工作流程和 Markdown：

  2. 新手貢獻者（不熟悉 GitHub 或 Markdown） 如果你是 GitHub 或 Markdown 的新手：

    • 可以通過 Telegram 或 電子郵件 聯繫維護人員以獲取幫助。
    • 或者，按照下面的分步指南，學習如何安全、有效地貢獻。
資訊

如果覺得下面的指南太複雜，不用擔心！

你可以通過 Telegram 或 電子郵件 聯繫維護人員。你可以使用任何語言（如中文、英文等）和任何格式（如 Markdown、Word 等）提交你的內容，維護人員會一步步指導你完成貢獻或直接幫助你提交更改。

⚠️ 中國大陸貢獻者的重要安全注意事項​

危險

你的安全是我們的首要任務。如果你在中國大陸進行貢獻，請務必按照以下步驟操作，以保護你的匿名性並確保參與的安全。

第一步：創建匿名的 GitHub 賬戶​

  • 使用 ProtonMail 創建一個新的電子郵件賬戶（推薦用於隱私保護）。
  • 使用這個新的匿名電子郵件地址在 GitHub 上註冊。
  • 不要在 GitHub 個人資料中填寫任何可能泄露身份的個人信息。
  • 啓用兩步驗證（2FA）以增強賬戶安全性（參考 GitHub 文檔）。

第二步：爲多個 GitHub 賬戶配置 SSH（可選但推薦）​

如果你已經有一個個人 GitHub 賬戶，並希望與匿名賬戶分開使用：

生成 SSH 密鑰​

  1. 打開 PowerShell 並運行以下命令：

    ssh-keygen -t ed25519 -C "[email protected]"
    • 將密鑰保存到安全位置（例如 C:\Users\YourUsername\.ssh\id_ed25519_anonymous）。

  2. 更新 SSH 配置文件

    • 轉到 .ssh 文件夾（例如 C:\Users\YourUsername\.ssh），創建或編輯 config 文件，並添加以下內容： 
      Host github.com-anonymous
          HostName github.com
          User git
          IdentityFile ~/.ssh/id_ed25519_anonymous
          IdentitiesOnly yes
    • 保存文件。

  3. 將 SSH 密鑰添加到 GitHub

    • 將公鑰複製到剪貼板： 
      cat ~/.ssh/id_ed25519_anonymous.pub
    • 打開 GitHub SSH 設置 並粘貼密鑰。

第三步：爲匿名貢獻配置倉庫​

  1. 匿名克隆倉庫

    • 使用你創建的 SSH 別名： 
      git clone [email protected]:{your-github-username}/{your-forked-repo-name}.git

  2. 設置匿名的 Git 提交信息

    • 配置 Git 使用匿名身份： 
      git config user.name "anonymous-contributor"
      git config user.email "[email protected]"

  3. 驗證配置

    • 檢查你的設置： 
      git config --get user.name
      git config --get user.email

第四步：額外的安全提示​

  • 始終使用可靠的 VPN

    • 使用受信任的 VPN 訪問 GitHub，以隱藏你的 IP 地址。
    • 確保 VPN 具有強加密功能，並且不會記錄用戶活動。

  • 避免提交個人信息

    • 仔細檢查你的提交內容，確保沒有包含任何個人或敏感數據。

  • 不要鏈接到社交媒體

    • 將你的貢獻與個人在線賬戶完全分開。

分步指南：爲新手貢獻者提供幫助​

第一步：安裝必要工具​

  1. Git

    • 下載並安裝 Git。
    • 驗證安裝是否成功： 
      git --version

  2. VS Code 或 Cursor

  3. Bun（可選）

    • 如果計劃本地構建和測試站點，安裝 Bun： 
      curl -fsSL https://bun.sh/install | bash
    • 驗證安裝： 
      bun --version

第二步：設置 GitHub 賬戶​

本部分適合新手用戶。如果你已經熟悉 GitHub，可以直接跳到 [第三步](#第三步：使用 SSH 密鑰)。

  1. 註冊或登錄

  2. 啓用雙因素認證（2FA，推薦）

第三步：使用 SSH 密鑰​

SSH 密鑰提供了一種安全、便捷的方式連接 GitHub。按照以下步驟，根據你的操作系統完成設置：

生成 SSH 密鑰​

  1. 打開 PowerShell 並運行以下命令：

    ssh-keygen -t ed25519 -C "[email protected]"
    • 將 [email protected] 替換爲你 GitHub 賬戶關聯的電子郵件。
    • 默認情況下，密鑰將保存到 C:\Users\<YourUsername>\.ssh\id_ed25519。

  2. 確保密鑰已生成：

    dir $HOME\.ssh
    • 你應該看到 id_ed25519（私鑰）和 id_ed25519.pub（公鑰）。

將 SSH 密鑰添加到 SSH 代理​

  1. 啓動 SSH 代理： 
    Start-Service ssh-agent
  2. 添加私鑰到代理： 
    ssh-add $HOME\.ssh\id_ed25519

將 SSH 密鑰添加到 GitHub​

  1. 複製公鑰到剪貼板： 
    Get-Content $HOME\.ssh\id_ed25519.pub | clip
  2. 打開 GitHub SSH 設置。
  3. 點擊 “New SSH Key”，提供一個標題（如“我的筆記本”），然後粘貼密鑰。
  4. 點擊 “Add SSH Key” 保存。

測試 SSH 連接​

  1. 驗證 SSH 設置： 
    ssh -T [email protected]
    • 你應該看到類似以下的信息： 
      Hi <username>! You've successfully authenticated, but GitHub does not provide shell access.

第四步：Fork 和 Clone 倉庫​

  1. Fork 倉庫

    • 訪問 li-dao/wiki 倉庫。
    • 點擊頁面右上角的 “Fork” 按鈕，將倉庫複製到你的 GitHub 賬戶中。

  2. 克隆你的 Fork

    • 使用 Git 將你的 Fork 克隆到本地： 
      git clone [email protected]:<your-username>/wiki.git
    • 將 <your-username> 替換爲你的 GitHub 用戶名。

  3. 進入項目目錄

    • 進入克隆的項目目錄： 
      cd wiki

第五步：學習 Markdown 語法​

Markdown 是一種輕量級的標記語言，用於高效地格式化文檔。

  1. 學習基礎語法

    • 訪問 Markdown 指南 學習標題、列表、鏈接和代碼塊等基礎語法。
    • 此指南提供了示例和詳細說明，幫助你快速上手。

  2. 探索高級 Markdown 功能

    • 本項目使用 Docusaurus，支持擴展的 Markdown 功能，包括：
      • 嵌入選項卡
      • 添加提示框（如警告、信息框）
      • 使用 MDX 自定義組件
    • 瞭解更多高級功能，請訪問 Docusaurus Markdown 功能文檔。

第六步：修改 Wiki​

現在你已經完成了環境設置，可以開始對 Wiki 進行貢獻了。以下是具體步驟：

修改現有頁面​

  1. 定位到 wiki 文件夾

    • 該文件夾包含所有現有文檔文件。

  2. 在 VS Code 或 Cursor 中打開文件

    • 對內容進行改進，例如修正拼寫錯誤、添加新部分或更新過時信息。

  3. 本地預覽更改（可選）

    • 如果你已經安裝了 Bun 或 Node.js，可以運行本地開發服務器： 
      bun run start
      • 服務器將在 http://localhost:3000 啓動，你可以在瀏覽器中查看你的更改。

  4. 保存更改

    • 確保所有更改都已完成，保存文件，並準備提交更改。

添加新頁面​

  1. 創建一個新 Markdown 文件

    • 在 wiki 下的適當文件夾中添加 .md 或 .mdx 文件。
    • 例如，要創建一個新指南，請將其放在 docs 文件夾中。

  2. 在側邊欄註冊頁面

    • 打開根目錄下的 src/sidebars.ts 文件。
    • 在適當的部分下添加新頁面的條目，例如： 
      {
        type: 'doc',
        id: 'your-new-page-id',
      }
      • 將 your-new-page-id 替換爲文件名（不包括 .mdx 擴展名）。

  3. 本地預覽新頁面

    • 運行開發服務器，驗證新頁面是否正確呈現： 
      bun run start

設置多語言支持​

如果希望你的貢獻支持多種語言：

  1. 導航到 i18n 文件夾

    • 該文件夾包含不同語言的翻譯內容。

  2. 爲你的內容添加翻譯

    • 如果目標語言的子文件夾尚不存在，請創建一個，例如 i18n/zh-CN 表示簡體中文。

  3. 將你的 .mdx 文件複製到目標語言的文件夾中

    • 並將內容翻譯成目標語言。

  4. 測試多語言功能

    • 運行以下命令構建站點，並查看翻譯效果： 
      bun run build
      bun run serve

用任何語言書寫​

  • 你可以使用任何你擅長的語言編寫貢獻內容。
  • 提交後，維護人員會審查你的更改，並協調將內容翻譯成其他語言。

第七步：提交更改​

現在，你已經完成了 Wiki 的更改，可以將更改提交到主倉庫。

新手指南​

  1. 暫存更改

    • 將你修改的文件添加到暫存區： 
      git add .

  2. 提交更改

    • 使用描述性提交消息保存你的更改： 
      git commit -m "添加貢獻指南的新頁面"

  3. 推送更改

    • 將你的更改推送到你 Fork 的倉庫： 
      git push -u origin main

  4. 發起 Pull Request

    • 轉到你 Fork 的 GitHub 倉庫。
    • 點擊 “Compare & pull request” 按鈕。
    • 添加有意義的標題和描述，然後提交 Pull Request 到主倉庫。

進階用戶：Git 教程鏈接​

提交後會發生什麼？​

  1. 維護人員審查

    • 你的 Pull Request 將由維護人員審查，他們可能會提出修改建議或提供反饋。

  2. 合併到主倉庫

    • 一旦通過審查，你的 Pull Request 將被合併，你的貢獻將成爲 Wiki 的一部分！ 🎉

  3. 慶祝你的貢獻

    • 恭喜！你正式成爲 $Li Wiki 的貢獻者。感謝你的努力！

恭喜！ 🎉​

感謝你的貢獻，$Li Wiki 因你更進一步！如果你還有其他問題或需要進一步指導，請隨時聯繫維護人員。 😊