为《载歌在谷》志愿者社区,本代码库托管其官方网站的源代码。
想要开发这个网站,需要用到以下工具:
本网站使用 Jekyll 渲染。安装 Jekyll 之后,您可以运行以下命令来在您的电脑上(“本地”)打开这个网站:
bundle exec jekyll serve
本代码库使用 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
文件夹,但它已经被弃用了。若需要存放照片,请使用我们自己的 Cloudinary 服务。
_layouts
:当朴素的layout: page
难以满足您的表达需求时,您可以创建新的 layout,存放于这里。请参见下文“如何自由排版”一节。_includes
:存放可复用的一些元件。复用可以发生在:assets
:存放了一些脚本和样式表文件。assets/css/style.scss
:许多仅对《载歌在谷》有意义的样式(与“对其他网站也有用”相对),都被存放到了这里。如春晚横幅:https://github.com/zgzgorg/yj.zgzg.io/blob/d11235a52359996f299a1bdab37669251c10d21c/assets/css/style.scss#L357-L364assets/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”:
接下来,我们创建一个 _layouts/gala.html
文件。虽然这是一个 HTML 文档,但是我们依然可以写入 front matter。在它的 front matter 里,我们写“请把这个 layout 嵌套在叫 default 的那个 layout 里”:
接下来的工作,就是常见的“写 HTML”了。其实,我们写的不会是纯粹的 HTML,而是一种叫 Liquid 的“模板语言”(templating language)。模板语言提供一些高阶功能,比如引用一些模块。例如,在现今的 _layouts/gala.html
底部,我们就有引用两个模块:
这些模块存放于 _includes/
文件夹下。例如,上面引用的第一个模块,就在 _includes/galalist.html
:
这个模块很好地体现了 Jekyll 里的“枚举”该怎么用。注意这一行:
它说:“请在本网站(site
)的 data
文件夹下,找到叫 data
的 YAML 文件,读取其中的 galalist
列表。对于其中每个项目(以 pic
指代),重复渲染下述内容“。这里所指的”下述内容“,即是:
它说:
放置一个
galalist-section
类型的分区(division,div
)。在里面放:
- 一个图片(
img
),图片链接为pic.image
;- 在那之后放一个三级标题(
h3
),内容为pic.title
;- 最后,把
pic.description
直接放上去。
这里,galalist-section
和 galalist-pic
是用来排版的。它们所对应的 CSS 规则在这里:
(
The MIT License (MIT).
Thanks goes to these wonderful people (emoji key):
Ming 🚇 |
This project follows the all-contributors specification. Contributions of any kind welcome!