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

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

有关为 https://fortran-lang.cn 贡献代码的一般指南，请参阅贡献指南。

0. 迷你书格式#

迷你书旨在成为关于 Fortran 语言特定功能的大部分自包含教程。

迷你书格式有两种类型

单页：所有内容都写在单个 Markdown 文件中，并在单个网页上显示；
多页：教程内容分散在多个 Markdown 文件中，并显示为网页集合。

书籍类型的选择取决于您内容的长度以及您打算如何对其进行结构化。

考虑将生成的目录

单页书籍具有一级导航：教程中每个标题的链接都在 inpage-toc 中（页面右侧的目录）。
多页书籍具有两级导航：教程中每个标题的链接都在 inpage-toc 中（页面右侧的目录）和 sidebar-toc 中（页面左侧显示目录中不同页面的目录）。

单页迷你书制作起来比较简单，应该用于简短的主题或最终将并入更全面的多页书籍的简短教程。

对于可以按每个页面一个子主题进行结构化的更全面的教程，建议使用多页书籍。

本指南的其余部分分为两个部分，分别针对单页和多页书籍类型。

1. 单页迷你书#

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

在 ./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 填写文件的其余部分；有关 Markdown 实现的文档，请参阅 Kramdown 语法。

1.2 使用标题构建迷你书#

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

在 Markdown 中，标题可以写成

# Heading level 1

## Heading level 2

### Heading level 3

#### Heading level 4

##### Heading level 5

###### Heading level 6

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

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

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

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

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

title 字段将在“Learn”页面上显示您的迷你书的标题，通常应与 Markdown 文件中的 title 字段相同，但这并非必需。

description 字段的内容也会显示在“Learn”页面上，并且应该简要总结迷你书教程的内容。

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

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 数据文件中添加条目后，请在 https://github.com/fortran-lang/webpage 上打开一个拉取请求（请参阅贡献）。

2. 多页迷你书#

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

在 ./learn/ 目录中创建一个新文件夹
在您的新文件夹中创建一个 index.md 文件
在您的新文件夹中使用 Markdown 文件编写您的教程内容
为您的新迷你书在 data/learning.yml 中添加一个条目
打开一个拉取请求

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

在 ./learn/ 目录中创建一个新文件夹，并使用一个简短的名称来简洁地描述教程的主题，例如 ./learn/coarrays/。迷你书的所有页面都将包含在此文件夹中。

迷你书的第一页应命名为 index.md，因此在您的迷你书文件夹中创建一个名为 index.md 的新 Markdown 文件，并在所有 Markdown 文件中添加以下格式的目录

:::{toctree}
:hidden:

file1
file2
:::

不应该有尾部斜杠。

示例： index.md 的目录

:::{toctree}
:hidden:

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

非： permalink: /learn/coarrays/

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

2.2 向您的迷你书添加页面#

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

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

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

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

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

- title: {{book-title}}
  description: {{book-description}}
  category: {{book-category}}
  link: /learn/{{book-folder}}
  pages:
    - link: /learn/{{book-folder}}/{{page1-filename}}
    - link: /learn/{{book-folder}}/{{page2-filename}}
    - link: /learn/{{book-folder}}/{{page3-filename}}

title 字段将在“Learn”页面上显示您的迷你书的标题，通常应与 index.md Markdown 文件中的 title 字段相同，但这并非必需。

description 字段的内容也会显示在“Learn”页面上，并且应该简要总结迷你书教程的内容。

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

顶级 link 字段应与 index.md 文件中的 permalink 字段完全匹配。

pages 下的每个 link 字段应与后续每个迷你书页面中的 permalink 字段完全匹配。