如何利用github pages搭建gatsby静态博客

这是一个简单的关于如何利用github自带的github pages搭建gatsby博客的教程,现在国内的教程以及相关文档都实在太少。官方的文档也并没有很好地描述了该如何利用github pages进行部署自己的个人博客。可是gatsby又极其先进地使用了react构建了整体的框架,在我找到它的时候,我感觉它满足了我的热部署的所有需求。

1
除此之外,能够进行热部署的博客框架还有vuejs构成的NUXT。

在开始搭建这个博客之前,我们要先说明具体流程:

  • 首先是本地的环境的部署,先后下载node.js,git,gatsby,yarn,react等。
  • 利用gatsby下载并生成一个基础的网页,可以在本地访问一下看看效果。
  • 将git和github连接起来。并且创建一个基础的github page页面。绑定域名等。
  • 将gatsby生成的文件通过git推送到你的git仓库中。也就是github pages对应的git仓库中。
  • 输入你的域名,并且进行访问。
  • 完成。

在浏览本文前,请先粗略看一下官方文档:https://www.gatsbyjs.org/docs/

先是本地环境的搭建,这里是接下来需要拷贝的代码的副本:gatsbycode

首先需要先根据自己的系统下载一个最新的node.js安装包,node.js是一个能够在服务器端运行JavaScript的开放源代码、跨平台JavaScript运行环境。简单来说,静态博客的本地运行调试需要用到它的很多模组。

当前最推荐的版本是8.9.3,而最新版本已经为9.3.0

建议自行前往这里下载并且安装对应自己喜欢的版本:node.js下载

安装过程不细说,安装完毕以后,用win+R调出CMD命令行窗口,分别输入以下代码:

1
2
npm -v    //这里这两个代码的意思是检查它们的版本,
node -v //只有安装成功的情况下,才能显示数字。

如果看到以下显示就证明安装成功,接下来就能够调用npm来下载或者用node来构建服务器了。如果安装不成功,请先卸载相关内容再重新安装。

img

然后由于关于git和tortoise git的安装配置过程几乎可以再写一篇全解文章,所以在此略过,这里是相关的官网下载。

注意!:git一定要注意path的设定以及tortoise git也需要注意用户的设置

tortoise软件以及中文版补丁下载在https://tortoisegit.org/download/

git软件下载在https://git-scm.com/downloads


让我们回到本地环境的配置上,刚刚说到已经下载完了npm和node,实际上在接下来的过程中,我们并不需要用到node。

我们首先来安装gatsby的cli

1
npm install --global gatsby-cli

这个能够让你在接下来的过程中使用gatsby来下载以及生成相关站点。

Gatsby 的 CLI包含了许多常见的开发特性,比如gatsby build(构建一个生产、静态生成的项目版本)、gatsby develop(启动一个热加载的web开发服务器)等等。

然后让我们用刚刚下载安装好的npm来安装另外一个包管理:yarn

yarn在某种程度上比npm更先进。

运行cmd/git bash,并且输入下列代码:

1
npm install --global yarn

在随意一个非中文字符相关的盘中新建一个文件夹。

然后用刚刚git下载安装完毕后的git bash通过cd命令进入到当前文件夹。输入以下生成网站的代码以及进入网站目录:

1
gatsby new personal-blog && cd $_

你可能看到的目录结构和下面的图相似:

img

为你的gatsby博客生成构建安装插件:

插件可以分为三个主要类别:功能( functional )插件、源( source )插件和转换器( transformer )插件。

下方这两个是功能插件

1
yarn add gatsby-plugin-catch-links gatsby-plugin-react-helmet

功能插件的大致解释为:

  • gatsby-plugin-catch-links
    • 实现了历史 pushState API, 不需要页面重载就可以导航到博客的不同页面, 大大地加快页面访问的速度
  • gatsby-plugin-react-helmet
    • react-helmet 是一种允许实时修改head标签的工具 ,而后让Gatsby 静态地呈现这些头部标签的变化,简单来说就是为了热部署而生的一个功能插件

下方这个是源插件:

