fortran-lang.org 上的迷你书教程#

本指南将介绍如何为 https://fortran-lang.org 的 Learn 部分编写迷你书教程。

有关为 https://fortran-lang.org 做出贡献的一般指导，请参阅贡献指南。

0. Mini-book formats#

迷你书一般是对于 Fortran 语言特定功能的独立教程。

迷你书有两种格式类型：

单页： 所有内容都写在一个 markdown 文件中，并显示在单个网页上；
多页： 教程内容跨越多个 markdown 文件中，并显示为一组网页。

书的类型取决于内容的长度以及你打算如何组织它。

关于生成的目录：

单页面的书有 一层级 的导航：页内目录（页面右侧的目录）会显示教程中每个标题的链接。
多页面的书有 两层级 的导航：页内目录（页面右侧的目录）显示本页中每个标题的链接，侧边栏目录（页面左侧的目录）则显示文件夹下各个页面的名称。

单页面的迷你书容易制作，适合写简短的主题或教程，甚至可以并入到更详尽的多页书中。

而更详尽的教程，建议使用多页书，每页可包含一个小的主题。

本指南的剩余内容分为两小节，分别针对单页书和多页书。

1. Single-page mini-book#

发布单页迷你书所需的步骤是：

在 ./learn 路径下新建一个 markdown 文档
编写你的教程内容
在 data/learning.yml 中添加你的新迷你书的条目
发起新「拉取请求」

1.1 用 markdown 编写你的迷你书#

对于单页迷你书，你的教程将完全包含在单个 markdown 文档中。

首先在 ./learn/{{name_of_minibook}}/ 文件夹中创建一个新的 markdown 文档，起一个能概括教程主题的短名字，文件扩展名为 .md ，例如 ./learn/{{name_of_minibook}}/file_io.md。

打开新的markdown 文件并在 learn.md 的目录中附加一个条目，格式如下：

:::{toctree}
:hidden:

learn/quickstart/index
learn/best_practices/index
learn/os_setup/index
learn/building_programs/index
learn/intrinsics/index
learn/{{book-filename}}
:::

将 {{book-filename}} 替换为你的 markdown 文件的文件名，但不包括 .md 扩展名。也不应该有尾部斜线。

示例： 标头

:::{toctree}
:hidden:

learn/quickstart/index
learn/best_practices/index
learn/os_setup/index
learn/building_programs/index
learn/intrinsics/index
learn/file_io
:::

而不是： permalink: /learn/file_io.md

而不是： permalink: /learn/file_io/

现在你可以使用 markdown 格式编写教程的剩余内容了；在Kramdown 语法可以查看 markdown 的语法文档。

1.2 用标题划分迷你书的结构#

你应当使用标题划分单页迷你书的逻辑结构。每个标题都将显示在目录的超链接中。

标题在 markdown 中这样写：

# Heading level 1

## Heading level 2

### Heading level 3

#### Heading level 4

##### Heading level 5

###### Heading level 6

注意： 确保在标题前留一空行。

1.3 将你的迷你书添加到 Learn 页面#

你需要在 data/learning.yml 数据文件中添加一个新条目，以将新迷你书加入到 Learn 页面。

打开此文件并在 books: 字段下按以下格式创建一个新条目：

- title: {{book-title}}
  description: {{book-description}}
  category: {{book-category}}
  link: /learn/{{book-filename}}

title 字段是你的迷你书在 Learn 页面上显示的标题，通常应该与 markdown 文件中的 title 字段相同，但这不是必需的。

description 字段的内容也会显示在 Learn 页面上，能简要总结你的迷你书教程内容。

category 字段内容用于对 Learn 页面上的教程进行分组，应与数据文件头部列出的类别（在 categories: 字段下）之一相匹配。

link 字段应该与 markdown 文档中的 permalink 字段完全匹配。

示例： learning.yml 书籍条目

- title: File input and output
  description: A tutorial on reading and writing files in Fortran
  category: Getting started
  link: /learn/file/file_io

保存修改后的 learning.yml 数据文件并运行 fortran_package.py 并在本地计算机上重建网站以检查结果。如果成功，_Learn* 页面上应该会出现一个新链接，其中包含新迷你书的标题。

完成迷你书并向 learning.yml 数据文件添加条目后，请在 fortran-lang/webpage 处发起「拉取请求」（请参阅 CONTRIBUTING)。

2. Multi-page mini-books#

发布多页迷你书所需的步骤是：

在./learn/目录下新建文件夹
在新文件夹中创建一个 index.md 文件
在新文件夹中的 markdown 文件里编写教程内容
在 data/learning.yml 中添加你的新迷你书的条目
发起新「拉取请求」

2.1 为你的迷你书创建一个新文件夹#

在 ./learn/ 目录中创建一个新文件夹，其名称简明扼要地描述了你的教程主题，例如 ./learn/coarrays/。你的迷你书的所有页面都将包含在此文件夹中。

你的迷你书的第一页应该叫做index.md，所以在你的迷你书文件夹中创建一个名为index.md的新markdown文件，并在所有的markdown文件中添加一个如下格式的目录：

:::{toctree}
:hidden:

file1
file2
:::

不应有尾部斜线。

示例： toc for index.md

:::{toctree}
:hidden:

learn/quickstart/index
learn/best_practices/index
learn/os_setup/index
learn/building_programs/index
learn/intrinsics/index
:::

不是： 永久链接：/learn/coarrays/

你应该在 index.md 的其余部分中添加对你的迷你书教程的介绍，其中可能包括：所涵盖概念的摘要；任何先决条件；以及对其它相关迷你书或有用的第三方资源的任何引用。

2.2 为你的迷你书添加页面#

对于迷你书中的每个新页面，在迷你书文件夹中创建一个新的降价文件。

与单页迷你书一样，你应该使用标题将每一页分解成一个逻辑结构。当前页面上的每个标题都将显示在 inpage 目录中。

2.3 将你的迷你书添加到学习页面#