Skip to main content Link Search Menu Expand Document (external link)
Jekyll 文档

欢迎！您有兴趣为 Jekyll 做贡献吗？我们衷心感谢您的帮助。Jekyll 是一个开源项目，是被一个个像您一样的开发者一点一点的贡献力量才做到现在的。

哪里能寻求帮助或者上报程序问题

查阅支持大纲

贡献方式

不管您是开发者、设计者还是 Jekyll 的爱好者（Devotee），都有很多种方式做贡献。这里归纳了一些：

  • 在您的计算机上安装 Jekyll and kick the tires. Does it work? Does it do what you’d expect? If not, open an issue and let us know.
  • 对项目的某些开放问题进行评论。Have you experienced the same problem? Know a work around? Do you have a suggestion for how the feature could be better?
  • 阅读文档，如果发现有些地方语义模糊或者需要完善，随时可以点击“完善本页内容”按钮进行编辑修改。
  • 浏览 Jekyll 论坛，回答相关问题。There’s a good chance you’ve already experienced what another user is experiencing.
  • 找到开放问题（尤其是那些标记为 help-wanted 的问题），提交修复建议。If it’s your first pull request, we promise we won’t bite, and are glad to answer any questions.
  • 帮助解决开放拉取请求，在本地测试修改，然后审核其功能。

提交一个拉取请求

常见拉取请求

  • The smaller the proposed change, the better. If you’d like to propose two unrelated changes, submit two pull requests.

  • The more information, the better. Make judicious use of the pull request body. Describe what changes were made, why you made them, and what impact they will have for users.

  • If this is your first pull request, it may help to understand GitHub Flow.

  • If you’re submitting a code contribution, be sure to read the 贡献代码 section below.

通过 github.com 提交一个拉取请求

Many small changes can be made entirely through the github.com web interface.

  1. Navigate to the file within jekyll/jekyll that you’d like to edit.
  2. Click the pencil icon in the top right corner to edit the file
  3. Make your proposed changes
  4. Click “Propose file change”
  5. Click “Create pull request”
  6. Add a descriptive title and detailed description for your proposed change. The more information the better.
  7. Click “Create pull request”

That’s it! You’ll be automatically subscribed to receive updates as others review your proposed change and provide feedback.

通过 Git 命令行提交一个拉取请求

  1. Fork the project by clicking “Fork” in the top right corner of jekyll/jekyll.
  2. Clone the repository locally git clone https://github.com/<you-username>/jekyll.
  3. Create a new, descriptively named branch to contain your change ( git checkout -b my-awesome-feature ).
  4. Hack away, add tests. Not necessarily in that order.
  5. Make sure everything still passes by running script/cibuild (查阅测试部分 below)
  6. Push the branch up ( git push origin my-awesome-feature ).
  7. Create a pull request by visiting https://github.com/<your-username>/jekyll and following the instructions at the top of the screen.

计划更新文档

We want the Jekyll documentation to be the best it can be. We’ve open-sourced our docs and we welcome any pull requests if you find it lacking.

如果提交修改

You can find the documentation for jekyllrb.com in the docs directory. See the section above, submitting a pull request for information on how to propose a change.

One gotcha, all pull requests should be directed at the master branch (the default branch).

更新 jekyllrb.com 的 FontAwesome 图标

We use a custom version of FontAwesome which contains just the icons we use.

If you ever need to update our documentation with an icon that is not already available in our custom iconset, you’ll have to regenerate the iconset using Icomoon’s Generator:

  1. Go to https://icomoon.io/app/.
  2. Click Import Icons on the top-horizontal-bar and upload the existing <jekyll>/docs/icomoon-selection.json.
  3. Click Add Icons from Library.. further down on the page, and add ‘Font Awesome’.
  4. Select the required icon(s) from the Library (make sure its the ‘FontAwesome’ library instead of ‘IcoMoon-Free’ library).
  5. Click Generate Font on the bottom-horizontal-bar.
  6. Inspect the included icons and proceed by clicking Download.
  7. Extract the font files and adapt the CSS to the paths we use in Jekyll:
  • Copy the entire fonts directory over and overwrite existing ones at <jekyll>/docs/.
  • Copy the contents of selection.json and overwrite existing content inside <jekyll>/docs/icomoon-selection.json.
  • Copy the entire @font-face {} declaration and only the new-icon(s)’ css declarations further below, to update the <jekyll>/docs/_sass/_font-awesome.scss sass partial.
  • Fix paths in the @font-face {} declaration by adding ../ before fonts/FontAwesome.* like so: ('../fonts/Fontawesome.woff?9h6hxj').

添加插件

If you want to add your plugin to the list of plugins, please submit a pull request modifying the plugins page source file by adding a link to your plugin under the proper subheading depending upon its type.

贡献代码

Interested in submitting a pull request? Awesome. Read on. There’s a few common gotchas that we’d love to help you avoid.

测试和文档

Any time you propose a code change, you should also include updates to the documentation and tests within the same pull request.

文档

If your contribution changes any Jekyll behavior, make sure to update the documentation. Documentation lives in the docs/_docs folder (spoiler alert: it’s a Jekyll site!). If the docs are missing information, please feel free to add it in. Great docs make a great project. Include changes to the documentation within your pull request, and once merged, jekyllrb.com will be updated.

测试

  • If you’re creating a small fix or patch to an existing feature, a simple test is more than enough. You can usually copy/paste from an existing example in the tests folder, but if you need you can find out about our tests suites Shoulda and RSpec-Mocks.

  • If it’s a brand new feature, create a new Cucumber feature, reusing existing steps where appropriate.

常见贡献代码

  • Jekyll uses the Rubocop static analyzer to ensure that contributions follow the GitHub Ruby Styleguide. Please check your code using script/fmt and resolve any errors before pushing your branch.

  • Don’t bump the Gem version in your pull request (if you don’t know what that means, you probably didn’t).

  • You can use the command script/console to start a REPL to explore the result of Jekyll’s methods. It also provides you with helpful methods to quickly create a site or configuration. Feel free to check it out!

  • Previously, we’ve used the WIP Probot app to help contributors determine whether their pull request is ready for review. Please use a draft pull request instead. When you’re ready, mark the pull request as ready for review

本地测试

测试依赖

To run the test suite and build the gem you’ll need to install Jekyll’s dependencies by running the following command:

script/bootstrap

Before you make any changes, run the tests and make sure that they pass (to confirm your environment is configured properly):

script/cibuild

If you are only updating a file in test/, you can use the command:

script/test test/blah_test.rb

If you are only updating a .feature file, you can use the command:

script/cucumber features/blah.feature

Both script/test and script/cucumber can be run without arguments to run its entire respective suite.

Visual Studio Code 开发容器

If you’ve got Visual Studio Code with the Remote Development Extension Pack installed then simply opening this repository in Visual Studio Code and following the prompts to “Re-open In A Development Container” will get you setup and ready to go with a fresh environment with all the requirements installed.

感谢

Thanks! Hacking on Jekyll should be fun. If you find any of this hard to figure out, let us know so we can improve our process or documentation!