高枫 發表於 2020-4-19 17:32:00

vuepress+gitee 构建在线项目文档

<p></p><div class="toc"><div class="toc-container-header">目录</div><ul><li>快速入门<ul><li>在现有vue项目中安装本地开发依赖vuepress</li><li>在现有vue项目根目录下创建docs目录</li><li>创建并配置文档首页内容</li><li>运行，查看效果<ul><li>可能会出现vue和vue-server-renderer版本不匹配的报错</li></ul></li></ul></li><li>以下通过示例说明vuepress的基本使用方法<ul><li>最终效果预览</li><li>示例目录结构说明</li><li>页面效果和文件对应关系说明</li></ul></li><li>（Window OS）将项目文档部署到Gitee上<ul><li>创建用于部署项目文档的仓库</li><li>配置script</li><li>在项目根目录创建build.bat和deploy.bat</li><li>在config.js中加入base设置</li><li>执行脚本命令deploy(完成构建，并推送到仓库的gh-pages分支上)</li><li>开启Gitee Pages服务</li></ul></li></ul></div><p></p>
<h2 id="快速入门">快速入门</h2>
<h3 id="在现有vue项目中安装本地开发依赖vuepress">在现有vue项目中安装本地开发依赖vuepress</h3>
<pre><code>yarn add -D vuepress # 或者：npm install -D vuepress
</code></pre>
<p><img src="https://img2020.cnblogs.com/blog/758819/202004/758819-20200419171939826-1595615686.png"></p>
<h3 id="在现有vue项目根目录下创建docs目录">在现有vue项目根目录下创建docs目录</h3>
<pre><code>mkdir docs
</code></pre>
<p><img src="https://img2020.cnblogs.com/blog/758819/202004/758819-20200419172047007-1933476647.png"></p>
<h3 id="创建并配置文档首页内容">创建并配置文档首页内容</h3>
<pre><code>在docs目录下创建README.md文件
</code></pre>
<p><img src="https://img2020.cnblogs.com/blog/758819/202004/758819-20200419172125735-1685220176.png"></p>
<h3 id="运行查看效果">运行，查看效果</h3>
<pre><code>npx vuepress dev docs
</code></pre>
<p><img src="https://img2020.cnblogs.com/blog/758819/202004/758819-20200419172234888-1418814016.png"></p>
<p>访问效果如下<br>
<img src="https://img2020.cnblogs.com/blog/758819/202004/758819-20200419172326118-197662360.png"></p>
<h4 id="可能会出现vue和vue-server-renderer版本不匹配的报错">可能会出现vue和vue-server-renderer版本不匹配的报错</h4>
<p><img src="https://img2020.cnblogs.com/blog/758819/202004/758819-20200419172357125-885653119.png"></p>
<p>解决方案： 显式安装和vue版本一致的vue-server-renderer<br>
<img src="https://img2020.cnblogs.com/blog/758819/202004/758819-20200419172407106-1483785908.png"></p>
<h2 id="以下通过示例说明vuepress的基本使用方法">以下通过示例说明vuepress的基本使用方法</h2>
<h3 id="最终效果预览">最终效果预览</h3>
<p><img src="https://img2020.cnblogs.com/blog/758819/202004/758819-20200419172443500-1723021422.png"></p>
<h3 id="示例目录结构说明">示例目录结构说明</h3>
<pre><code>项目根目录
|—— docs 项目文档目录
|        |—— README.md 文档首页内容
|        |—— .vuepress vuepress配置目录
|        |        |—— config.js 主配置文件
|        |        |—— nav.js 导航栏配置文件
|        |        |—— sidebar.js 左侧栏配置文件
|        |        |—— public 静态文件目录
|        |        |        |—— img 存放图片
|        |        |        |        |—— logo.jpg logo图片
|        |        |        |—— js 存放js文件
|        |        |        |        |—— main.js自定义的js
|        |        |        |—— css 存放css文件
|        |        |        |        |—— style.css 自定义的css
|        |—— guide
|        |        |—— README.md 子模块guide的主页内容
|        |        |—— sidebar.js 子模块guide的左侧栏配置文件
|        |        |—— notes 子模块guide的文件存放目录
|        |        |        |—— one.md 文档一
|        |        |        |—— two.md 文档二
|        |—— help
|        |        |—— user
|        |        |        |—— README.md
|        |        |        |—— sidebar.js
|        |        |        |—— basic
|        |        |        |        |—— one.md
|        |        |        |        |—— two.md
|        |        |        |        |—— three.md
|        |        |        |—— senior
|        |        |        |        |—— one.md
|        |        |        |        |—— two.md
|        |        |        |        |—— three.md
|        |        |—— manager
|        |        |        |—— README.md
|        |        |        |—— sidebar.js
|        |        |        |—— daily
|        |        |        |        |—— one.md
|        |        |        |        |—— two.md
|        |        |        |—— regular
|        |        |        |        |—— one.md
|        |        |        |        |—— two.md
</code></pre>
<h3 id="页面效果和文件对应关系说明">页面效果和文件对应关系说明</h3>
<p><img src="https://img2020.cnblogs.com/blog/758819/202004/758819-20200419172525275-1794193404.png"><br>
<img src="https://img2020.cnblogs.com/blog/758819/202004/758819-20200419172536022-1676245102.png"><br>
<img src="https://img2020.cnblogs.com/blog/758819/202004/758819-20200419172544217-505901495.png"><br>
<img src="https://img2020.cnblogs.com/blog/758819/202004/758819-20200419172601889-1813409230.png"></p>
<h2 id="window-os将项目文档部署到gitee上">（Window OS）将项目文档部署到Gitee上</h2>
<h3 id="创建用于部署项目文档的仓库">创建用于部署项目文档的仓库</h3>
<p><img src="https://img2020.cnblogs.com/blog/758819/202004/758819-20200419172626804-756083212.png"></p>
<pre><code>创建过程（略）
</code></pre>
<h3 id="配置script">配置script</h3>
<p><img src="https://img2020.cnblogs.com/blog/758819/202004/758819-20200419172650371-522836328.png"></p>
<h3 id="在项目根目录创建buildbat和deploybat">在项目根目录创建build.bat和deploy.bat</h3>
<p>build.bat内容：</p>
<pre><code>@echo off
npm run docs:build
</code></pre>
<p>deploy.bat内容：</p>
<pre><code>@echo off
      
