跳转至

Docs文档骨架🐟

在线浏览

Welcome to MkDocs 文档修改手册

一、开发环境部署🐟

1.mkdocs serve命令部署(可选)🐟

1
2
3
4
5
6
7
8
# pip3
pip install mkdocs-material
git clone -b mkdocs https://gitee.com/shafish/docsify-reference
cd docsify-reference
# 本机运行
mkdocs serve
# 局域网内运行
mkdocs serve --dev-addr=0.0.0.0:8000
Note

mkdocs serve命令默认只能本机访问,可以使用--dev-addr参数修改为局域网访问。mkdocs serve在关闭当前命令行后会退出程序,有需要可以使用nohup命令运行:

1
2
3
4
5
nohup mkdocs serve --dev-addr=0.0.0.0:8000 &
exit # 退出终端才能一直后台运行
# 退出(直接杀进程)
ps -aux | grep "mkdocs serve"
kill pid 

2.Docker部署(可选)🐟

1
2
3
4
5
6
git clone -b mkdocs https://gitee.com/shafish/docsify-reference
cd docsify-reference
# docker run --name mkdocs -d -p 8000:8000 -v ${PWD}:/docs --restart=unless-stopped squidfunk/mkdocs-material
docker run --name mkdocs --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material:latest
# 退出
docker stop mkdocs
Note

使用docker运行需要先注释 mkdocs.yml配置中的- macros,因为文件中的跳转用到了变量引用 在正常运行容器后,使用docker exec -it mkdocs sh进入该容器 最后输入pip install mkdocs-macros-plugin安装macros插件即可

二、生成静态文件使用nginx部署🐟

0.生成静态文件🐟

1
2
3
4
5
cd /home/user
git clone -b mkdocs https://gitee.com/shafish/docsify-reference
cd docsify-reference
mkdocs build # 或者运行 docker run --rm -it -v ${PWD}:/docs squidfunk/mkdocs-material build
# 编译生成的静态资源保存在./site中,可以直接使用浏览器打开其中的index.html即可。
Info

如果有有服务器部署了网站站点,直接在当前站点中新建个文件夹,把site中资源复制到该新建文件夹,通过站点/文件夹名访问即可

1.nginx安装🐟

直接使用 https://gitee.com/shafish/config/blob/master/nginx/nginx.sh脚本安装,安装完成后直接到第3步继续执行。

1
2
3
4
5
6
7
8
9
apt -y install gcc zlib zlib-devel pcre-devel openssl openssl-devel
groupadd www
useradd -s /sbin/nologin -g www www
wget http://nginx.org/download/nginx-1.20.1.tar.gz
tar -zxvf nginx-1.20.1.tar.gz && cd nginx-1.20.1
./configure --user=www --group=www --conf-path=/www/server/nginx/conf/nginx.conf # 使用conf-path指定配置文件路径,模块未全
make # 编译
make install # nginx命令添加到系统路径
touch /www/server/panel/vhost/nginx/mkdocs.conf # 单独配置mkdocs nginx server块

2.nginx.conf主配置🐟

vim /www/server/nginx/conf/nginx.conf

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
user  www www;
worker_processes auto;
error_log  /www/wwwlogs/nginx_error.log  crit;
pid        /www/server/nginx/logs/nginx.pid;
worker_rlimit_nofile 51200;

events
    {
        use epoll;
        worker_connections 51200;
        multi_accept on;
    }

