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

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

贡献指南

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

在本地渲染该网站

本网站使用 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：许多仅对《载歌在谷》有意义的样式（与“对其他网站也有用”相对），都被存放到了这里。如春晚横幅：

    yj.zgzg.io/assets/css/style.scss

    Lines 357 to 364 in d11235a

    	#gala-banner .container {
    	background-image:url(https://res.cloudinary.com/zaigezaigu/image/upload/v1637381379/zgzg-io-website/front-page-1280x712_ueloj5.png);
    	background-position:-150px;
    	background-repeat:no-repeat;
    	margin: 0 auto 0 auto;
    	min-height:550px;
    	padding-top:50px;
    	}

  • 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”：

yj.zgzg.io/pages/gala.md

Line 3 in d11235a

layout: gala

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

yj.zgzg.io/_layouts/gala.html

Lines 1 to 3 in d11235a

	---
	layout: default
	---

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

yj.zgzg.io/_layouts/gala.html

Lines 32 to 33 in d11235a

	{% include galalist.html %}
	{% include sponsor-section.html %}

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

yj.zgzg.io/_includes/galalist.html

Lines 1 to 14 in d11235a

	<div id="galalist-space">
	<div class="container">
	<div class="row">
	<img src="https://res.cloudinary.com/zaigezaigu/image/upload/c_scale,w_500/v1641779415/zgzg-io-website/2022%E6%98%A5%E6%99%9A%E6%8B%8D%E6%91%84%E8%8A%B1%E7%B5%AE/gala-1_dppg8y.png" id="galalist-pic-beginning">
	</div>
	<div class="row">
	{% for pic in site.data.data.galalist %}
	<div class="col-12 col-lg-12 col-md-4 galalist-section">
	<img class="galalist-pic" src="{{ pic.image }}">
	<h3> {{ pic.title }} </h3>
	{{ pic.description }}
	</div>
	{% endfor %}
	</div>

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

yj.zgzg.io/_includes/galalist.html

Line 7 in d11235a

{% for pic in site.data.data.galalist %}

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

yj.zgzg.io/_includes/galalist.html

Lines 8 to 12 in d11235a

	<div class="col-12 col-lg-12 col-md-4 galalist-section">
	<img class="galalist-pic" src="{{ pic.image }}">
	<h3> {{ pic.title }} </h3>
	{{ pic.description }}
	</div>

它说：

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

• 一个图片（img），图片链接为 pic.image；
• 在那之后放一个三级标题（h3），内容为 pic.title；
• 最后，把 pic.description 直接放上去。

这里，galalist-section 和 galalist-pic 是用来排版的。它们所对应的 CSS 规则在这里：

yj.zgzg.io/assets/css/style.scss

Lines 184 to 190 in d11235a

	@media screen and (min-width: 767px) {
	img.galalist-pic {
	width: 30%;
	float: left;
	margin:0px 20px 40px 20px;
	border-radius: 10px;
	}

（⚠️注意：我们采用 SCSS 作为“样式语言”（styling language）。它是 CSS 的一种超集（superset）。）

LICENSE

The MIT License (MIT).

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Ming 🚇 ⚠️ 💻

Bowen Xu 💻

rtq998916 💻

Flora Xue 💻 👀

Kongtao Chen 💻

This project follows the all-contributors specification. Contributions of any kind welcome!