快速页面
vements to styling
有关我们为何弃用此项目的更多信息，请参见此处。
fastpages一个易于使用的博客平台，支持 Jupyter 笔记本、Word 文档和 Markdown。
fastpages使用 GitHub Actions 简化从各种输入格式在 GitHub Pages 上创建 Jekyll 博客文章的过程。
fastpages提供以下功能：请参阅下文了解更详细的功能列表。
查看演示站点
fastpagesfastpages提供以下功能：单击此链接生成此存储库的副本。请务必登录您的帐户，否则您将看到 404 错误。将您的存储库命名为您喜欢的任何名称，除了{your-username}.github.io。
创建副本后约 30 秒，GitHub Actions 将自动在您的新存储库上打开 PR 。请按照该 PR 中的说明继续。
如果您没有看到 PR，请确保您的组织中启用了第三方操作：设置 -> 操作 -> 操作权限 -> 为此存储库启用本地和第三方操作
有关设置步骤的实时演练（以及一些附加提示），请参阅 Abdul Majed 撰写的设置快速页面博客的视频教程。
Read and Write权限，并选中Allow GitHub Actions to create and approve pull requests 。 
授予权限后，请转到存储库主页顶部的Actions选项卡，您将在其中看到操作运行的列表。首先点击失败的运行（带有红色X的项目）：
您将进入一个屏幕，右上角有一个按钮，允许您重新运行作业。
执行此操作后，应该会出现拉取请求。
_posts 、 _notebooks或_word目录中添加内容。您可以按照此存储库中这些文件夹中的内容示例来了解如何构建内容。最需要注意的是前面的事情，下面会更详细地讨论。此外，您可以添加其他页面，这些页面将显示在博客导航栏的_pages目录中。请注意， _word目录中的内容不支持 Front Matter。 Front Matter 允许您打开/关闭每个博客文章的各种选项，以及将元数据传递给快速页面的各种功能。
在笔记本中，前文被定义为笔记本开头的 Markdown 单元，包含以下内容：
# "Title"
> "Awesome summary"
- toc: false
- branch: master
- badges: true
- comments: true
- categories: [ fastpages, jupyter ]
- image: images/some_folder/your_image.png
- hide: false
- search_exclude: true
- metadata_key1: metadata_value1
- metadata_key2: metadata_value2类似地，在 Markdown 文档中，相同的前事项将在文档的开头定义如下：
---
title : " My Title "
description : " Awesome description "
layout : post
toc : false
comments : true
image : images/some_folder/your_image.png
hide : false
search_exclude : true
categories : [fastpages, jupyter]
metadata_key1 : metadata_value1
metadata_key2 : metadata_value2
---其他元数据是可选的，并允许您设置自定义标题。
请注意，前面定义的任何内容都必须是有效的 YAML。未能提供有效的 YAML 可能会导致您的页面无法在博客中呈现。例如，如果您想在标题中使用冒号，则必须使用双引号将其转义，如下所示：
- title: "Deep learning: A tutorial"
有关更多信息，请参阅有关 YAML 的教程。
Title替换为您想要的标题，并将Awesome summary替换为您想要的摘要。注意：建议将这些值括在双引号中，以便可以转义冒号和其他可能破坏 YAML 解析器的字符。
fast_template会根据 markdown headers 自动为你生成一个目录！您可以通过将toc:设置为true或false来打开或关闭此功能。此选项仅适用于笔记本电脑
branch字段用于选择性地在博客文章中呈现笔记本到 Colab 和 GitHub 的链接。如果您没有在笔记本中指定它，它将默认为master 。badges设置为false 。默认为truebadges: true时，默认情况下将显示所有四个徽章（GitHub、Binder、Deepnote、Colab） 。您可以使用站点范围配置选项中的default_badges参数调整这些默认值。如果只想隐藏单个帖子上的徽章，可以设置 front Matter hide_{github,colab,binder,deepnote}_badge: true 。例如，如果您想隐藏单个笔记本的 Binder 徽章，但希望显示其他徽章，则可以在 Front Matter 中进行设置：
- badges : true
- hide_binder_badge : truerequirements.txt文件，其中包含您用于所有笔记本的通用包，您可以在官方 Binder 文档中了解更多信息。您可以在博客文章的类别的方括号内包含一个以逗号分隔的列表，这将使该文章在您博客网站的标签页面上可见。例如：
在笔记本中：
# "My Title"
- categories: [fastpages, jupyter]
在 Markdown 文档中：
---
title: "My Title"
categories: [fastpages, jupyter]
---
您可以在此处查看其外观的预览。
_config.yml中将show_tags设置为true或false来打开/关闭标签的显示： # Set this to true to display tags on each post
show_tags : true对博客文章的评论由 Utterances 提供支持，这是一种开源且无广告的评论实施方式。所有评论都存储在您博客的 GitHub 存储库上的问题中。您可以在将comments设置为true时将其打开。默认为false 。
要启用话语评论，您需要执行以下操作：
在 Twitter 等社交媒体网站上，可以自动显示图像预览和您的 URL。指定首页image会将此元数据提供给社交媒体网站，以便为您呈现此图像。您可以按如下方式设置该值：
- image: images/diagram.png
注意：对于此设置，您只能引用存储库的/images文件夹中的图像文件和文件夹。
您可能希望阻止博客文章列在主页上，但仍然有一个可以预览或谨慎共享的公共 URL。您可以通过将 Front Matter hide设置为true来隐藏主页中的博客文章。默认设置为false 。
建议您使用永久链接来为隐藏的博客文章生成可预测的 URL。如果您不希望用户在搜索中找到您的隐藏帖子，您还可以将 Front Matter search_exclude设置为true 。
默认情况下，主页上的帖子按日期排序。但是，您可能希望一篇或多篇博客文章始终显示在主页的最顶部。换句话说，您可能希望某些帖子被“固定”或“粘性”。要实现此目的，请按照您希望置顶帖子出现的顺序指定sticky_rank标题。未设置此参数的博文默认按日期排序在置顶帖之后。
例如，考虑这三个 Markdown 帖子（也适用于笔记本）。
2020-01-01-Post-One.md
---
title : Post One
sticky_rank : 1
--- 2020-02-01-Post-Two.md
---
title : Post Two
sticky_rank : 2
--- 2020-04-01-Post-Three.md
---
title : Post Three
---但是，由于指定了sticky_rank ，博客文章将首先按sticky_rank升序排序，然后按日期降序排序，因此这些帖子的顺序将如下所示：
如果没有sticky_rank由于与每个帖子关联的日期，上述帖子实际上会按相反的顺序排序。
注意：固定也适用于笔记本：
# "My cool blog post"
> "Description of blog post"
- sticky_rank: 2
fastpages 带有由 lunr.js 提供支持的内置关键字搜索。您可以通过将标题search_exclude设置为false来阻止博客文章或页面出现在搜索结果中。默认情况下此设置为true 。
建议每个人通过设置站点范围的配置选项来个性化他们的博客站点。这些选项可以在/_config.yml中找到。以下是各种可用选项的描述。
title ：这是出现在所有页面标题左上角的标题。
description ：生成网站预览时（例如，在社交媒体上），此描述将显示在各个位置。
github_username ：这允许您的网站在页脚中显示指向 GitHub 页面的链接。
github_repo ：这允许您的网站呈现返回到存储库的各种功能的链接，例如笔记本的 GitHub、Colab 和 Deepnote 的链接。
url ：除非您有自定义域，否则不需要更改。注意：忽略该值中的尾随 /。
baseurl ：请参阅/_config.yml中的注释以获取有关正确设置此值的说明（“baseurl 的特殊说明”）。如果您没有自定义域，那么您可能会忽略此选项。
email ：目前未使用。忽略。
twitter_username ：在页脚中创建指向 Twitter 页面的链接。
use_math ：将其设置为true以获得 LaTeX 数学方程支持。默认情况下此选项处于关闭状态，否则会将 javascript 加载到可能不使用的每个页面中。
show_description ：这会在主页上的博客文章标题下显示说明，其中包含您的博客文章列表。默认设置为true 。
google_analytics ：如果需要，可以选择使用 Google Analytics ID 进行跟踪。
show_image ：如果设置为 true，则使用博客文章前面的image参数来呈现博客的预览，如下所示。默认设置为false 。当 show_image 设置为true时，您的主页将如下所示：
show_tags ：您可以通过将此值设置为false来打开或关闭博客文章上标签的显示。默认情况下，此设置为true ，这会在您的博客文章上呈现以下标签链接，如下所示：
pagination ：这是主页每页上显示的最大帖子数。任何超过此数量的帖子都将分页到另一个页面。默认设置为15 。触发此操作后，您将看到主页底部的分页显示如下：
注意：如果您使用旧版本的 fastpages，则无法使用自动升级过程来获取分页。相反，您必须遵循以下步骤：
mvindex.mdindex.html
Gemfile和Gemfile.lock替换为此存储库中的文件。_config.yml （查看 _config.yml 示例）： gems :
- jekyll-paginate
paginate : 10
paginate_path : /page:num/或者，您可以将所有帖子复制到从 fastpages 模板创建的新创建的存储库中。
default_badges ：默认情况下，GitHub、Binder、Deepnote 和 Colab 徽章将显示在笔记本博客文章上。您可以通过将default_badges中的适当值设置为 false 来调整这些默认值。例如，如果您想默认关闭 Binder 徽章，则可以将default_badges更改为：
default_badges :
github : true
binder : false
deepnote : false
colab : true html_escape ：这允许您在博客文章的各个组件中打开或关闭 HTML 转义。目前，您只能为帖子中的description字段切换此选项。
默认设置为false 。
您可以通过编辑 /_sass/minima/custom-variables.scss 来调整各种设备上 fastpages 的页面宽度。
这些是默认值，可以根据您的喜好进行调整：
// width of the content area
// can be set as "px" or "%"
$content-width : 1000 px ;
$on-palm : 800 px ;
$on-laptop : 1000 px ;
$on-medium : 1000 px ;
$on-large : 1200 px ;Hypothes.is 是一个开放平台，提供了一种注释和突出显示页面的方法，页面可以是公共的，也可以是私有的。启用此功能后，您博客的读者在突出显示文本时将看到以下工具提示：
默认情况下，快速页面中禁用此功能。您可以通过将annotations设置为true或false在 _config.yml 文件中启用或禁用此功能：
# Set this to true to turn on annotations with hypothes.is
annotations : false您可以通过阅读这些配置选项来自定义 Hypothes.is。如果您想使用假设做更多事情，阅读这些文档也是一个好主意。但是，在尝试自定义此功能之前，您应该阅读自定义快速页面部分以了解重要的注意事项。
您可以引导读者订阅 RSS 源。互联网上有许多可用的 RSS 订阅服务。一些例子包括：
fastpages覆盖了 Dracula 主题的最小值的默认语法突出显示。
fastpages 中的默认突出显示如下所示：
但是，如果您选择，则可以使语法突出显示如下所示：
如果您想恢复到上面的浅色主题，您可以删除 _sass/minima/custom-styles.scss 中的以下行
@import " minima/fastpages-dracula-highlight " ;如果您不喜欢这些主题，您可以在_sass/minima/custom-styles.scss中添加您自己的 CSS。有关更多详细信息，请参阅自定义快速页面。
这篇博文介绍了如何为快速页面启用深色模式。
喜欢使用引文系统 BibTeX 的用户可以这样做；它需要启用 jekyll-scholar 插件。请参阅 BibTeX 和 jekyll-scholar 中的 Fastpages 引文，了解实现此功能的说明。
将注释#hide放在代码单元格的开头，它将隐藏该单元格的输入和输出。
任何单元格顶部的#hide_input注释只会隐藏输入。
此外， hide input Jupyter 扩展可用于隐藏单元格输入或输出，这将受到快速页面的尊重。
您可能希望将某些代码隐藏在用户可以展开的折叠元素中，而不是完全向读者隐藏代码。
#collapse放在代码单元格的顶部。#collapse_show或#collapse-show放在代码单元格的顶部。#collapse_output或#collapse-output放在代码单元格的顶部。在笔记本的 Markdown 单元中，使用以下 Markdown 快捷方式嵌入 Twitter 卡和 YouTube 视频。
> youtube: https://youtu.be/your-link
> twitter: https://twitter.com/some-link在笔记本中添加脚注与 Markdown 略有不同。请参阅笔记本脚注详细指南。
使用命名约定YYYY-MM-DD-*.分别进入此存储库的/_notebooks或/_word文件夹。例如2020-01-28-My-First-Post.ipynb 。 Jekyll 需要此命名约定来呈现您的博客文章。
请注意正确命名您的文件！人们很容易忘记YYYY-MM-DD-中的最后一个破折号。此外，紧跟在破折号后面的字符只能是字母。有效文件名的示例有：
2020-01-28-My-First-Post.ipynb
2012-09-12-how-to-write-a-blog.ipynb如果您未能正确命名文件， fastpages将自动尝试通过将文件的上次修改日期添加到生成的博客文章中来解决问题，但是，建议您自己正确命名文件以提高透明度。
提交文件并将其推送到存储库主分支中的 GitHub。
GitHub 会自动将您的文件转换为博客文章。转换过程大约需要 5 分钟。您可以单击存储库的“操作”选项卡来查看此过程的日志。每次推送到主分支时都会触发两个工作流程：(1)“CI”和(2)“GH 页面状态”。在更新您的网站之前，这两个工作流程都必须完成，并为您的最新提交打上绿色复选标记。
如果您愿意，您可以在提交到 GitHub 之前预览您的博客在本地的外观。有关在本地运行预览的详细指南，请参阅本节。
如果您在 Markdown 中编写博客文章，请将.md文件保存到/_posts文件夹中，并使用为笔记本指定的相同命名约定 ( YYYY-MM-DD-*.md )。
使用为笔记本指定的相同命名约定 ( YYYY-MM-DD-*.docx ) 将 Microsoft Word 文档保存到/_word文件夹中。
注意： fastpage 尚不支持 Word 文档中的替代文本，并且会破坏图像链接。
fastpages没有可靠的方法来指定 Word 文档的标题。目前，您只能通过编辑 _action_files/word_front_matter.txt 来全局指定所有 Word 文档的前题。
要指定每个 Word 文档的唯一标题，您需要手动将 Word 转换为 Markdown 文件。您可以按照此博客文章中的步骤操作，该文章将引导您了解如何使用 pandoc 进行转换。注意：如果您希望在 Markdown 中自定义 Word 生成的博客文章，请确保从 _word 目录中删除 Word 文档，以免您的 Markdown 文件被覆盖！
如果您撰写博客文章的主要方法是 Word 文档，并且您计划始终手动编辑从 Word 转换的 Markdown 文件，那么您最好使用 fast_template 而不是 fastpages。
请参阅开发指南。
fastpages操作允许您将存储库中/_notebooks中的笔记本和/_word目录中的 Word 文档转换为位于/_posts中的符合 Jekyll 的博客文章 Markdown 文件。注意：此目录结构目前对此操作不灵活，因为它设计为与 Jekyll 一起使用。
如果您已经对 Jekyll 有足够的熟悉并希望在自己的主题中使用此自动化功能，则可以通过引用fastai/fastpages@master来使用此 GitHub Action，如下所示：
...
uses : fastai/fastpages@master
...完整工作流程的示例如下：
jobs :
build-site :
runs-on : ubuntu-latest
...
- name : convert notebooks and word docs to posts
uses : fastai/fastpages@master
...
- name : Jekyll build
uses : docker://jekyll/jekyll
with :
args : jekyll build
- name : Deploy
uses : peaceiris/actions-gh-pages@v3
if : github.event_name == 'push'
with :
deploy_key : ${{ secrets.SSH_DEPLOY_KEY }}
publish_branch : gh-pages
publish_dir : ./_site请注意，此操作没有任何必需的输入，也没有输出变量。
BOOL_SAVE_MARKDOWN ：“真”或“假”。是否将笔记本和 Word 文档中转换后的 Markdown 文件提交到存储库中的 _posts 目录中。这对于调试很有用。默认值：假SSH_DEPLOY_KEY ：如果 BOOL_SAVE_MARKDOWN = 'true' 则需要 ssh 部署密钥请参阅 action.yml 中此操作的 API 规范
有关如何自定义此博客的详细说明超出了本自述文件的范围。 （我们邀请社区中的某人贡献一篇博客文章，介绍如何在此存储库中执行此操作！）
请参阅贡献指南。
请参阅升级指南。
_posts/中从我的 Jupyter 笔记本或 Word 文档生成的 Markdown 文件在哪里？答：此存储库中的 GitHub Actions 工作流程会在构建站点之前将您的笔记本和 Word 文档动态转换为 Markdown，但绝不会将这些中间 Markdown 文件提交到此存储库。这是为了使您免受本地环境不断与存储库不同步的烦恼。您可以选择通过将BOOL_SAVE_MARKDOWN和SSH_DEPLOY_KEY输入设置为.github/workflows/ci.yaml文件中的 fastpages 操作来查看这些中间 Markdown 文件，如下所示： ...
- name : convert notebooks and word docs to posts
uses : fastai/fastpages@master
with :
BOOL_SAVE_MARKDOWN : true
SSH_DEPLOY_KEY : ${{ secrets.SSH_DEPLOY_KEY }}
...问：我可以对 Jekyll 文档网站或非 Jekyll 博客文章的内容使用fastpages吗？答：目前， fastpages是一个非常固执己见的解决方案，仅适用于 Jekyll 博客文章。如果您想使用 Jupyter Notebook 为您的模块或库编写文档，我们建议您使用专门为此目的构建的 fastai/nbdev。
问： fast_template 和 fastpages 有什么区别？我应该使用哪一个？答：因为fastpages更加灵活和可扩展，所以我们建议尽可能使用它。 fast_template可能是让那些完全没有技术专业知识并且只会使用 Github 的集成在线编辑器创建帖子的人写博客的更好选择。
fastpages 建立在 minima 主题之上。如果您想自定义快速页面的样式或布局，可以在 minima 的 README 中找到说明。最好阅读 README 的完整内容以了解目录结构。此外，在定制主题之前对 Jekyll 有基本的了解是个好主意。对于 Jekyll 的新手来说，官方文档是一个很好的起点。具体来说，您可以在_sass/minima/custom-styles.scss中覆盖 fastpages 中的 css 。请注意，minima 的“皮肤”功能当前与 fastpages 的 css 设置不兼容。
如果您选择对 fastpages 进行自定义，您所做的自定义可能会与当前或未来版本的 fastpages 发生冲突，我们建议您仅在您对 HTML 和 CSS 感到足够熟悉时才这样做。
请参阅故障排除指南。
