// chapter_13.md

GitHub Pages، Wiki و Documentation

GitHub Pages میزبانی رایگان سایت‌های static برای هر ریپو است. Wiki فضای documentation سازمان‌یافته. در این فصل هر دو، به‌علاوه README پیشرفته و badges را یاد می‌گیریم.

GitHub Pages میزبانی رایگان سایت‌های static برای هر ریپو است. Wiki فضای documentation سازمان‌یافته. در این فصل هر دو، به‌علاوه README پیشرفته و badges را یاد می‌گیریم.

GitHub Pages

هر ریپو می‌تواند یک سایت static رایگان داشته باشد. مناسب برای:

وب‌سایت پروژه
documentation
پورتفولیو شخصی
وبلاگ
صفحه فرود محصول

انواع GitHub Pages

نوع	URL	منبع
User/Org	username.github.io	ریپوی `username.github.io`
Project	username.github.io/repo	هر ریپو دیگر

راه‌اندازی Project Page

Settings → Pages
Source: Deploy from a branch
Branch: main یا gh-pages
Folder: / (root) یا /docs
Save
۱-۲ دقیقه بعد، سایت در URL بالای صفحه ظاهر می‌شود

اولین صفحه

# index.html در root
cat > index.html << 'EOF'
<!DOCTYPE html>
<html lang="fa" dir="rtl">
<head>
    <meta charset="UTF-8">
    <title>سایت من</title>
</head>
<body>
    <h1>سلام دنیا!</h1>
    <p>این سایت با GitHub Pages میزبانی شده است.</p>
</body>
</html>
EOF

git add index.html
git commit -m "Add GitHub Pages site"
git push

دامنه سفارشی

۱. خرید دامنه

از NameCheap، Cloudflare، یا هر registrar.

۲. تنظیم DNS

# برای apex domain (example.com)
A     185.199.108.153
A     185.199.109.153
A     185.199.110.153
A     185.199.111.153

# برای www subdomain
CNAME www  USERNAME.github.io.

# برای subdomain سفارشی
CNAME blog USERNAME.github.io.

۳. در ریپو

Settings → Pages
Custom domain: example.com
Save
تیک Enforce HTTPS (پس از تأیید DNS)

۴. CNAME file

GitHub خودکار فایل CNAME در ریپو می‌سازد. این فایل را پاک نکنید:

example.com

Jekyll – Generator پیش‌فرض

GitHub Pages built-in از Jekyll پشتیبانی می‌کند – یک static site generator با Ruby.

ساختار Jekyll

my-site/
├── _config.yml          # تنظیمات
├── _layouts/            # template‌ها
│   ├── default.html
│   └── post.html
├── _includes/           # کامپوننت‌های قابل استفاده مجدد
│   └── header.html
├── _posts/              # وبلاگ پست‌ها (نام: YYYY-MM-DD-title.md)
│   └── 2026-05-01-welcome.md
├── _data/               # data files
├── assets/
│   └── style.css
├── index.md             # صفحه اصلی
└── about.md

_config.yml

title: وب‌سایت من
description: سایت شخصی محمدعلی ناظری
baseurl: ""              # مسیر سایت (برای project page: /repo-name)
url: "https://example.com"

theme: minima            # یا jekyll-theme-cayman، -slate، -hacker

plugins:
  - jekyll-feed
  - jekyll-seo-tag
  - jekyll-sitemap

# Markdown settings
markdown: kramdown
highlighter: rouge

# Author info
author:
  name: محمدعلی ناظری
  email: you@example.com
  github: manazeri

اولین post

---
layout: post
title: "خوش آمدید"
date: 2026-05-01 10:00:00 +0330
categories: blog
tags: [intro, welcome]
---

# سلام به وبلاگ من!

این اولین post است. می‌توانید از Markdown استفاده کنید:

- لیست
- موارد
- بیشتر

```python
def hello():
    print("Hello!")
```

تست محلی

# نصب Jekyll
gem install jekyll bundler

# Gemfile
cat > Gemfile << 'EOF'
source "https://rubygems.org"
gem "jekyll", "~> 4.3"
gem "jekyll-feed"
gem "jekyll-seo-tag"
gem "jekyll-sitemap"
EOF

bundle install

# اجرا
bundle exec jekyll serve
# http://localhost:4000

