团队技术文档构建利器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/', ] }, {
码云 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
效果预览: 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
安装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: {
/09/16: GitHub Pages 现在已经改为只支持 kramdown),而其它放在 GitHub 仓库里的文档使用 GFM,我决定为我常用的 Markdown 编辑器 Vim 做一款同时支持...GFM 和 Redcarpet 两种 TOC 链接风格的 Table of Contents 自动生成插件。...这算是我真正意义上完全独立开发的第一款实用 Vim 插件,当然开发过程中也参考了别人的做法。...适用于 GitHub 仓库里的 Markdown 文件,比如 README.md,也适用用于生成 GitBook 的 Markdown 文件。...屏幕截图 使用本插件生成 TOC 的英文文档在线示例 english.gif 使用本插件生成 TOC 的中文文档在线示例 chinese.gif
领取专属 10元无门槛券
手把手带您无忧上云