REM 构建生成静态文件
echo building...
call build.bat
echo building-complete
      
REM 进入生成的文件夹
cd docs/.vuepress/dist
      
REM 如果是发布到自定义域名
REM echo 'www.example.com' &gt; CNAME
      
git init
git add -A
git commit -m 'deploy'
      
REM 如果发布到 https://gitee.com/&lt;USERNAME&gt;
REM git push -f git@github.com:&lt;USERNAME&gt;/&lt;USERNAME&gt;.github.io.git master
      
REM 如果发布到 https://gitee.com/&lt;USERNAME&gt;/&lt;REPO&gt;
git push -f https://gitee.com/nicke/ni-report-blog.git master:gh-pages
      
cd ..
cd ..
cd ..
echo Auto-Deploy-Complete
</code></pre>
<h3 id="在configjs中加入base设置">在config.js中加入base设置</h3>
<p><img src="https://img2020.cnblogs.com/blog/758819/202004/758819-20200419172822949-259777613.png"></p>
<p>注： ni-report-blog是gitee上的仓库名</p>
<h3 id="执行脚本命令deploy完成构建并推送到仓库的gh-pages分支上">执行脚本命令deploy(完成构建，并推送到仓库的gh-pages分支上)</h3>
<p><img src="https://img2020.cnblogs.com/blog/758819/202004/758819-20200419172846741-735334558.png"><br>
<img src="https://img2020.cnblogs.com/blog/758819/202004/758819-20200419172906366-476539497.png"></p>
<h3 id="开启gitee-pages服务">开启Gitee Pages服务</h3>
<p><img src="https://img2020.cnblogs.com/blog/758819/202004/758819-20200419172925065-1436440777.png"></p>
<p>等待更新完毕，即可访问<br>
<img src="https://img2020.cnblogs.com/blog/758819/202004/758819-20200419172942361-483648604.png"></p><br><br>
来源：https://www.cnblogs.com/linnicke/p/12732456.html
頁: [1]
查看完整版本: vuepress+gitee 构建在线项目文档