Create Rust book and Publish on github account

gitbook.md

Make a book fast with mdbook and publish faster

---

0. Prerequisites (once)

Make sure you have these locally:

git --version
cargo --version

Install mdBook if you don’t have it:

cargo install mdbook

---

1. Create a New GitHub Repository

Option A: GitHub UI (most common)

1. Go to https://github.com/new

2. Fill in:

   • Repository name: my-mdbook (or whatever you like)
   • Visibility: Public (required for free GitHub Pages)

3. ✅ Do NOT check “Add a README”

4. Click Create repository

Keep that page open — GitHub will show you the repo URL.

---

2. Create the mdBook Locally

mkdir my-mdbook
cd my-mdbook
mdbook init

Choose:

• src directory? → yes
• Create .gitignore? → yes

Test locally:

mdbook serve

Open http://localhost:3000 to confirm it works.

Stop the server (Ctrl+C).

---

3. Initialize Git and Push to GitHub

Inside your book directory:

git init
git add .
git commit -m "Initial mdBook"

Add the remote (replace with your GitHub username):

git branch -M main
git remote add origin https://github.com/<your-username>/my-mdbook.git
git push -u origin main

✅ You now have:

• A GitHub repo
• mdBook source code on main

---

4. Enable GitHub Pages (via GitHub Actions – recommended)

We’ll let GitHub build and publish the book automatically.

Create workflow directory

mkdir -p .github/workflows

Create deployment workflow

Create .github/workflows/deploy.yml:

name: Deploy mdBook to GitHub Pages

on:
  push:
    branches:
      - main

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Rust
        uses: dtolnay/rust-toolchain@stable

      - name: Install mdBook
        run: cargo install mdbook

      - name: Build book
        run: mdbook build

      - name: Upload Pages artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: book

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Commit and push:

git add .github
git commit -m "Deploy mdBook to GitHub Pages"
git push

---

5. Turn On GitHub Pages

1. Go to your repo on GitHub

2. Settings → Pages

3. Under Source, select:

   • Source: GitHub Actions

4. Save

---

6. View Your Live Book 🚀

After the workflow finishes (1–2 minutes), your book will be live at:

https://<your-username>.github.io/my-mdbook/

---

7. Editing the Book

Edit files in src/:

• src/SUMMARY.md → table of contents
• src/chapter_1.md → content

Then:

git add .
git commit -m "Update book content"
git push

GitHub Pages updates automatically.

---