使用pelican搭建一个Jupyter Notebook数据科学博客

来源：互联网发布：数据录入公司编辑：程序博客网时间：2024/05/23 19:14

前言：这里是我最终搭建的博客，可以先预览看一下效果，这里是 github 地址, 欢迎 fork and star !

写博客是一个证明你的技能，进一步加深学习和积累受众的一个非常好的方式。已经有非常多的数据科学和编程博客帮助它们的作者找到工作，或是建立了非常重要的联系。撰写博客是任何一个有想法的programmer或数据科学家在日常基础之上非常重要的一件事情。

不幸的是，写博客一个不可忽视的障碍便是首先如何搭建一个博客。在本文，我们将会涉及到如何使用Python创建博客，如何使用Jupyter notebook写博客和如何使用GitHub Pages部署博客。读完本文，你应当能够创建属于你自己的博客，并以一种熟悉简单地方式写文章。

静态网站

根本上，一个静态网站只不过是一个由HTML文件构成的文件夹而已。我们可以运行一个服务器来使得其他人访问并获取这些文件。它的一个好处就是不需要一个数据库或是其他一些动态交互的部分，而且非常容易将其部署到像GitHub这样的网站。

将你的博客构建成为一个静态网站是一个非常好的想法，因为它维护起来极其简单。创建静态网站的一个方式是手写HTML, 然后将所有的HTML文件上传到服务器。在这样的情况下，你至少需要一个index.html文件。如果你的网站URL是thebestblog.com, 那么访问者访问http://thebestblog.com时将会被展示index.html的内容。下面是thebestblog.com可能的HTML构成：

thebestblog.com│   index.html│   first-post.html│   how-to-use-python.html│   how-to-do-machine-learning.html│   styles.css

在上面的网站中，访问http://www.thebestblog.com/first-post.html将会展示first-post.html文件中的内容。first-post.html可能像这样：