1
yarn add gatsby-source-filesystem

这个源插件的解释(比较重要,大多数情况报错都是因为这个)为:

源插件创建节点,然后通过一个转换器插件将其转换为可用的格式。例如,一个典型的工作流通常需要使用gatsby-source-filesystem它从磁盘上加载文件,例如 Markdown 文件,然后指定一个 Markdown 转换器(马上出现)将 Markdown 转换成 HTML 。

下方这个是转换插件:

1
yarn add gatsby-transformer-remark
  • 使用 remark Markdown解析器进行转换磁盘上的 md 文件为 HTML 。 此外,该转换器还可以选择使用插件来进一步扩展功能,例如通过gatsby-remark-prismjs来添加语法高亮,通过gatsby-remark-copy-linked-files复制在 markdown 中指定的相关文件,通过 gatsby-remark-images 压缩图像,并使用 srcset 添加响应性图像等等。

让我们编辑刚刚生成的网站源文件里面的gatsby-config.js,具体目录应当为 ~/personal-post/gatsby-config.js。在里面随便找个地方插入下边的代码,分别是将上述三个插件放进去。

编辑的时候一定要注意!符号是否正确!是否有相应符号的缺少!不然会报错!

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
module.exports = {
siteMetadata: {
title: `BonXG-Blog`, //自行修改
author: `Bon`, //自行修改
},
plugins: [
'gatsby-plugin-catch-links', //功能插件
'gatsby-plugin-react-helmet', //功能插件
{
resolve: `gatsby-source-filesystem`, //源插件
options: {
path: `${__dirname}/src/pages`, //所找到的文件目录
name: 'pages',
},
},
{
resolve: 'gatsby-transformer-remark', //转换器插件
options: {
plugins: [] // 你能在这里放入语法高亮等插件
}
},
]
}

然后让我们生成第一个博客文章吧!

编写一个markdown文件,命名为index.md,写入以下内容(其实可以随意,但是建议这样写,上下的符号是建议存在)。放入/personal-blog/src/pages里面(给它新建一个文件夹,最好是用时间命名,以后也好管理。我的是这样的:/personal-blog/src/pages/12-14-2017-getting-started。)

1
2
3
4
5
6
7
---
path: "/hello-world" //表示后续看到自己这个文章的代码
date: "2017-12-14T14:14:33.962Z"
title: "My First Gatsby Post"
---

Oooooh-weeee, my first blog post!

让我来解释一波:

被包含在横线里面的就是所谓的frontmatter,是给react组件拿来使用的。你可以说随便试一下,因为毕竟不会boom。而我们使用gatsby build这个热部署命令的时候,在这个例子里面,也就是上述代码里面,我们可以在http://localhost:8000/hello-world。这个地址中看到自己的文章。


接下来让我们创建一个react的模板:

我们创建一个 /personal-blog/src/templates/blog-post.js文件(请创建一个src/templates文件夹)

然后往里面加上下边的代码:

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
26
27
28
29
30
import React from 'react';
import Helmet from 'react-helmet';
// 还能import '../css/blog-post.css';
export default function Template({
data
}) {
const { markdownRemark: post } = data;
return (
<div>
&lt;Helmet title={`Your Blog Name - ${post.frontmatter.title}`} /&gt;
<div>
<h1>{post.frontmatter.title}</h1>
<div />
</div>
</div>
);
}

export const pageQuery = graphql` //graphql查询,关于这个查询,具体请参考别的文档
query BlogPostByPath($path: String!) {
markdownRemark(frontmatter: { path: { eq: $path } }) {
html
frontmatter {
date(formatString: "MMMM DD, YYYY")
path
title
}
}
}
`;

里面分别用到了react模板和graphql查询,关于这两个的细节不在这里展开,但是这个是建完以后就可以使用的了。如果有兴趣,请参考文章最后写出来的引用文章。


接下来让我们开始创建静态页面

用文本编辑器打开编辑/personal-blog/gatsby-node.js,加入下列代码后保存:

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
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
const path = require('path');

