253 lines
7.1 KiB
Markdown
253 lines
7.1 KiB
Markdown
---
|
||
title: 撰写新文章
|
||
date: 2019-08-08 14:10:00 +0800
|
||
description: >-
|
||
文本、排版、数学公式、图表、流程图、图片、视频等示例。
|
||
categories:
|
||
- 博客
|
||
- 教程
|
||
tags:
|
||
- 写作
|
||
pin: True
|
||
---
|
||
> **NOTE:** 该教程还没有完成从 Jekyll 版本的迁移，请谨慎参考。
|
||
{ .prompt-warning }
|
||
|
||
本教程将指导您如何在 _Chirpy_ 模板中撰写文章，即使您以前使用过Jekyll，也值得阅读，因为许多功能需要设置特定变量。
|
||
|
||
## 命名和路径
|
||
|
||
创建一个名为 `YYYY-MM-DD-TITLE.EXTENSION`{: .filepath} 的新文件，并将其放在根目录的 `_posts`{: .filepath} 中。请注意，`EXTENSION`{: .filepath} 必须是 `md`{: .filepath} 和 `markdown`{: .filepath} 之一。如果您想节省创建文件的时间，请考虑使用插件 [`Jekyll-Compose`](https://github.com/jekyll/jekyll-compose) 来完成此操作。
|
||
|
||
## 前言
|
||
|
||
基本上，您需要在文章顶部填写[前言](https://jekyllrb.com/docs/front-matter/)，如下所示：
|
||
|
||
```yaml
|
||
---
|
||
title: 标题
|
||
date: YYYY-MM-DD HH:MM:SS +/-TTTT
|
||
categories: [主分类, 子分类]
|
||
tags: [标签] # 标签名称应始终为小写
|
||
---
|
||
```
|
||
|
||
> 文章的_布局_默认已设置为`post`，因此无需在前言块中添加变量_layout_。
|
||
{: .prompt-tip }
|
||
|
||
### 日期的时区
|
||
|
||
为了准确记录文章的发布日期，您不仅应该设置 `_config.yml`{: .filepath} 的 `timezone`，还应在其前言块的 `date` 变量中提供文章的时区。格式：`+/-TTTT`，例如 `+0800`。
|
||
|
||
### 分类和标签
|
||
|
||
每篇文章的 `categories` 设计为最多包含两个元素，而 `tags` 中的元素数量可以从零到无穷大。例如：
|
||
|
||
```yaml
|
||
---
|
||
categories: [动物, 昆虫]
|
||
tags: [蜜蜂]
|
||
---
|
||
```
|
||
|
||
### 作者信息
|
||
|
||
文章的作者信息通常不需要在 _前言_ 中填写，默认情况下，它们将从配置文件的 `social.name` 和 `social.links` 的第一个条目中获取。但您也可以按如下方式覆盖它：
|
||
|
||
在 `_data/authors.yml` 中添加作者信息（如果您的网站没有此文件，请创建一个）。
|
||
|
||
```yaml
|
||
<作者ID>:
|
||
name: <全名>
|
||
twitter: <作者的推特>
|
||
url: <作者的主页>
|
||
```
|
||
{: file="_data/authors.yml" }
|
||
|
||
然后使用 `author` 指定单个条目或 `authors` 指定多个条目：
|
||
|
||
```yaml
|
||
---
|
||
author: <作者ID> # 单个条目
|
||
# 或
|
||
authors: [<作者1ID>, <作者2ID>] # 多个条目
|
||
---
|
||
```
|
||
|
||
话虽如此，键 `author` 也可以识别多个条目。
|
||
|
||
> 从文件 `_data/authors.yml`{: .filepath } 读取作者信息的好处是页面将有元标签 `twitter:creator`，这丰富了 [Twitter Cards](https://developer.twitter.com/en/docs/twitter-for-websites/cards/guides/getting-started#card-and-content-attribution) 并有利于SEO。
|
||
{: .prompt-info }
|
||
|
||
### 文章描述
|
||
|
||
默认情况下，文章的第一句话用于在首页的文章列表、_进一步阅读_ 部分以及RSS源的XML中显示。如果您不想为文章显示自动生成的描述，可以使用 _前言_ 中的 `description` 字段自定义它，如下所示：
|
||
|
||
```yaml
|
||
---
|
||
description: 文章的简短摘要。
|
||
---
|
||
```
|
||
|
||
此外，`description` 文本也将显示在文章页面的文章标题下方。
|
||
|
||
## 目录
|
||
|
||
默认情况下，目录（TOC）显示在文章的右侧面板上。如果您想全局关闭它，请转到 `_config.yml`{: .filepath} 并将变量 `toc` 的值设置为 `false`。如果您想为特定文章关闭TOC，请将以下内容添加到文章的[前言](https://jekyllrb.com/docs/front-matter/)中：
|
||
|
||
```yaml
|
||
---
|
||
toc: false
|
||
---
|
||
```
|
||
|
||
## 评论
|
||
|
||
评论的全局设置由 `_config.yml`{: .filepath} 文件中的 `comments.provider` 选项定义。一旦为此变量选择了评论系统，所有文章将启用评论。
|
||
|
||
如果您想关闭特定文章的评论，请将以下内容添加到文章的**前言**中：
|
||
|
||
```yaml
|
||
---
|
||
comments: false
|
||
---
|
||
```
|
||
|
||
## 媒体
|
||
|
||
在 _Chirpy_ 中，我们将图片、音频和视频称为媒体资源。
|
||
|
||
### URL前缀
|
||
|
||
有时，我们必须为一篇文章中的多个资源定义重复的URL前缀，这是一项可以通过设置两个参数来避免的繁琐任务。
|
||
|
||
- 如果您使用CDN托管媒体文件，可以在 `_config.yml`{: .filepath } 中指定 `cdn`。然后，站点头像和文章的媒体资源的URL将以CDN域名为前缀。
|
||
|
||
```yaml
|
||
cdn: https://cdn.com
|
||
```
|
||
{: file='_config.yml' .nolineno }
|
||
|
||
- 要为当前文章/页面范围指定资源路径前缀，请在文章的 _前言_ 中设置 `media_subpath`：
|
||
|
||
```yaml
|
||
---
|
||
media_subpath: /path/to/media/
|
||
---
|
||
```
|
||
{: .nolineno }
|
||
|
||
选项 `site.cdn` 和 `page.media_subpath` 可以单独使用或组合使用，以灵活组合最终的资源URL：`[site.cdn/][page.media_subpath/]file.ext`
|
||
|
||
### 图片
|
||
|
||
#### 标题
|
||
|
||
在图片的下一行添加斜体，然后它将成为标题并显示在图片底部：
|
||
|
||
```markdown
|
||
|
||
_图片标题_
|
||
```
|
||
{: .nolineno}
|
||
|
||
#### 尺寸
|
||
|
||
为防止图片加载时页面内容布局发生偏移，我们应该为每张图片设置宽度和高度。
|
||
|
||
```markdown
|
||
{: width="700" height="400" }
|
||
```
|
||
{: .nolineno}
|
||
|
||
> 对于SVG，您至少必须指定其 _宽度_，否则它不会被渲染。
|
||
{: .prompt-info }
|
||
|
||
从 _Chirpy v5.0.0_ 开始，`height` 和 `width` 支持缩写（`height` → `h`，`width` → `w`）。以下示例与上述效果相同：
|
||
|
||
```markdown
|
||
{: w="700" h="400" }
|
||
```
|
||
{: .nolineno}
|
||
|
||
#### 位置
|
||
|
||
默认情况下，图片居中，但您可以使用 `normal`、`left` 和 `right` 类之一指定位置。
|
||
|
||
> 一旦指定了位置，就不应添加图片标题。
|
||
{: .prompt-warning }
|
||
|
||
- **普通位置**
|
||
|
||
在下面的示例中，图片将左对齐：
|
||
|
||
```markdown
|
||
{: .normal }
|
||
```
|
||
{: .nolineno}
|
||
|
||
- **向左浮动**
|
||
|
||
```markdown
|
||
{: .left }
|
||
```
|
||
{: .nolineno}
|
||
|
||
- **向右浮动**
|
||
|
||
```markdown
|
||
{: .right }
|
||
```
|
||
{: .nolineno}
|
||
|
||
#### 暗/亮模式
|
||
|
||
您可以使图片跟随暗/亮模式的主题偏好。这需要您准备两张图片，一张用于暗模式，一张用于亮模式，然后为它们分配特定的类（`dark` 或 `light`）：
|
||
|
||
```markdown
|
||
{: .light }
|
||
{: .dark }
|
||
```
|
||
|
||
#### 阴影
|
||
|
||
程序窗口的截图可以考虑显示阴影效果：
|
||
|
||
```markdown
|
||
{: .shadow }
|
||
```
|
||
{: .nolineno}
|
||
|
||
#### 预览图片
|
||
|
||
如果您想在文章顶部添加图片，请提供分辨率为 `1200 x 630` 的图片。请注意，如果图片的宽高比不符合 `1.91 : 1`，图片将被缩放和裁剪。
|
||
|
||
了解这些先决条件后，您可以开始设置图片的属性：
|
||
|
||
```yaml
|
||
---
|
||
image:
|
||
path: /path/to/image
|
||
alt: 图片替代文本
|
||
---
|
||
```
|
||
|
||
请注意，[`media_subpath`](#url前缀) 也可以传递给预览图片，也就是说，当它已经设置好时，属性 `path` 只需要图片文件名。
|
||
|
||
为了简单使用，您也可以只使用 `image` 来定义路径。
|
||
|
||
```yml
|
||
---
|
||
image: /path/to/image
|
||
---
|
||
```
|
||
|
||
#### LQIP
|
||
|
||
对于预览图片：
|
||
|
||
```yaml
|
||
---
|
||
image:
|
||
lqip: /path/to/lqip-file # 或base64 URI
|
||
``` |