《载歌在谷》志愿者社区官方网站

为《载歌在谷》志愿者社区，本代码库托管其官方网站的源代码。

贡献指南

想要开发这个网站，需要用到以下工具：

在本地渲染该网站

本网站使用 Jekyll 渲染。安装 Jekyll 之后，您可以运行以下命令来在您的电脑上（“本地”）打开这个网站：

bundle exec jekyll serve

Pre-commit hooks

本代码库使用 pre-commit hooks 来自动化一些琐事。（请参见 .pre-commit-config.yaml 来熟悉一下都启用了哪些 hooks。）

Assuming you have pre-commit installed (perhaps via brew install pre-commit), after cloning this repo to your local machine, you need to execute this command in the root directory of this repo:

pre-commit install

One of the hooks use the ESLint tool to check JavaScript files, including enforcing the Google JavaScript Code Style. (See .eslintrc.json for the exact config.) As a npm package, ESLint is installed via npm and specified in the package.json.

本代码库结构简介

根据您想要贡献的内容的类型划分，您可能想要专注于认识不同的部分。

如果你想要加入、更新内容

对于内容贡献者来说，最重要的几个文件夹是：

pages：这里存放了每个页面的内容。每个页面都是一个单独的 Markdown 文本文档。在每个文件开头，有个符合 YAML 语法的区块，叫“front matter“，是会被 Jekyll 特殊处理的“元数据”（metadata）。元数据包括（显示在浏览器标签页卡片上的）标题、布局（layout）名称等。对于布局，大部分的页面都可以使用 layout: page（例如《关于我们》、《常见问题》）。
_data：这里存放了任何需要被 enumerate （“枚举”/“罗列”/“用循环读出”）出来的信息。每个文件都是一个 YAML 文件。例如：
- data.yml：定义了网站顶栏、底栏应该有哪些链接；我们有哪些伙伴社区、赞助商；春晚板块有哪些节目；歌手赛有哪些节目；云集板块有哪些栏目…… 这是最主要的、最杂的数据文件。 当某个列表太大时，您也可以选择把它单独拆出来、成为一个单独的文件，就像下面两项这样👇
- past-events.yml：定义了《往届回顾》页面的内容。
- trailer-images.yml：罗列了一些春晚宣传片的拍摄花絮照片。

⚠️ 注意：本代码库虽然包含一个 images 文件夹，但它仅应该被用来存放 svg 等源代码格式的图片。若需要存放 jpg、png 等二进制格式的图片，请使用我们自己的 Cloudinary 服务。

如果你想要开发网站功能

_layouts：当朴素的 layout: page 难以满足您的表达需求时，您可以创建新的 layout，存放于这里。请参见下文“如何自由排版”一节。
_includes：存放可复用的一些元件。复用可以发生在：
- 几页之间。例如：赞助商列表（_includes/sponsor-section.html）被复用于歌手赛、游园、春晚等页面底部。
- 一页之内。例如：栏目卡片（_includes/programme.html）被复用于首页。
- 其他可复用的元件之内。例如，上述栏目卡片也在云集节目列表（_includes/programmes.html）里被复用：
assets：存放了一些脚本和样式表文件。
- assets/css/style.scss：许多仅对《载歌在谷》有意义的样式（与“对其他网站也有用”相对），都被存放到了这里。如春晚横幅：https://github.com/zgzgorg/yj.zgzg.io/blob/d11235a52359996f299a1bdab37669251c10d21c/assets/css/style.scss#L357-L364
- assets/js/sidenotes.js： is a pure-JavaScript plugin that puts .footnotes into #sidebar, aligning each piece of note at their corresponding superscript, developed by @tslmy.
_sass：这里存放各种对其他网站也有复用意义的样式表。其实，本网站采用的即是他人制作的、现成的主题——由 Robert Austin 制作的 Serif。

本网站托管于 Netlify 之上，域名为 zgzg.io。请参见 zgzg.link/site-notes 更多信息，包括《载歌在谷》的所有网络服务资源、各代网站特点及制作背景等。（仅限内部访问。）

如何自由地排版

当朴素的 layout: page 难以满足您的表达需求时，您可以创建新的 layout。

假设我们想做一个《春晚》页面。通常，我们只需要创建一个 pages/gala.md 来提供内容。但是，假设这次我们想要做一些复杂的结构，如图所示：

我们首先要做的是，在 pages/gala.md 的 front matter 上写明“请用一个叫 gala 的 layout 来渲染这个文档，而不是默认的叫 page 的那个 layout”：

https://github.com/zgzgorg/yj.zgzg.io/blob/d11235a52359996f299a1bdab37669251c10d21c/pages/gala.md?plain=1#L3

接下来，我们创建一个 _layouts/gala.html 文件。虽然这是一个 HTML 文档，但是我们依然可以写入 front matter。在它的 front matter 里，我们写“请把这个 layout 嵌套在叫 default 的那个 layout 里”：

https://github.com/zgzgorg/yj.zgzg.io/blob/d11235a52359996f299a1bdab37669251c10d21c/_layouts/gala.html#L1-L3

接下来的工作，就是常见的“写 HTML”了。其实，我们写的不会是纯粹的 HTML，而是一种叫 Liquid 的“模板语言”（templating language）。模板语言提供一些高阶功能，比如引用一些模块。例如，在现今的 _layouts/gala.html 底部，我们就有引用两个模块：

https://github.com/zgzgorg/yj.zgzg.io/blob/d11235a52359996f299a1bdab37669251c10d21c/_layouts/gala.html#L32-L33

这些模块存放于 _includes/ 文件夹下。例如，上面引用的第一个模块，就在 _includes/galalist.html：

https://github.com/zgzgorg/yj.zgzg.io/blob/d11235a52359996f299a1bdab37669251c10d21c/_includes/galalist.html#L1-L14

这个模块很好地体现了 Jekyll 里的“枚举”该怎么用。注意这一行：

https://github.com/zgzgorg/yj.zgzg.io/blob/d11235a52359996f299a1bdab37669251c10d21c/_includes/galalist.html#L7

它说：“请在本网站（site）的 data 文件夹下，找到叫 data 的 YAML 文件，读取其中的 galalist 列表。对于其中每个项目（以 pic 指代），重复渲染下述内容“。这里所指的”下述内容“，即是：

https://github.com/zgzgorg/yj.zgzg.io/blob/d11235a52359996f299a1bdab37669251c10d21c/_includes/galalist.html#L8-L12

它说：

放置一个 galalist-section 类型的分区（division，div）。在里面放：

一个图片（img），图片链接为 pic.image；

在那之后放一个三级标题（h3），内容为 pic.title；

最后，把 pic.description 直接放上去。