欢迎使用 fastpages

一款简单的博客网站，支持 Jupyter 笔记本, Word 文档, 以及 Markdown.

原作链接在此：fastai/fastpages，是英文的。

fastpages 用 GitHub Actions来简化多种格式文档（Jupyter 笔记本, Word 文档, 以及 Markdown）在GitHub Pages上转换为HTML格式的Jekyll博客帖的过程。

fastpages 提供以下功能:

• 建立博客帖。可以包含代码，运行结果，带格式文本等等。 使用Jupyter Notebooks可以轻松实现; 博客支持以下特性:
  • 使用Altair保持Jupyter的可交互性。
  • 显示或隐藏单元格。
  • 通过特殊的Markdown表格定义标题，概要，以及其他内容。
  • 提供链接到Colab 以及GitHub。
• 通过GitHub Issues来发表评论。
• 快速查找历史博客。
• 修改网站风格。
• 嵌入推特或油管视频。
• 通过标签分类。
• 建立Markdown格式的博客。
• 支持带格式和图片的word文档的博客页面。
• 本地写好并实时预览。

看下去了解更多细节。

看看模板网站

---

• 欢迎使用 fastpages
  • 初始化指导
  • 编写博客
    • 编写表头
    • 编写其他内容
• 查看英文原生文档
• 问答

初始化指导

1. 点击 这个链接 生成一个自己的仓库（repository，repo），用于运行博客。 随意给仓库起名字，但是 请勿使用 {your-username}.github.io.

2. GitHub Actions 会自动拉取请求（Pull Request，PR） ~ ，大约30s完成。 完成后会在你的仓库有一个README.md文档，根据那里的指导继续操作。

想要看视频指导，可以访问这个YouTube网址，但是国内看不了。 video tutorial of setting up a fastpages blog by Abdul Majed. 当然，根据文字指导也没有问题。

3. 你或许会收到一封指导邮件，但由于邮件是英文的，你可以忽视邮件，按以下指导操作。

• 3.1 生成SSH密钥对。访问这里，选择RSA和4096，点击生成（Generate-SSH-Keys），就会可到两串字符。

• 3.2 设置仓库（repo）的Secrets。在当前仓库地址后加/settings/secrets，或者访问settings>secrets，点击添加new secret。复制3.1中的Private Key至Value栏，包含"---BEGIN RSA PRIVATE KEY---" 和 "--END RSA PRIVATE KEY---"。在Name栏填写SSH_DEPLOY_KEY（只能是这个名字）。

• 3.3 设置仓库（repo）的deploy key。在当前仓库地址后加/settings/keys，或者访问settings>Deploy keys，点击添加deploy key。复制3.1中的Public Key至key栏，name栏随意填写。请注意勾选Allow write access。点击Add key保存设置。

• 3.4 启用网站。点击这里找到GitHub Pages，source选择gh-pages branch（如果没有可以先选择其他项，稍后自动生成gh-pages branch后可以再修改）。等待一段时间，GitHub Pages栏生成一个网址，点击即可访问该网站。

4. 修改_config.yml。需要修改的部分已经在文档内用中文标注。

5. 完成后等待约10分钟，网站自动建立成功。如果之前branch选择不是gh-pages，现在需要更改为gh-pages。

编写博客

编写表头

表头 允许你设置博客的很多属性。

在Jupyter中，表头是文档中的第一个单元格。并且是markdown格式的单元格。内容如下（可以缺省）：

# "标题"
> "概要"

- toc: true
- badges: true
- comments: true
- categories: [fastpages, jupyter]
- image: images/some_folder/your_image.png
- author: A & B

类似的, 在一个markdown文档中，也需要表头。内容如下：

---
title: "标题"
summary: "概要"
toc: true
comments: true
image: images/some_folder/your_image.png
categories: [fastpages, jupyter]
---

注意这里的代码是以YAML格式写的，必须保证正确。

更多YAML指导请看这里。

编写其他内容

正常编写即可。

需要说明的是Jupyter和Markdown插入图片的时候需要先上传图片，再引用到文档。例如我将图片传至根目录下的images文件夹，那么在Jupyter和Markdown中写以下代码即可引用。

![描述](images/filename.jpg "图片标题")

查看英文原生文档

更多内容查阅原生文档：fastai/fastpages。

FAQ

问答（英文）

• Q: Where are the markdown files in _posts/ that are generated from my Jupyter notebooks or word documents?

• A: The GitHub Actions workflow in this repo converts your notebook and word documents to markdown on the fly before building your site, but never commits these intermediate markdown files to this repo. This is in order to save you from the annoyance of your local environment being constantly out of sync with your repository. You can optionally see these intermediate markdown files by setting the BOOL_SAVE_MARKDOWN and SSH_DEPLOY_KEY inputs to the fastpages action in your .github/workflows/ci.yaml file as follows:

    ...

    - name: convert notebooks and word docs to posts
      uses: fastai/fastpages@master
      with:
        BOOL_SAVE_MARKDOWN: true
        SSH_DEPLOY_KEY: ${{ secrets.SSH_DEPLOY_KEY }}

    ...

• Q: Can I use fastpages for Jekyll docs sites or for things that are not Jekyll blog posts?

• A: At the moment, fastpages is a highly opinionated solution that works only for Jekyll blog posts. If you want to write documentation for your module or library with Jupyter notebooks, we suggest you use fastai/nbdev which is expressly built for this purpose.

• Q: What is the difference between fast_template and fastpages? Which one should I use?

• A: Because fastpages is more flexible and extensible, we recommend using it where possible. fast_template may be a better option for getting folks blogging who have no technical expertise at all, and will only be creating posts using Github's integrated online editor.