快速搭建一個文檔站點

開發人員最熟悉的Git+Markdown工具即可輕鬆維護一個簡約大氣的文檔站點，效果如下：

訪問地址：https://bytesfly.github.io/island

使用GitHub Pages部署

參考： https://docsify.js.org/#/zh-cn/deploy

使用GitHub Pages部署一個文檔站點非常簡單，這裏假定你已經有了GitHub賬號，沒有的話，註冊一下。

• 第一步：Fork我當前island倉庫，即 https://github.com/bytesfly/island

• 第二步：在剛Fork的倉庫設置(Settings)頁面開啓GitHub Pages功能

然後，你就可以打開https://<yourname>.github.io/island看看效果了。

本地部署

如何在本地編輯文檔並實時預覽效果呢？

• 第一步： 克隆文檔項目

倉庫所在地址： https://github.com/bytesfly/island

git clone [email protected]:bytesfly/island.git

• 第二步： 安裝啓動nginx

Linux系統：

# 安裝
sudo apt-get install nginx

# 查看狀態
sudo systemctl status nginx

# 啓動
sudo systemctl start nginx

Windows系統(待補充)：

# TODO

如果安裝啓動成功，瀏覽器打開 http://localhost/ ，可見如下界面：

• 第三步： 配置nginx

Linux系統：

# 進入nginx配置目錄
cd /etc/nginx/conf.d

# 創建新配置
sudo touch island.conf

然後打開island.conf，添加如下內容：

server {
  listen 12345;
  root /home/bytesfly/proj/island;
  index index.html;
  location ~* ^.+\.(jpg|jpeg|gif|png|ico|css|js|pdf|txt){
    root /home/bytesfly/proj/island;
  }
}

其中root後面配置的是剛纔克隆的island項目絕對路徑。

再執行命令讓nginx重新加載：

sudo nginx -s reload

瀏覽器打開 http://localhost:12345/ ,如下

此時，用你喜歡的本地編輯器編寫Markdown文檔並保存，瀏覽器刷新頁面(Ctrl + F5)即可實時預覽效果。

補充Docker部署

當然，如果本地有Docker環境，也可使用Docker部署。下面以docker-compose爲例。

下面是整體目錄結構，當前目錄下有docker-compose.yml文件和conf.d文件夾，conf.d文件夾下有island.conf文件。

➜  ~ tree
.
├── conf.d
│   └── island.conf
└── docker-compose.yml

1 directory, 2 files

docker-compose.yml文件內容如下：

version: '3.9'
services:
  nginx:
    image: nginx:1.20.1
    volumes:
      - ./conf.d:/etc/nginx/conf.d:ro
      - /home/bytesfly/proj/island:/var/www
    ports:
      - "8080:8080"
    networks:
      internal:  {}
    restart: always
networks:
  internal: {}

其中/home/bytesfly/proj/island是文檔項目所在絕對路徑。

island.conf文件內容如下：

server {
  listen 8080;
  root /var/www;
  index index.html;
  location ~* ^.+\.(jpg|jpeg|gif|png|ico|css|js|pdf|txt){
    root /var/www;
  }
}

在docker-compose.yml當前目錄執行如下命令：

sudo docker-compose up -d

如果沒有其他問題的話，瀏覽器打開 http://localhost:8080/ 查看文檔。