mdbook

mdbook 是什麼? (from ChatGPT)

mdBook 是一個用 Rust 語言編寫的命令行工具，用於創建現代化的在線書籍或文件，其靈感來自於 GitBook。

它讓你可以使用 Markdown 語法來編寫內容，並將其轉換為一個完整的靜態網站。這個工具特別適合用於創建技術文檔或教程。

mdBook 提供了一個命令行界面，可以用來創建新的書籍、測試書籍的鏈接、生成 HTML、PDF 等格式的輸出，或者在本地啟動一個 Web 服務器來實時預覽書籍的變化。

mdbook 相關資源

第一章

本章主要說明 mdbook 本身該如何使用，以及該如何部署此頁面

安裝(install)

使用安裝檔安裝

此方法不需要安裝 Rust， 可以到官方 GitGub Releases下載預編譯好的二進位檔來安裝。

使用 Cargo 安裝

透過 Rust 的 套件管理器 Cargo 來安裝， 此方法需要在電腦上先安裝好 Rust。

cargo install mdbook

使用(use)

初始化

mdbook init

建置專案

mdbook build

本地即時輸出

mdbook serve

測試

import this

html

<h1>Hello, World</h1>

部署(deployment)

如何自動部署

使用 GitHub Action 自動部署

修改github自動部署設定

將以下 yaml 貼到 ./.github/workflows/deploy.yml

name: Deploy
on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: write # To push a branch
      pages: write # To push to a GitHub Pages site
      id-token: write # To update the deployment status
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Install latest mdbook
        run: |
          tag=$(curl 'https://api.github.com/repos/rust-lang/mdbook/releases/latest' | jq -r '.tag_name')
          url="https://github.com/rust-lang/mdbook/releases/download/${tag}/mdbook-${tag}-x86_64-unknown-linux-gnu.tar.gz"
          mkdir mdbook
          curl -sSL $url | tar -xz --directory=./mdbook
          echo `pwd`/mdbook >> $GITHUB_PATH
      - name: Build Book
        run: |
          # This assumes your book is in the root of your repository.
          # Just add a `cd` here if you need to change to another directory.
          mdbook build
      - name: Setup Pages
        uses: actions/configure-pages@v2
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v1
        with:
          # Upload entire repository
          path: "book"
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v1

從分支部署

插件(plugin)

  • pagetoc (右上角生成章節目錄)

  • whichlang (程式碼區塊顯示語言提示及圖示)

第二章

本章主要介紹如何使用 MarkDown 來寫 mdbook，以及一些輔助寫 markdown 的插件

Nothing