团队技术文档构建利器vuepress上手实践 toc Write By CS逍遥剑仙 我的主页: www.csxiaoyao.com GitHub: github.com/csxiaoyaojianxian...一个 vuepress 网站是一个由 Vue、Vue Router 和 Webpack 驱动的单页应用。在构建时,创建一个服务端渲染(SSR)的版本,然后通过虚拟访问每一条路径来渲染对应的HTML。...目录结构 项目创建完后,最简的目录结构如下: ├─ docs │ ├─ README.md │ └─ .vuepress │ └─ config.js └─ package.json 官方推荐的完整目录结构如下...GitHub Pages 部署 发布 GitHub Pages 需要在 .vuepress/config.js 中设置正确的 base。...github.io/ # git push -f git@github.com:/.git master:gh-pages cd - 设置package.json
GitHub Pages 部署 8....一个 vuepress 网站是一个由 Vue、Vue Router 和 Webpack 驱动的单页应用。在构建时,创建一个服务端渲染(SSR)的版本,然后通过虚拟访问每一条路径来渲染对应的HTML。...目录结构 项目创建完后,最简的目录结构如下: ├─ docs │ ├─ README.md │ └─ .vuepress │ └─ config.js └─ package.json 官方推荐的完整目录结构如下...3.1.3 侧边栏(sidebar) themeConfig.sidebar 侧边栏一般用于文档的目录索引,可以直接在 config.js 中配置链接数组,也在页面中配置 sidebar:auto 自动生成侧边栏目录...GitHub Pages 部署 发布 GitHub Pages 需要在 .vuepress/config.js 中设置正确的 base。
你可以使用 Markdown在新窗口打开 来书写内容(如文档、博客等),然后 VuePress 会帮助你生成一个静态网站来展示它们。...一个 VuePress 站点本质上是一个由 Vue在新窗口打开 和 Vue Router在新窗口打开 驱动的单页面应用 (SPA)。 路由会根据你的 Markdown 文件的相对路径来自动生成。...在构建过程中,我们会为 VuePress 站点创建一个服务端渲染 (SSR) 的版本,然后通过虚拟访问每一条路径来渲染对应的 HTML 。...目录 如果你想要把当前页面的目录添加到 Markdown 内容中,你可以使用 [[toc]] 语法。 代码块 下列代码块扩展是在 Node 端进行 Markdown 解析的时候实现的。...无论你是单独部署到 nginx 还是 GitHub Pages、Gitlab Pages 上。否则可能会样式文件找不到导致网页加载不正常。
前言 本文主要介绍如何在Windows环境本地部署 Docsify 这款以 markdown 为中心的文档编辑器,并即时生成您的文档博客网站,结合cpolar内网穿透还能将博客一键发布至公网允许所有人访问...如果你想要开始使用他,只需要创建一个index.html就可以开始编写文档并直接部署在GitHub Pages。...,可以在文中添加表情 兼容IE11 支持服务端渲染SSR 接下来,讲解如何在本地部署Docsify。.../docs 目录下创建的几个文件 index.html 入口文件 README.md 会做为主页内容渲染 .nojekyll 用于阻止 GitHub Pages 忽略掉下划线开头的文件 直接编辑 docs...开启渲染封面功能后在文档根目录创建 _coverpage.md 文件。渲染效果如本文档。 index.html window.
/2.2.1/github-markdown.css"/> (一)TOC 看内容目录就是用[[toc]]生成的 注:只要放置:[[TOC]],就能把其后面的标题如:#,##,......######自动生成目录树,注意,[[TOC]]要独立一行,并前面和后面都要空一行 示例如下图所示: ?...TOC目录的使用 (二)直接支持html,css 如果你懂html和css,那下面这些效果就不在话下了: 使用示例: * 页内跳转 来个页内跳转,跳转到文未的...- title: 高性能 details: VuePress 为每个页面预渲染生成静态的 HTML,同时在页面被加载的时候,将作为 SPA 运行。...github.io/ # git push -f git@github.com:/.git master:gh-pages cd - ---- 八、遇到的一些错误
,主要分两类,一类是动态的,有数据库,有后台管理界面,可以在后台管理中去发布文档;一种是静态的,基本就是提供写好的markdown,然后部署到服务器上,用特定技术预先渲染成html,再利用nginx之类的指向这些.../guides/blogging image-20231021161050857 该网站的搜索效果是做不出来的,这个是对接了专门的搜索网站 对应的github:https://github.com/enspiral...,node目前最新的长期支持版本是v18.18.2,但是,在centos7.9上,都是用不了的。...可以看下面的具体报错,是node v18版本依赖了高版本的glic库,而这个库在centos 7.9上没有;同时,也需要安装高版本的gcc,才能运行不报错,而这个高版本的gcc在centos 7.9上也没有...编译为html 其实在执行上面的npx honkit serve后,就生成了index.html和相关的资源文件,在当前目录的_book目录下: image-20231021170724174 编译的命令
登陆 GitHub,然后点击进入你博客的仓库,然后 Settings-GitHub Pages-Custom domain,里面填上你的需要绑定的域名。...3.1.不能上传 README.md 文件 GitHub 不能上传 README.md 文件,对于强迫症患者来说,这是不能接受的,如果按普通做法的话,当你生成静态文件然后上传的时候,hexo 会自动把...README.md渲染成README.html,内容也变了,就因为这个,差点重装用另一种方法。...但是经过一番摸索,搞定,下面是方法: 在博客目录下的 source 文件夹下新建README.md 文件: ?...上看,会发现久违的 README.md 文件出现了,这才完整,赏心悦目。
/docs 会生成如下目录: -| docs/ -| .nojekyll 用于阻止 GitHub Pages 会忽略掉下划线开头的文件 -| index.html 入口文件 -...| README.md 会做为主页内容渲染 直接编辑 docs/README.md 就能更新网站内容 遇到的问题: 初始化docsify文档不成功 升级node.js之后就成功了 ?...,可配置最大支持渲染的标题层级。...subMaxLevel: 4, // 生成目录的最大层级 mergeNavbar: true, // 小屏设备下合并导航栏到侧边栏 alias: { // 定义路由别名,可以更自由的定义路由规则...GitHub Pages配置 ?
自从几年前开始在 GitHub 玩耍,接触到 Markdown 之后,就一发不可收拾,在各种文档编辑上,有条件用 Markdown 的尽量用,不能用的创造条件也要用——README、博客、公众号、接口文档等等全都是...展示数学公式 如果是在 GitHub Pages,可以参考 http://wanguolin.github.io/mathmatics_rending/ 使用 MathJax 来优雅地展示数学公式(非图片...网页上部的输入框里输入 LaTeX 公式,比如 $x=\frac{-b\pm\sqrt{b^2-4ac}}{2a} 在网页下部拷贝 URL Encoded 的内容,比如以上公式生成的是 https:...有时候维护一份比较长的文档,希望能够自动根据文档中的标题生成目录(Table of Contents),并且当标题有变化时自动更新目录,能减轻工作量,也不易出错。...如果你使用 Vim 编辑器,那可以使用我维护的插件 vim-markdown-toc 来帮你完美地解决此事: english.gif 插件地址:https://github.com/mzlogin/vim-markdown-toc
自从几年前开始在 GitHub 玩耍,接触到 Markdown 之后,就一发不可收拾,在各种文档编辑上,有条件用 Markdown 的尽量用,不能用的创造条件也要用——README、博客、公众号、接口文档等等全都是...展示数学公式 如果是在 GitHub Pages,可以参考 http://wanguolin.github.io/mathmatics_rending/ 使用 MathJax 来优雅地展示数学公式(非图片...有时候维护一份比较长的文档,希望能够自动根据文档中的标题生成目录(Table of Contents),并且当标题有变化时自动更新目录,能减轻工作量,也不易出错。...如果你使用 Vim 编辑器,那可以使用我维护的插件 vim-markdown-toc 来帮你完美地解决此事: ?...插件地址:https://github.com/mzlogin/vim-markdown-toc 如果你使用其它编辑器,一般也能找到对应的解决方案,比如 Atom 编辑器的 markdown-toc 插件
但是文字稿实在是又臭又长,这些平台似乎都不太是一个好的载体。而 GitHub Pages 使用 Jekyll[4] 渲染,但只支持寥寥几个免配置的主题,怎么说呢,就都挺丑的。...],原文托管在 github[8] 上,欢迎大家拍砖,不吝赐教,多提 issue、pr。...Docsify Docsify 一个文档向的静态网页生成工具,配合 GitHub Pages 使用,体验绝佳。...初始化 初始化一个 GitHub repo,然后使用 docsify 初始化:docsify init . ,会生成: README.md:文档的首页。...此外,如果你的 repo 本来有 _config.yml(JekyII 默认配置文件)通常还生成一个空的文件 .nojekyll来禁止 GitHub Pages 启用 JekyII 来渲染。
只有将页面和页面内引用到的资源信息进行汇总,最终才能生成全书的 资源清单、书脊 和 导航目录。 这就需要我们在过程中一边渲染和生成文件,一边整理相关信息。...最后由它统筹生成上面提到的基础信息,打包成书,随后清理临时目录。...2) 转换目录结构,渲染全书 之前我们在 book.config 内定义的 pages 字段是一个树形结构,便于我们日常灵活调整和更新,但最终需要生成的资源清单和书脊却是一维线性的(与真实书籍的纸张排列一样...并且我们对 list 内节点的引用的方式,保留原目录数据的基本树形结构,便于之后生成树形的导航目录。...前者我们可以根据之前的 pageTree 递归拼出目录部分的 html 结构,再通过通用的 render() 函数渲染生成,并加入到 manifestList 内: const parseToc = (
/docs 子目录中编写文档,将该目录初始化: docsify init ./docs 初始化后系统帮我们生成了一个 ..../docs 目录,目录中包含以下文件: index.html:入口文件 README.md:将作为主页渲染 .nojekyll:阻止 Github Pages 忽略以下划线开头的文件 预览 使用以下命令启动本地服务器...部署到 Github Pages 我的 Github Pages 读取的是 gh-pages 分支下的代码,因此我要把 ..../docs 下的文件上传到 gh-pages 分支上,完整的代码则上传的到 master 分支。...为了方便更新,我在项目根目录下放置了一个用于推送代码的脚本 push.sh: message=$1 # 复制 README.md cp README.md docs/README.md # 更新 master
/usr/bin/env sh # 确保脚本抛出遇到的错误 set -e # 生成静态文件 npm run docs:build # 进入生成的文件夹 cd docs/.vuepress/dist.../usr/bin/env sh # 确保脚本抛出遇到的错误 set -e # 生成静态文件 npm run docs:build # 进入生成的文件夹 cd docs/.vuepress/dist...(GitHub会自动将此分支代码部署到pages页面中)则删除,并将本地的master分支推到远程的gh-pages,在根目录下运行....可以写简单的配置就能渲染跟 Vue一样 的主页,只需在docs文件夹目录下创建一个README.md --- home: true // 为true则开启主页 # heroImage: hi //...install目录,此路径表示读取install目录下的README.md文件 '/get-started/', ] }, {
效果预览: https://rodert.github.io/JavaPub-Interview/ [在这里插入图片描述] @toc 准备 你需要已有的环境:node、git、npm 快速安装脚手架:...[在这里插入图片描述] 1. index.html:入口文件,docsify 的各项配置都在此页面设置。 2. README.md:默认展示的首页就是 README.md 里的内容。...3. .nojekyll:用于阻止 GitHub Pages 会忽略掉下划线开头的文件。 <!...docsify = { name: 'rodert', repo: 'https://gitee.com/rodert/rodert', maxLevel: 5,//最大支持渲染的标题层级...新建仓库 提交项目 开启 Github Pages 同步国内Gitee、访问速度 现在Github网络非常不稳定,在码云部署一份 导入 Github 项目 选择 -> 服务 -> Gitee Pages
码云 CommonMark 解析器 之前码云的解析器基于用户的反馈做了很多定制化的修改。 但是随着使用码云的用户越来越多,以及越来越多的Github用户往码云上迁移,我们收到了很多用户反馈。...始料不及,在Github正常解析渲染的Readme在码云上渲染出来的结果却有所出入。 ? ? 讨论再三,我们决定将码云的 Markdown 解析器更换为 CommonMark。 更改后的差异如下。...01 标题#后面需要有空格才会正确渲染标题 ? 02 正确解析形如 Map> 的文本 ?...07 解决内容中不留空格无法加粗的问题 ? 08 支持--构建表格 ? ? 09 不再支持[TOC] 标准的Markdown是不支持[TOC]标签的,可以通过a标签的方式自行创建目录。 ?...码云上Readme后缀说明 码云为了适应不同种类的开源项目的Readme显示,有不同的优先显示规则,如下: 如一个项目有Readme.osc.md 也有 Readme.md,那么在码云上则优先显示 Readme.osc.md
安装node插件 npm global install markdown-toc 2.使用 文件内容 // README.md 文件 # 测试markdown-toc 生成目录 ### 目录1 目录1内容 ### 目录2 目录1内容 ### 目录3 目录1内容 ### 目录4 目录1内容 使用命令 # 在README.md文档中需要生成目录地方添加...-- toc --> # 使用命令 markdown-toc -i ./README.md 生成文件 # 测试markdown-toc 生成目录 - [目录1](#%E7%9B%AE%E5%BD%951) - [目录2](#%E7%9B%AE%E5%BD%952) - [目录3](#%E7%9B%AE%E5%BD%953)...-- tocstop --> ### 目录1 目录1内容 ### 目录2 目录1内容 ### 目录3 目录1内容 ### 目录4 目录1内容 如此既可在github上使用目录查看了
Jekyll 生成目录的方案 如参考资料 1 中所提到的,如果想要在 Jekyll 中实现文章目录,有三种不同的方案可供选择: 第一种方案 利用完整的标签来生成静态目录,可以看到在本文的开头就是这样的一个实例...缺点在于 Github Pages 不支持这类自定义插件,你可能需要使用自定义的 workflow.yml 文件来指导 Github Action 来编译生成静态文件。...如果不怎么了解 Github Action,恐怕这种方式部署在 Github Pages 上也不是很省心。...实践 从上述三种方案综合来看,第三种方案能够同时支持自动生成目录和 Github Pages,比较适合预期的需求。...目录生成 目录生成这里直接采用的是上述的第三种方案。具体在 post 模板页使用 toc 模块的代码如最后所示。
Vite 的出现很好地解决了这些问题:近乎即时的服务器启动、仅编译所服务页面的按需编译以及闪电般快速的 HMR。 VuePress v1 在本质上是一个 Webpack 应用程序。...run dev具体文档文件结构vite-plugin-react-pages其实也可以通过 https://github.com/vitejs/vite-plugin-react-pages 生成vite-plugin-react-pages... vite-pages [仓库名] --template [模板名]我们执行 npm init vite-pages library-demo --template lib 生成了一个典型的 Vite...依赖 react-router-dom ^5.0.0 版本pages 目录为文档入口。...: { // markdown-it-anchor 的选项 anchor: { permalink: false }, // markdown-it-toc 的选项 toc: {
想要将docsify生成的文档网站发布出去,以前我们会选择GitHub Pages来进行网站托管。但由于GitHub是国外网站,会导致你的文档网站访问速度较慢。...docsify init mydocs 会在当前目录下创建mydocs目录,目录结构如下: README.md 入口文件 index.html 会做为主页内容渲染 .nojekyll 用于阻止 GitHub...Pages 会忽略掉下划线开头的文件,不用关心 直接编辑 README.md 就能更新网站内容,当然也可以写多个页面。...在文件管理页,点击上传文件,将本机mydocs目录下的index.html与README.md两个静态文件进行上传。 ? 进入到设置页,使用默认域名即可访问到我们的文档网站啦!...One More Thing 只需简单的几步,你就可以轻松实现将创作好的文档网站部署到云开发上供大家访问了,无需再忍受 Github Pages 的龟速啦!现在还可以0元迁移哦!
领取专属 10元无门槛券
手把手带您无忧上云