http
    {
        include       mime.types;
        include proxy.conf;
        include luawaf.conf;

        default_type  application/octet-stream;

        server_names_hash_bucket_size 512;
        client_header_buffer_size 32k;
        large_client_header_buffers 4 32k;
        client_max_body_size 50m;

        sendfile   on;
        tcp_nopush on;

        keepalive_timeout 60;

        tcp_nodelay on;

        fastcgi_connect_timeout 300;
        fastcgi_send_timeout 300;
        fastcgi_read_timeout 300;
        fastcgi_buffer_size 64k;
        fastcgi_buffers 4 64k;
        fastcgi_busy_buffers_size 128k;
        fastcgi_temp_file_write_size 256k;
        fastcgi_intercept_errors on;

        gzip on;
        gzip_min_length  1k;
        gzip_buffers     4 16k;
        gzip_http_version 1.1;
        gzip_comp_level 2;
        gzip_types     text/plain application/javascript application/x-javascript text/javascript text/css application/xml;
        gzip_vary on;
        gzip_proxied   expired no-cache no-store private auth;
        gzip_disable   "MSIE [1-6]\.";

        limit_conn_zone $binary_remote_addr zone=perip:10m;
        limit_conn_zone $server_name zone=perserver:10m;

        server_tokens off;
        access_log off;

include /www/server/panel/vhost/nginx/*.conf;  # 加载 /www/server/panel/vhost/nginx/ 目录下所有conf结尾的配置文件
}

3.mkdocs.conf🐟

vim /www/server/panel/vhost/nginx/mkdocs.conf

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
server
{
    listen 80;
    listen 443 ssl http2;
    server_name docs.shafish.cn; # 将docs.shafish.cn替换为你的域名
    index index.php index.html index.htm default.php default.htm default.html;
    root /www/wwwroot/docs.shafish.cn;

    #SSL-START SSL相关配置,请勿删除或修改下一行带注释的404规则
    #error_page 404/404.html;
    #HTTP_TO_HTTPS_START
    if ($server_port !~ 443){
        rewrite ^(/.*)$ https://$host$1 permanent;
    }
    #HTTP_TO_HTTPS_END  tls证书路径
    ssl_certificate    /etc/letsencrypt/live/docs.shafish.cn/fullchain.pem;
    ssl_certificate_key    /etc/letsencrypt/live/docs.shafish.cn/privkey.pem;
    ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
    ssl_ciphers ECDHE-RSA-AES128-GCM-SHA256:HIGH:!aNULL:!MD5:!RC4:!DHE;
    ssl_prefer_server_ciphers on;
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 10m;
    error_page 497  https://$host$request_uri;

    #SSL-END

    #ERROR-PAGE-START  错误页配置,可以注释、删除或修改
    error_page 404 /404.html;
    error_page 502 /502.html;
    #ERROR-PAGE-END

    #PHP-INFO-START  PHP引用配置,可以注释或修改
    include enable-php-70.conf;
    #PHP-INFO-END

    #REWRITE-START URL重写规则引用,修改后将导致面板设置的伪静态规则失效
    include /www/server/panel/vhost/rewrite/docs.shafish.cn.conf;
    #REWRITE-END

    #禁止访问的文件或目录
    location ~ ^/(\.user.ini|\.htaccess|\.git|\.svn|\.project|LICENSE|README.md)
    {
        return 404;
    }

    #一键申请SSL证书验证目录相关设置
    location ~ \.well-known{
        allow all;
    }

    location ~ .*\.(gif|jpg|jpeg|png|bmp|swf)$
    {
        expires      30d;
        error_log off;
        access_log off;
    }

    location ~ .*\.(js|css)?$
    {
        expires      12h;
        error_log off;
        access_log off; 
    }
    access_log  /www/wwwlogs/docs.shafish.cn.log;
    error_log  /www/wwwlogs/docs.shafish.cn.error.log;
}
1
2
sudo nginx -t # 检查配置文件是否正确
sudo nginx -s reload # 重载配置生效

直接访问设置的域名即可

Tip

nginx教程也在准备了哟

三、部署到GitHub Pages访问🐟

more about github page : https://pages.github.com/

1
2
3
4
5
6
7
8
9
git clone -b mkdocs https://gitee.com/shafish/docsify-reference
cd docsify-reference
git remote remove origin
# github创建一个仓库,比如命名为docs
git remote add origin https://github.com/username/docs.git
# 推送内容
git push -u origin master
# 自动部署到github page
mkdocs gh-deploy --clean
访问:https://username.github.io/docs/ 即可。


最后更新: August 9, 2021 00:14:15
Back to top