时间:2023-05-29 13:15:01 | 来源:网站运营
时间:2023-05-29 13:15:01 来源:网站运营
使用 Hexo 创建项目文档网站:当我们发布一个开源项目的时候,最重要的事情之一就是要创建项目文档。对使用项目的用户来说,文档是非常有必要的,通常我们可以使用下面这些方式来创建文档:$ nvm install v8.1.3
安装完 Node.js 的同时也会安装对应的 npm。$ git --version
如果出现了 Git 的版本号,则不需要再安装了。如果没有,则需要安装 Git。$ sudo apt-get install git-core
$ sudo yum install git-core
$ npm install -g hexo-cli
通过下面的命令来检查 hexo 是否正确安装上了:$ hexo --version
如果输出了一系列的版本号,说明所有安装工作都以完成,可以正式使用 hexo 了。$ git clone https://github.com/USERNAME/REPOSITORY.git
将 USERNAME 替换为你的用户名,REPOSITORY 替换为你的项目名称。例如我执行的命令如下:$ git clone https://github.com/nodejh/hexo-documentation
然后使用 cd 进入项目目录,并创建一个名为 docs 的目录:$ cd hexo-documentation$ mkdir docs
docs 目录将存放我们的文档。使用 hexo 初始化 docs 目录:$ hexo init docs
上面的命令将生成 hexo 的一些配置并安装相关依赖。安装完成之后,docs 的目录结构如下:$ hexo generate$ hexo server
第一个命令将根据选用的主题,将 sources 目录中的文件转换成静态网站文件。第二个命令将启动一个 Web 服务器,提供这些静态网站文件,我们可以通过 http://localhost:4000 来访问:$ npm install --save hexo-renderer-sass
然后回到 themes 目录里面,配置 Sass,不然 hexo-renderer-sass 插件不会被加载。在 docs/themes/documentation/_config.yml 文件中加入下面的代码:node_sass: outputStyle: nested precision: 4 sourceComments: false
Sass 的所有可配置在 node-sass<!DOCTYPE html><html><head> <meta charSet='utf-8' /> <title>{{config.title + ' - ' + page.title}}</title> <link href='https://cdnjs.cloudflare.com/ajax/libs/normalize/4.0.0/normalize.min.css' rel='stylesheet' type='text/css'> <link href='https://fonts.googleapis.com/css?family=Open+Sans:400,600,300,700' rel='stylesheet' type='text/css'> <link href='{{ url_for("css/docs.css") }}' rel='stylesheet'></head><body> <div class='menu'> <div class='logo'> Documentation </div> <nav class='menu-nav'> {% for section in site.data.nav %} <ul class='nav'> <span>{{ section.title }}</span> <ul class='nav'> {% for item in section.items %} <li> <a href='{{item.href || url_for(item.id + ".html") }}'{% if item.id == page.id %} class='active'{% endif %}>{{item.title}}</a> </li> {% endfor %} </ul> </ul> {% endfor %} </nav> <a class='footer' href='https://github.com/sitepoint-editors/hexo-documentation'> Project on github </a> </div> <div class='page'> <div class='page-content'> <h1>{{page.title}}</h1> {{page.content}} </div> </div> <div class='switch-page'> {% if page.prev %} <a class='previous' href='{{ url_for(page.prev) }}'>Previous</a> {% endif %} {% if page.next %} <a class='next' href='{{ url_for(page.next) }}'>Next</a> {% endif %} </div></body></html>
简单分析一下代码。<head> <meta charSet='utf-8' /> <title>{{config.title + ' - ' + page.title}}</title> <link href='https://cdnjs.cloudflare.com/ajax/libs/normalize/4.0.0/normalize.min.css' rel='stylesheet' type='text/css'> <link href='https://fonts.googleapis.com/css?family=Open+Sans:400,600,300,700' rel='stylesheet' type='text/css'> <link href='{{ url_for("css/docs.css") }}' rel='stylesheet'></head>
头部主要包括两部分:<nav class='menu-nav'> {% for section in site.data.nav %} <ul class='nav'> <span>{{ section.title }}</span> <ul class='nav'> {% for item in section.items %} <li> <a href='{{ item.href || url_for(item.id + ".html") }}' {% if item.id == page.id %} class='active' {% endif %} > {{ item.title }} </a> </li> {% endfor %} </ul> </ul> {% endfor %}</nav>
上面的代码会生成网站的菜单部分,菜单项来自于 site.data.nav 这个对象,稍后我们会在 docs/source/_data/nav.yml 中创建。source/_data 是 Hexo 的数据文件。site.data.nav 即 _data 目录中的 nav.yml 文件。nav.yml 中是一个包含 title 和 items 对象的数组。<div class="page-content"> <h1>{{ page.title }}</h1> {{ page.content }}</div>
这里面包括了文章标题和内容两部分。文章内容是根据 MarkDown 文件生成的 HTML。{% if page.prev %} <a class='previous' href="{{ url_for(page.prev) }}">上一页</a>{% endif %}{% if page.next %} <a class='next' href="{{ url_for(page.next) }}">下一页</a>{% endif %}
上面的代码中,我们假设每个页面都有 “上一页” 和 “下一页” 按钮。<!DOCTYPE html><html><head> <meta charSet='utf-8' /> <title>{{config.title + ' - ' + page.title}}</title> <link href='https://cdnjs.cloudflare.com/ajax/libs/normalize/4.0.0/normalize.min.css' rel='stylesheet' type='text/css'> <link href='https://fonts.googleapis.com/css?family=Open+Sans:400,600,300,700' rel='stylesheet' type='text/css'> <link href='{{ url_for("css/docs.css") }}' rel='stylesheet'></head><body> <div class='index'> <a href="/what-is-it.html"> Get Start </a> </div></body></html>
现在差不多就完成了!不仅是布局文件完成了,我们的主题也制作好了。最后一件事情就是修改 Hexo 生成静态文件的时候使用的主题。修改 docs/_config.yml 文件中的 theme 属性:theme: documentation
所有事情都做完了!接下来我们就可以创建文档了。- title: Introduction items: - id: what-is-it title: What is it? - id: how-it-works title: How it works- title: Usage items: - id: installation title: Installation - id: using title: Using It
这样我们就可以通过 site.data.nav 来访问 nav.yml 中的文件。---layout: defaultid: what-is-ittitle: What is it?next: how-it-works.html---This is our what it is markdown file- one- two- three
在 front-matter 中有下面这些设置:$ hexo generate$ hexo server
然后通过 http://localhost:4000 就可以看到如下页面:$ npm install --save hexo-deployer-git
然后打开 docs/_config.yml,在文档的最后面,修改部署配置信息,注意将其中的用户名(nodejh)修改为你的用户名:deploy: type: git repo: https://github.com/nodejh/hexo-documentation branch: gh-pages message: "Docs updated: {{ now('YYYY-MM-DD HH:mm:ss') }})"
最后再修改一些其他配置:# Sitetitle: Hexo documentationsubtitle: Hexo documentation articledescription: Hexo documentation articleauthor: nodejhlanguage: zh-cntimezone: GMT# URLurl: https://nodejh.github.io/hexo-documentationroot: /hexo-documentation/
OK!现在就只剩下一件事情了,就是将网站部署到 Github 上,在终端上运行:$ hexo generate$ hexo deploy
Hexo 将生成静态文件,并将其自动部署到 gh-pages 分支上。部署完成之后,我们就可以通过 https://nodejh.github.io/hexo-documentation 来访问了。关键词:项目,创建,使用