• Vuepress 三分钟搭建一个精美的文档或博客


    大家好,我是凌览。

    作为一个程序员,相信每个人都想折腾一个属于自己的博客。技术文章的输出是我们程序员能力的一种体现,也是一种非常好的个人总结。

    网上有很多文档编写网站及工具,比如语雀、石墨等等。但多数需要付费,不能自己DIY。

    为了少写点curd,我推荐使用VuePress,它可以帮助我们快速地搭建出技术文档或个人博客。

    Vuepress搭建地址:https://jshai.gitee.io/vuepress-blog/

    什么是Vuepress

    VuePress是由Vue.js开发团队创建的一个静态网站生成器。它的设计目标是用于编写技术文档或者博客,并且提供了一系列的默认主题和插件,使得构建和维护现代化的静态网站变得更加简单。

    它有以下优点:

    • 基于Vue.js,可以使用Vue.js编写功能

    • 支持Markdown

    • 简单易用

    • 开箱即用的主题

    • 丰富的插件

    本地搭建文档

    快速上手同官方文档

    1. 创建新目录
    mkdir vuepress-starter && cd vuepress-starte
    
    • 1
    1. 初始化项目,自行选择喜欢的包管理器
    npm init #yarn init
    
    • 1
    1. 安装VuePress为本地依赖
    npm install -D vuepress # yarn add -D vuepress
    
    • 1
    1. 创建一篇文档
    mkdir docs && echo '这是知识库的介绍' > docs/README.md
    
    • 1
    1. 在 package.json 中添加一些 ++scripts++
    {
    "scripts": {
      "docs:dev": "vuepress dev docs",
      "docs:build": "vuepress build docs"
     }
    }
    
    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    1. 启动本地服务器
    npm run docs:dev #yarn docs:dev 
    
    • 1

    VuePress 会在 http://localhost:8080启动一个热重载的开发服务器。

    基础配置

    docs创建一个.vuepress文件夹,.vuepress下再创建config.js文件,Vuepress的配置由config.js文件内容决定。这里我们的项目结构可能是这样的:

    ├─ docs
    │  ├─ README.md
    │  └─ .vuepress
    │     └─ config.js
    └─ package.json
    
    • 1
    • 2
    • 3
    • 4
    • 5

    配置网站的标题和描述,config.js写入内容:

    module.exports = {
        title: '凌览的知识库',
        description: '凌览,微信搜索「凌览社」关注我,长期交流学习。不知名前端,Node.js爱好者'
    }
    
    • 1
    • 2
    • 3
    • 4

    页面长这样:

    添加导航栏

    给首页的上方添加导航栏,config.js修改:

    module.exports = {
        title: '凌览的知识库',
        description: '凌览,微信搜索「程序员凌览」关注我,长期交流学习。不知名前端,Node.js爱好者'
        themeConfig: {
            logo: 'https://www.linglan01.cn/favicon.JPG',
            //顶部导航栏
            nav: [
                { text: '博客', link: 'https://linglan01.cn/' },
                { text: '掘金', link: 'https://juejin.cn/user/3350967174565198' },
                { text: 'Github', link: 'https://github.com/CatsAndMice' }
            ]
        }
     }
    
    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    • 13

    页面变成了这样:

    更多导航栏配置参考VuePress导航栏配置

    添加侧边栏

    我们在docs文件夹下,创建introduce文件夹,此时结构如下:

    ├─ docs
    │  ├─ README.md
    │  └─ .vuepress
    │     └─ config.js
    |   └─ introduce
    |            └─ haha.md
    |            └─ README.md
    └─ package.json
    
    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8

    配置config.js如下:

    module.exports = {   
        themeConfig: {
            nav:[...]
            sidebar: [
                {
                    title: '侧边栏分组1', 
                    collapsable: false, 
                    sidebarDepth: 1,    
                    children: [
                        '/introduce/',//自动获取README.md
                        '/introduce/haha'
                    ]
                },
            ],
        },  
    }
    
    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    • 13
    • 14
    • 15
    • 16

    页面效果如下:

    还可以设置多组侧边栏:

    module.exports = {   
        themeConfig: {
            nav:[...]
            sidebar: [
                {
                    title: '侧边栏分组1', 
                    collapsable: false, 
                    sidebarDepth: 1,    
                    children: [
                        '/introduce/',//自动获取README.md
                        '/introduce/haha',
                       '...'
                    ]
                },
                 {
                    title: '侧边栏分组2', 
                    collapsable: true, 
                    sidebarDepth: 1,    
                    children: [
                         '...'
                    ]
                },
            ],
        },  
    }
    
    • 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

    更多侧边栏配置参与Vuepress侧边栏

    更换主题

    社区有vuepress-theme-hopevuepress-theme-reco等主题,可以根据喜好选择。

    这里我们以vuepress-theme-reco为例,现在安装vuepress-theme-reco:

    npm install vuepress-theme-reco --save-dev
    # or
    yarn add vuepress-theme-reco
    
    • 1
    • 2
    • 3

    config.js配置:

    module.exports = {
        // ...
        theme: 'reco'
        // ...
    }  
    
    • 1
    • 2
    • 3
    • 4
    • 5

    刷新页面即可看见改变。这里就不贴具体图样了

    添加文章信息

    我们的文章必需要标题,可能需要展示文章作者信息、创建日期等信息,我们可以给文章的md文件添加一些信息修改:

    --- 
    title: 凌览的知识库 #文章标题
    author: 凌览 #作者
    date: '2023-10-24' #日期
    tags: #标题
      - 配置
      - 主题
      - 索引
    ---
    公众号【程序员凌览】
    
    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10

    此时页面效果如下:

    设置语言

    Vuepress默认使用en-US,所以日期我们明明设置的是2023-10-24,但它页面展示的是10/24/2023 。

    这里修改config.js

    module.exports = {
        // ...
        locales: {
            '/': {
                lang: 'zh-CN'
            }
         },
        // ...
    }  
    
    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9

    页面效果:

    网站部署

    到这里,我们的博客或文档算是正式做好了。接下来我们部署到免费的 Gitee Pages 上,这里有两种方式:

    • 直接在Gitee 创建一个名为vuepress-blog的仓库,手动触发Gitee Pages

    • Github创建一个名为vuepress-blog的仓库,Gitee也相同创建一个名为vuepress-blog仓库,通过Github Action 每次一次仓库更新时将Github仓库自动同步到Gitee并自动触发Gitee Pages,详情操作请阅读Github Actions实现仓库自动同步Gitee并更新文档

    (完)

    关注公粽号【程序员凌览】回复"666",拉您进【人类高质量前端交流群~】
    往期推荐:linglan01.cn/about

  • 相关阅读:
    AI 大框架基于python来实现基带处理之TensorFlow(信道估计和预测模型,信号解调和解码模型)
    计算机毕业设计之java+ssm基于android的家庭理财系统app
    安防监控视频AI智能分析网关:人流量统计算法的应用场景汇总
    小谈设计模式(15)—观察者模式
    洛谷 P1016 [NOIP1999 提高组] 旅行家的预算【贪心】
    java-net-php-python-jspm陕菜食谱网站录像(上)计算机毕业设计程序
    FME转换CAD填充块文件为SHP,并正确显示颜色符号。
    Java并发编程学习5-对象的组合
    专业硕士招生占比将达到三分之二,那么跟学术硕士有哪些区别?
    计算机的体系与结构
  • 原文地址:https://blog.csdn.net/qq_45472813/article/details/134026085