Deploy با GitHub Actions

روش مدرن‌تر – با Actions می‌توانید هر static site generator را deploy کنید (Hugo، Vue، React، …):

# .github/workflows/pages.yml
name: Deploy to GitHub Pages

on:
  push:
    branches: [main]

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

concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      
      - name: Install & Build
        run: |
          npm ci
          npm run build
      
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./dist
  
  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

سپس در Settings → Pages، Source را روی GitHub Actions بگذارید.

README پیشرفته

README اولین چیزی است که visitor می‌بیند. باید جذاب و informative باشد:

ساختار توصیه‌شده

<div align="center">
  <img src="docs/logo.png" width="200" />
  <h1>نام پروژه</h1>
  <p>شرح کوتاه در یک خط</p>
  
  ![Tests](https://img.shields.io/github/actions/workflow/status/USER/repo/test.yml)
  ![License](https://img.shields.io/github/license/USER/repo)
  ![Version](https://img.shields.io/github/v/release/USER/repo)
  ![Downloads](https://img.shields.io/github/downloads/USER/repo/total)
</div>

## ✨ ویژگی‌ها

- 🚀 سرعت بالا
- 🎨 رابط زیبا
- 🔒 امن
- 📱 موبایل‌فرندلی

## 📸 Screenshots

![Screenshot 1](docs/screenshot-1.png)

## 🚀 شروع سریع

### نصب

```bash
pip install my-package
```

### استفاده

```python
from my_package import hello
hello()
```

## 📖 مستندات

[مستندات کامل](https://example.com/docs)

## 🤝 مشارکت

ببینید [CONTRIBUTING.md](CONTRIBUTING.md)

## 📄 لایسنس

MIT - ببینید [LICENSE](LICENSE)

## 🙏 سپاسگزاری

- [پروژه X](https://x.com) برای الهام
- همه contributor‌ها

## 📞 تماس

- Email: you@example.com
- Twitter: [@username](https://twitter.com/username)

Badges

Badge‌های وضعیت در README:

Shields.io – بهترین

<!-- ساخت -->
![Build](https://img.shields.io/github/actions/workflow/status/USER/repo/test.yml)

<!-- آخرین release -->
![Release](https://img.shields.io/github/v/release/USER/repo)

<!-- License -->
![License](https://img.shields.io/github/license/USER/repo)

<!-- ستاره -->
![Stars](https://img.shields.io/github/stars/USER/repo)

<!-- Issue باز -->
![Issues](https://img.shields.io/github/issues/USER/repo)

<!-- زبان -->
![Language](https://img.shields.io/github/languages/top/USER/repo)

<!-- آخرین commit -->
![Last commit](https://img.shields.io/github/last-commit/USER/repo)

<!-- پکیج‌ها -->
![PyPI](https://img.shields.io/pypi/v/package-name)
![Downloads](https://img.shields.io/pypi/dm/package-name)
![npm](https://img.shields.io/npm/v/package-name)

<!-- coverage -->
![Codecov](https://img.shields.io/codecov/c/github/USER/repo)

<!-- چت -->
![Discord](https://img.shields.io/discord/SERVER_ID)

<!-- سفارشی -->
![Custom](https://img.shields.io/badge/تست-سبز-success)
![Style](https://img.shields.io/badge/style-black-000000)

برای رنگ سفارشی

![](https://img.shields.io/badge/-Persian-success?logo=iran)
![](https://img.shields.io/badge/Made_with-Python-blue?logo=python&logoColor=white)

Profile README

اگر ریپویی هم‌نام username خود بسازید، README آن در پروفایل GitHub شما ظاهر می‌شود:

github.com/USERNAME/USERNAME
└── README.md          ← این در پروفایل دیده می‌شود

Profile README جذاب

### Hi 👋

من محمدعلی ناظری هستم - مدیر [ICSD](https://icsd.ir)

🌍 کاشان، ایران  
💼 توسعه‌دهنده Django/Python و Flutter  
🎯 علاقه: AI، صنعت فرش، open-source

#### 🛠 Stack

![Python](https://img.shields.io/badge/-Python-3776AB?logo=python&logoColor=white)
![Django](https://img.shields.io/badge/-Django-092E20?logo=django&logoColor=white)
![PostgreSQL](https://img.shields.io/badge/-PostgreSQL-336791?logo=postgresql&logoColor=white)
![Flutter](https://img.shields.io/badge/-Flutter-02569B?logo=flutter&logoColor=white)

#### 📊 GitHub Stats

![Stats](https://github-readme-stats.vercel.app/api?username=USERNAME&show_icons=true&theme=dark)

![Top Languages](https://github-readme-stats.vercel.app/api/top-langs/?username=USERNAME&layout=compact)

GitHub Wiki

Wiki فضای documentation جدا از کد:

فعال‌سازی

Settings → General → Features → Wikis ✅
tab “Wiki” ظاهر می‌شود

ساختار Wiki

Home: صفحه اصلی wiki
هر صفحه یک Markdown
Sidebar: ناوبری (در فایل _Sidebar.md)
Footer: footer تمام صفحات (در _Footer.md)

Clone کردن Wiki

Wiki خودش یک Git repository است!

git clone git@github.com:USER/repo.wiki.git
cd repo.wiki
ls
# Home.md
# _Sidebar.md
# Installation.md
# ...

# ویرایش
nano Installation.md
git add .
git commit -m "Update installation guide"
git push

Wiki vs Pages vs README

ویژگی	README	Wiki	Pages
محل	ریپو main	ریپو wiki	سایت
قابل ویرایش توسط	maintainer‌ها	هر کسی (تنظیم‌پذیر)	maintainer‌ها
ساختار	تک فایل	چند صفحه	هر چی بخواهید
کاستومایز	محدود	محدود	کامل
کاربرد	معرفی	راهنما داخلی	سایت رسمی

بهترین شیوه‌های Documentation

چه چیزی documentation کنید؟

README: چی هست + سریع‌ترین راه شروع
QUICKSTART: ۵-دقیقه‌ای
INSTALL: مفصل برای OS مختلف
USAGE: مثال‌های کاربرد
API: مرجع کامل
ARCHITECTURE: طراحی داخلی
FAQ: سوالات رایج
CHANGELOG: تاریخچه تغییرات
CONTRIBUTING: راهنمای مشارکت
CODE_OF_CONDUCT: قواعد جامعه
SECURITY: گزارش vulnerability
LICENSE: مجوز

Static Site Generators محبوب

Jekyll: built-in در Pages، Ruby
Hugo: سریع‌ترین، Go
Docusaurus: مدرن، React-based، عالی برای docs فنی
VitePress: Vue-based، بسیار سریع
MkDocs: Python-based، با Material theme زیبا
GitBook: کاستومایزشده برای کتاب‌ها

MkDocs Material – پیشنهاد برای پروژه‌های Python

pip install mkdocs-material

# init
mkdocs new my-docs
cd my-docs

# config
cat > mkdocs.yml << 'EOF'
site_name: My Docs
theme:
  name: material
  language: fa
  direction: rtl
  features:
    - navigation.tabs
    - navigation.sections
    - search.highlight
    - content.code.copy

markdown_extensions:
  - admonition
  - pymdownx.highlight
  - pymdownx.superfences
EOF

# build
mkdocs build

# serve محلی
mkdocs serve

# deploy به GitHub Pages
mkdocs gh-deploy

نکات SEO برای GitHub Pages

title و description در هر صفحه
OpenGraph tags برای social sharing
sitemap.xml
robots.txt
HTTPS اجباری
canonical URLs
structured data (Schema.org)

بهترین شیوه‌ها

README در زبان مخاطب اصلی + معادل انگلیسی برای پروژه‌های international
screenshots و GIF نشان دهید (تصویر بهتر از هزار کلمه)
quickstart بسیار کوتاه (۵ دقیقه)
badges مفید (نه همه چیز)
Pages برای documentation رسمی
Wiki برای راهنماهای قابل ویرایش جامعه
HTTPS اجباری
SEO کامل

جمع‌بندی

GitHub Pages: میزبانی رایگان static site
User Page: USERNAME.github.io
Project Page: USERNAME.github.io/repo
Custom domain با CNAME
Jekyll: built-in generator
Actions deploy برای generator‌های دیگر
README پیشرفته با badges و emoji
Profile README در ریپو هم‌نام username
Wiki: documentation جامعه‌محور
MkDocs Material، Docusaurus برای docs حرفه‌ای

در فصل بعد، GitHub CLI و REST/GraphQL API.