exports.createPages = ({ boundActionCreators, graphql }) =&gt; {
const { createPage } = boundActionCreators;

const blogPostTemplate = path.resolve(`src/templates/blog-post.js`);

//上边引用了gatsby的createPages的api,感兴趣的人可以去官网看一下。

return graphql(`{
allMarkdownRemark(
sort: { order: DESC, fields: [frontmatter___date] }
limit: 1000
) {
edges {
node {
excerpt(pruneLength: 250)
html
id
frontmatter {
date
path
title
}
}
}
}
}`)
.then(result =&gt; {
if (result.errors) {
return Promise.reject(result.errors);
}

//上述代码则进行了graphql查询。

result.data.allMarkdownRemark.edges
.forEach(({ node }) =&gt; {
createPage({
path: node.frontmatter.path,
component: blogPostTemplate,
context: {} // 额外的数据可以加载在这里
});
});
});
}

//graphql查询的延伸:result.data.allMarkdownRemark.edges

实际上上述的代码就进行了三个步骤

  • 生成页面
  • 基于markdown节点进行graphql查询
  • 额外的特定的graphql查询

具体的技术细节不在这里展开,改日我会根据这个文章写出react模板实际的原理。


以上的所有操作都保存完以后。接下来就是见证奇迹的时候,在/personal-blog/中用git bash输入gatsby develop或者yarn develop

然后打开你的浏览器,输入

1
http://localhost:8000/hello-world

会看到

img

完成!!

你可以试一下在你的pages文件夹里面随意创建一个静态的js文件,它都会自动被编译生成html,而且这个过程是实时改变的,这就是React的魅力。

试一下创建一个tags.js

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
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
import React from 'react';
import Link from 'gatsby-link';
import Helmet from 'react-helmet';

// import '../css/index.css'; // 加载你喜欢的cssssssss!

export default function Index({
data
}) {
const { edges: posts } = data.allMarkdownRemark;
return (
<div>
{posts
.filter(post =&gt; post.node.frontmatter.title.length &gt; 0)
.map(({ node: post }) =&gt; {
return (
<div>
<h1>
&lt;Link to={post.frontmatter.path}&gt;{post.frontmatter.title}&lt;/Link&gt;
</h1>
<h2>{post.frontmatter.date}</h2>
<p>{post.excerpt}</p>
</div>
);
})}
</div>
);
}

export const pageQuery = graphql`
query IndexQuery {
allMarkdownRemark(sort: { order: DESC, fields: [frontmatter___date] }) {
edges {
node {
excerpt(pruneLength: 250)
id
frontmatter {
title
date(formatString: "MMMM DD, YYYY")
path
}
}
}
}
}
`;

在一会儿,你就能够通过这个来访问了

1
http://localhost:8000/tags/

会显示下方的页面

img

完美!接下来,你会发现当你编辑md文件的时候,这里也会实时改变。

而当你增加目录,增加静态js的时候,你都能在片刻以后访问到这个的站点。如果出现错误,具体的报错信息都会出现在你的命令行窗口里面。

而接下来如果需要部署到github仓库则需要使用gatsby deploy命令。然后部署到自己的example.github.io中后,即可用https://example.github.io访问了。

此外如果需要用别人的模板,则去官网上下载对应的templates文件,替换后即可。

谨记!关于部署的知识,这里不展开,但是这也是一个极大的难点

推荐

Dustin Schau:https://github.com/dschau/blog


到目前为止我们已经说完了gatsby的网页生成全流程。

让我们接着说说git和github的连接以及部分的坑,将会在我的下一篇文章中把剩下的都说完。


谢谢阅读

本文章参考了

众成翻译:用gatsby搭建一个博客

Dustin Schau:creating a blog with gatsby


欢迎观看如何用小内存vps搭建个人用zimbra

下一次目标:讲述关于nlp的那些事

本文作者: Bon
本文地址https://bonxg.com/p/2.html
版权声明:本博客所有文章除特别声明外,均采用 CC BY-NC-SA 3.0 CN 许可协议。转载请注明出处!

# Bon
Your browser is out-of-date!

Update your browser to view this website correctly. Update my browser now

×