快速搭建一个文档站点

发布于 2022年 01月 24日 00:28

开发人员最熟悉的Git+Markdown工具即可轻松维护一个简约大气的文档站点,效果如下:

访问地址:https://bytesfly.github.io/island

使用GitHub Pages部署#

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

使用GitHub Pages部署一个文档站点非常简单,这里假定你已经有了GitHub账号,没有的话,注册一下。

  • 第二步:在刚Fork的仓库设置(Settings)页面开启GitHub Pages功能

然后,你就可以打开https://<yourname>.github.io/island看看效果了。

本地部署#

如何在本地编辑文档并实时预览效果呢?

  • 第一步: 克隆文档项目

仓库所在地址: https://github.com/bytesfly/island

git clone git@github.com: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/ 查看文档。

推荐文章