<html><head>  <title>The best blog!</title>  <meta name="description" content="The best blog!"/>  <link rel="stylesheet" href="styles.css" /></head><body>  <h1>First post!</h1>  <p>This is the first post in what will soon become (if it already isn't) the best blog.</p>  <p>Future posts will teach you about data science.</p><div class="footer">  <p>Thanks for visiting!</p></div></body></html>

你可能很快会发现手写HTML会有一些问题：

手写HTML相当痛苦。
如果要写多篇文章，你将不得不复制HTML的风格，和诸如标题，页脚等重复的元素。
如果想要集成评论或是其他一些插件，你不得不写JavaScript。

通常来说，当写博客的时候，你希望能够关注内容而不是将时间花费在调整HTML上。幸好，使用静态网站生成器这个工具，你就可以摆脱手写HTML了。

静态网站生成器

静态网站生成器允许你使用一个简单的格式写博客文章，比如markdown, 然后定义一些设置即可。生成器将会自动将你的文章转换成HTML。通过静态网站生成器，我们可以将first-post.html简化为first-post.md:

# First post!This is the first post in what will soon become (if it already isn't) the best blog.Future posts will teach you about data science.

这要比手写HTML要容易得多！一些通常的元素，比如标题或是页脚，可以被放到模板中，所以它们也很容易修改！

有一些不同的静态网站生成器，非常出名的一个便是用ruby写的jekyll (译者注：我的jekyll blog，有兴趣的可以看一下)。由于想搭建一个数据科学博客，所以我们需要一个能够处理Jupyter notebook的静态生成器。

Pelican是用Python写的一个静态网站生成器，它能够将Jupyter notebook文件转换成HTML博客文章。Pelican也十分容易部署到GitHub Pages, 其他人可以在那里阅读我们的文章。

安装Pelican

在开始之前，可以在这里先看一下我们最终完成的一个示例。(译者：这里是译者搭建的pelican博客, 与原文稍有不同，部署在github的project下)

如果你还没有安装python, 那么在开始之前你需要进行一个准备工作的安装。推荐使用python3.5。

Python一旦安装完成，我们可以进行以下操作：

创建一个文件夹 – 我们将把博客内容和风格文件放到这个文件夹中。在本篇教程里，我们取名为jupyter-blog, 你可以取为任何你喜欢的名字。
cd进入到jupyter-blog
创建一个叫做.gitignore的文件，并添加入这个文件的内容。最终我们将会把文件提交到git, .gitignore将会排除指定类型的文件。
创建并激活一个虚拟环境(译者注：此步非必须，如发生问题可以跳过。)

在jupyter-blog中创建一个叫做requirements.txt的文件并写入以下内容：

Markdown==2.6.6pelican==3.6.3jupyter>=1.0ipython>=4.0nbconvert>=4.0beautifulsoup4ghp-import==0.4.1matplotlib==1.5.1

在jupyter-blog下执行pip install -r requirements.txt安装requirements.txt中的所有包。

创建属于你自己的数据科学博客

完成预备工作后，进入jupyter-blog目录并执行pelican-quickstart将会开始一个交互式的博客安装过程。你将会看到有一系列的问题来使得博客安装妥当。

对于大多数问题，直接点击Enter接受默认值即可，需要自定义的地方有the title of the website（网站标题）, the author of the website（作者）,n for the URL prefix（URL前缀选择n）, and the timezone（时间区）。下面是一个示例（译者：以下内容以后都可在pelicanconf.py中再次修改）：

# xuliucheng @ xlcdemac in ~/pelican-blog [14:39:44] $ pelican-quickstartWelcome to pelican-quickstart v3.6.3.This script will help you create a new Pelican-based website.Please answer the following questions so this script can generate the filesneeded by Pelican.> Where do you want to create your new web site? [.] > What will be the title of this web site? LiuchengXu's Blog> Who will be the author of this web site? LiuchengXu> What will be the default language of this web site? [en] > Do you want to specify a URL prefix? e.g., http://example.com   (Y/n) n> Do you want to enable article pagination? (Y/n) > How many articles per page do you want? [10] > What is your time zone? [Europe/Paris] > Do you want to generate a Fabfile/Makefile to automate generation and publishing? (Y/n) > Do you want an auto-reload & simpleHTTP script to assist with theme and site development? (Y/n) > Do you want to upload your website using FTP? (y/N) > Do you want to upload your website using SSH? (y/N) > Do you want to upload your website using Dropbox? (y/N) > Do you want to upload your website using S3? (y/N) > Do you want to upload your website using Rackspace Cloud Files? (y/N) > Do you want to upload your website using GitHub Pages? (y/N) y> Is this your personal page (username.github.io)? (y/N) yDone. Your new project is available at /Users/xuliucheng/pelican-blog# xuliucheng @ xlcdemac in ~/pelican-blog [14:43:04] $ lsMakefile  content  develop_server.sh  fabfile.py  output  pelicanconf.py  publishconf.py  requirements.txt

运行完pelican-quickstart后，你会发现在jupyter-blog目录下多了两个文件夹：content 和 output，还有几个文件。比如pelicanconf.py和publishconf.py，下面是应当出现的几个文件：

jupyter-blog├── Makefile├── content├── develop_server.sh├── fabfile.py├── output├── pelicanconf.py├── publishconf.py└── requirements.txt2 directories, 6 files

安装Jupyter插件

Pelican默认情况下并不支持使用jupyter写博客 – 我们需要安装插件来进行支持。我们将把插件以git submodule的方式进行安装以便于管理。如果你还没有安装git, 可以在这里找到一些提示.

git安装好后：

执行git init将当前文件夹初始化为一个git仓库。
创建plugins文件夹。
执行git submodule add git://github.com/danielfrg/pelican-ipynb.git plugins/ipynb来添加插件。

# xuliucheng @ xlcdemac in ~/pelican-blog [14:45:19] $ git initInitialized empty Git repository in /Users/xuliucheng/pelican-blog/.git/# xuliucheng @ xlcdemac in ~/pelican-blog on git:master x [14:52:21] $ mkdir plugins# xuliucheng @ xlcdemac in ~/pelican-blog on git:master x [14:52:37] $ cd plugins # xuliucheng @ xlcdemac in ~/pelican-blog/plugins on git:master x [14:52:48] $ git submodule add git://github.com/danielfrg/pelican-ipynb.git plugins/ipynbCloning into '/Users/xuliucheng/pelican-blog/plugins/plugins/ipynb'...remote: Counting objects: 387, done.remote: Total 387 (delta 0), reused 0 (delta 0), pack-reused 387Receiving objects: 100% (387/387), 299.26 KiB | 93.00 KiB/s, done.Resolving deltas: 100% (190/190), done.

现在你应该有一个.gitmodules文件和一个plugins文件夹:

jupyter-blog├── Makefile├── content├── develop_server.sh├── fabfile.py├── output├── pelicanconf.py├── plugins├── publishconf.py└── requirements.txt3 directories, 6 files

为了启动插件，我们需要修改pelicanconf.py并将以下内容添加到尾部：

MARKUP = ('md', 'ipynb')PLUGIN_PATHS = [ './plugins' ]  # 如果像原文直接PLUGIN_PATH = `./plugins`而不使用列表会报warningPLUGINS = ['ipynb.markup']

这几行代码是告诉pelican在生成HTML时激活插件。

撰写你的第一篇博文

插件安装完毕后，我们可以来创建第一篇文章：

新建一个jupyter notebook并写入一些内容。这里是一个示例。
将notebook文件复制到content文件夹。
创建一个跟notebook同名的一个文件，不过扩展名为`.ipynb-meta’。这里是一个示例。

将下面的内容添加到ipynb-meta文件中，请注意修改部分条目以适应你自己的博客。

Title: First PostSlug: first-postDate: 2016-06-08 20:00Category: postsTags: python firstsAuthor: Vik ParuchuriSummary: My first post, read it to find out.

这里是对上面的一些解释：

Title: 博客文章的题目
Slug: 服务器上这篇文章的访问路径。如果slug是first-post, 你的服务器是jupyter-blog.com，那么你可以通过http://jupyter-blog.com/first-post来进行访问。
Date: 文章的发布时间
Category: 文章所属目录，可以为空。
Tags: 以逗号分割的标签列表，可以为空。
Author: 文章的作者，多个时使用逗号进行分割
Summary: 文章的一个简单概述。

生成HTML

为了生成博文的HTML，我们需要运行pelican将notebook转换成HTML，然后运行本地服务器就能够看到效果了：

切换到jupyter-blog文件夹
运行pelican content生成HTML
切换到output文件夹
运行python -m pelican.server
打开浏览器访问localhost:8000进行预览

你应该能够看到所生成的博客效果。

创建一个GitHub Pages

GitHub Pages是GitHub的一个特色，它能够快速部署一个静态网站并通过一个独一无二的URL访问。为完成安装，你需要：

如果还没有GitHub账号你需要先注册一个账号
创建一个GitHub仓库，名称为username.github.io, username是你的GitHub名称。这里可以查看更多细节。
切换到jupyter-blog目录
运行git remote add origin git@github.com:username/username.github.io.git来为你的本地GitHub仓库添加一个远程仓库。注意将username替换为你的GitHub用户名。

GitHub Page将会显示推送到仓库username.github.io的所有HTML文件，并可通过username.github.io进行访问。

首先，我们需要修改pelican以便于它能够指向正确的地址：

修改pelicanconf.py中的SITEURL, 将它设置为https://username.github.io， username是你的GitHub用户名。
运行pelican content -s publishconf.py。当你想要在本地进行预览时，运行pelican content. 在部署之前，运行pelican content -s publishconf.py，这会使用正确的部署设置文件。

提交你的文件

如果你想要GitHub pages这个仓库保存实际的notebook和一些其他文件，你可以使用git分支。

运行git checkout dev切换到一个叫做dev的分支。我们不能使用master分支来保存notebook, 因为这个分支为GitHub pages所用。
像往常一样提交并推送到GitHub（使用git add, git commit, git push）

部署到GitHub Pages

我们需要将博客内容推送到GitHub pages的master分支来使之正常工作。现在，HTML内容已经在output文件夹中，不过我们需要它是仓库的根目录，而不是一个子目录。

我们可以用ghp-import：

运行ghp-import output -b master将output中的所有内容导入到master分支。
运行git push origin master将内容推送到GitHub
尝试访问username.github.io – 你应该看到你的博客了！

任何时候当你的博客内容有所改变时，重新运行上面的 pelican content -s publishconf.py, ghp-import和git push命令，你的GitHub page就会得到更新。

接下来的工作

当博客内容逐渐增多并开始有访客时，你可能会在下面内容上进一步深入：

主题
pelican支持主题，你可在这里看到很多主题，并选择一个喜欢的使用。
定制URL
使用username.github.io的确是很好，不过有时候你可能会想要一个更加个性化的域名。这里是GitHub pages自定义域名访问的介绍。
插件
在这里查看插件列表。插件能够帮助添加统计访问，评论，等等很多功能。
博客推广
尽力在一些网站上推广你的博客来获取观众，比如CSDN, 简书，知乎等等。

—————————————————

译者：

上面的部署部分只讲了部署到username.github.io, 这里讲一下部署到username.github.io/project的注意事项（因为有坑）。

有网友来信询问部署到username.github.io/project的具体操作，其实很简单，以我的pelican blog为例：

在github上新建一个叫做pelican-blog的仓库。
其他本地搭建步骤照旧，不同之处在于推送到不同分支。
因为如果是username.github.io，github展示的是master分支的内容。如果是其他名称的仓库，比如这里的pelican-blog, github展示的是它gh-pages分支的内容。因此只是在推送output目录时有所不同。
在pelicanconf.py中设置SITEURL, 格式为 https://liuchengxu.github.io/pelican-blog.
```
SITEURL = 'https://liuchengxu.github.io/pelican-blog'
```
在pelican-blog目录下，将output目录下的内容推送到gh-pages分支：
```
ghp-import output -b gh-pagesgit push origin gh-pages
```

现在可以在liuchengxu.github.io/pelican-blog进行访问了，比如我的pelican-blog: https://liuchengxu.github.io/pelican-blog .

至于日常写作在master分支即可。我的博客采用bootstrap3主题，并修缮了一些不足之处，欢迎 >>> fork and star.

这里写图片描述

另外，关于其他注意事项：

在Jupyter Notebook中引用图片
总归免不了要引入一些图片，如果不注意设置肯定会发生路径找不到的问题：这需要在 pelicanconf.py 中配置 STATIC_PATHS 属性，Pelican 默认设置content下的images 为图片资源，其他的资源需要进行配置。

比如我的content

content├── images│   └── foo.png├── notebooks     └── test.ipynb

pelicanconf.py新增配置：

STATIC_PATHS = ['images', 'notebooks']NOTEBOOK_DIR = 'notebooks'

在test.ipynb中引用foo.png:

![foo]({filename}/images/foo.png)

是的，就是要添加”{filename}”, 不用替换成什么其他内容，而 / ，也就根目录，指的是content目录。

不过需要注意！！！上面的写法只是用在发布时，当你在写作时这样去链接图片肯定是找不到图片的（指的是notebook中无法找到图片，localhost:8000 还是能够访问到图片的），因此在本地预览时写的是:

![foo](../images/foo.png)

发布时再改成filename的写法。

生成页面时，Pelican 会将foo.png 复制到output/images/foo.png，同时将链接适配到生成的页面。

原文地址:Building a data science portfolio: Making a data science blog

1 0