From 85aebe9b9041b8dec2a1c3072d86af2091463e7e Mon Sep 17 00:00:00 2001 From: Frank Taillandier Date: Tue, 3 Oct 2017 09:52:13 +0200 Subject: [PATCH] Docs: updates (#6407) Merge pull request 6407 --- .github/CONTRIBUTING.markdown | 16 +++- docs/_config.yml | 1 - docs/_docs/collections.md | 2 +- docs/_docs/continuous-integration/circleci.md | 4 +- .../_docs/continuous-integration/travis-ci.md | 2 +- docs/_docs/contributing.md | 16 +++- docs/_docs/datafiles.md | 13 ++- docs/_docs/frontmatter.md | 12 +-- docs/_docs/github-pages.md | 4 +- docs/_docs/includes.md | 59 +++++++++---- docs/_docs/index.md | 2 +- docs/_docs/pagination.md | 18 ++-- docs/_docs/plugins.md | 4 +- docs/_docs/posts.md | 82 +++++++++++-------- docs/_docs/static_files.md | 12 +-- docs/_docs/templates.md | 32 ++++---- docs/_docs/themes.md | 8 +- docs/_docs/troubleshooting.md | 4 +- docs/_docs/upgrading/0-to-2.md | 2 +- docs/_docs/upgrading/2-to-3.md | 13 +-- docs/_docs/usage.md | 29 +++---- docs/_docs/windows.md | 38 ++++----- .../2014-12-22-jekyll-2-5-3-released.markdown | 2 +- docs/_sass/_pygments.scss | 12 +-- .../convert-existing-site-to-jekyll.md | 2 +- docs/_tutorials/custom-404-page.md | 11 +-- docs/_tutorials/navigation.md | 55 +++++++++---- docs/_tutorials/orderofinterpretation.md | 48 +++++++---- docs/community/index.md | 6 +- 29 files changed, 299 insertions(+), 210 deletions(-) diff --git a/.github/CONTRIBUTING.markdown b/.github/CONTRIBUTING.markdown index 14cbecc1..91d18e7f 100644 --- a/.github/CONTRIBUTING.markdown +++ b/.github/CONTRIBUTING.markdown @@ -121,19 +121,27 @@ site or configuration. [Feel free to check it out!](https://github.com/jekyll/je To run the test suite and build the gem you'll need to install Jekyll's dependencies by running the following command: -
$ script/bootstrap
+```sh +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
+```sh +script/cibuild +``` If you are only updating a file in `test/`, you can use the command: -
$ script/test test/blah_test.rb
+```sh +script/test test/blah_test.rb +``` If you are only updating a `.feature` file, you can use the command: -
$ script/cucumber features/blah.feature
+```sh +script/cucumber features/blah.feature +``` Both `script/test` and `script/cucumber` can be run without arguments to run its entire respective suite. diff --git a/docs/_config.yml b/docs/_config.yml index 044cb386..130ed1a3 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -8,7 +8,6 @@ google_analytics_id: UA-50755011-1 google_site_verification: onQcXpAvtHBrUI5LlroHNE_FP0b2qvFyPq7VZw36iEY repository: https://github.com/jekyll/jekyll -help_url: https://github.com/jekyll/jekyll-help timezone: America/Los_Angeles diff --git a/docs/_docs/collections.md b/docs/_docs/collections.md index f0fed8ab..3d42bd88 100644 --- a/docs/_docs/collections.md +++ b/docs/_docs/collections.md @@ -454,7 +454,7 @@ works: Every album in the collection could be listed on a single page with a template: -```html +```liquid {% raw %} {% for album in site.albums %}

{{ album.title }}

diff --git a/docs/_docs/continuous-integration/circleci.md b/docs/_docs/continuous-integration/circleci.md index fede484a..4dd29053 100644 --- a/docs/_docs/continuous-integration/circleci.md +++ b/docs/_docs/continuous-integration/circleci.md @@ -40,7 +40,7 @@ CircleCI detects when `Gemfile` is present is will automatically run `bundle ins The most basic test that can be run is simply seeing if `jekyll build` actually works. This is a blocker, a dependency if you will, for other tests you might run on the generate site. So we'll run Jekyll, via Bundler, in the `dependencies` phase. -``` +```yaml dependencies: post: - bundle exec jekyll build @@ -63,7 +63,7 @@ test: When you put it all together, here's an example of what that `circle.yml` file could look like: -``` +```yaml machine: environment: NOKOGIRI_USE_SYSTEM_LIBRARIES: true # speeds up installation of html-proofer diff --git a/docs/_docs/continuous-integration/travis-ci.md b/docs/_docs/continuous-integration/travis-ci.md index 91323958..cbff5267 100644 --- a/docs/_docs/continuous-integration/travis-ci.md +++ b/docs/_docs/continuous-integration/travis-ci.md @@ -49,7 +49,7 @@ Some options can be specified via command-line switches. Check out the For example to avoid testing external sites, use this command: ```sh -$ bundle exec htmlproofer ./_site --disable-external +bundle exec htmlproofer ./_site --disable-external ``` ### The HTML Proofer Library diff --git a/docs/_docs/contributing.md b/docs/_docs/contributing.md index b8a838a7..5cf0398c 100644 --- a/docs/_docs/contributing.md +++ b/docs/_docs/contributing.md @@ -125,19 +125,27 @@ site or configuration. [Feel free to check it out!](https://github.com/jekyll/je To run the test suite and build the gem you'll need to install Jekyll's dependencies by running the following command: -
$ script/bootstrap
+```sh +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
+```sh +script/cibuild +``` If you are only updating a file in `test/`, you can use the command: -
$ script/test test/blah_test.rb
+```sh +script/test test/blah_test.rb +``` If you are only updating a `.feature` file, you can use the command: -
$ script/cucumber features/blah.feature
+```sh +script/cucumber features/blah.feature +``` Both `script/test` and `script/cucumber` can be run without arguments to run its entire respective suite. diff --git a/docs/_docs/datafiles.md b/docs/_docs/datafiles.md index 671a3206..f5971519 100644 --- a/docs/_docs/datafiles.md +++ b/docs/_docs/datafiles.md @@ -56,8 +56,8 @@ determines the variable name). You can now render the list of members in a template: -```html {% raw %} +```liquid -{% endraw %} ``` +{% endraw %} {: .note .info } If your Jekyll site has a lot of pages, such as with documentation websites, see the detailed examples in [how to build robust navigation for your site]({% link _tutorials/navigation.md %}). @@ -106,8 +106,8 @@ members: The organizations can then be accessed via `site.data.orgs`, followed by the file name: -```html {% raw %} +```liquid -{% endraw %} ``` +{% endraw %} ## Example: Accessing a specific author @@ -136,8 +136,8 @@ dave: The author can then be specified as a page variable in a post's frontmatter: -```html {% raw %} +```liquid --- title: sample post author: dave @@ -149,8 +149,7 @@ author: dave title="{{ author.name }}"> {{ author.name }} - -{% endraw %} ``` +{% endraw %} For information on how to build robust navigation for your site (especially if you have a documentation website or another type of Jekyll site with a lot of pages to organize), see [Navigation](/tutorials/navigation). diff --git a/docs/_docs/frontmatter.md b/docs/_docs/frontmatter.md index b2b7699c..761c8bb5 100644 --- a/docs/_docs/frontmatter.md +++ b/docs/_docs/frontmatter.md @@ -65,13 +65,13 @@ front matter of a page or post. If set, this specifies the layout file to use. Use the layout file name without the file extension. Layout files must be placed in the - _layouts directory. + _layouts directory.

``` +{% endraw %} The result would be as follows: @@ -523,8 +540,9 @@ Here's the code for getting lists of pages grouped under their corresponding cat **Liquid** +{% raw %} ```liquid -{% raw %}{% assign mydocs = site.docs | group_by: 'category' %} +{% assign mydocs = site.docs | group_by: 'category' %} {% for cat in mydocs %}

{{ cat.name | capitalize }}

-{% endfor %}{% endraw %} +{% endfor %} ``` +{% endraw %} **Result** @@ -574,6 +593,6 @@ After getting the category name, we assign the variable `items` for the docs and The `for item in items` loop looks through each `item` and gets the `title` and `url` to form the list item link. -For more details on the `group_by` filter, see [Jekyll's Templates documentation](https://jekyllrb.com/docs/templates/) as well as [this Siteleaf tutorial](https://www.siteleaf.com/blog/advanced-liquid-group-by/). For more details on the `sort` filter, see [sort](https://help.shopify.com/themes/liquid/filters/array-filters#sort) in Liquid's documentation. +For more details on the `group_by` filter, see [Jekyll's Templates documentation](https://jekyllrb.com/docs/templates/) as well as [this Siteleaf tutorial](https://www.siteleaf.com/blog/advanced-liquid-group-by/). For more details on the `sort` filter, see [sort](https://shopify.github.io/liquid/filters/sort/) in Liquid's documentation. Whether you use properties in your doc's front matter to retrieve your pages or a YAML data file, in both cases you can programmatically build a more robust navigation for your site. diff --git a/docs/_tutorials/orderofinterpretation.md b/docs/_tutorials/orderofinterpretation.md index 8cf9da55..b0ea0ec7 100644 --- a/docs/_tutorials/orderofinterpretation.md +++ b/docs/_tutorials/orderofinterpretation.md @@ -37,15 +37,19 @@ The following scenarios highlight potential problems you might encounter. These In your layout file (`_layouts/default.html`), suppose you have a variable assigned: +{% raw %} +```liquid +{% assign myvar = "joe" %} ``` -{% raw %}{% assign myvar = "joe" %}{% endraw %} -``` +{% endraw %} On a page that uses the layout, you reference that variable: +{% raw %} +```liquid +{{ myvar }} ``` -{% raw %}{{ myvar }}{% endraw %} -``` +{% endraw %} The variable won't render because the page's order of interpretation is to render Liquid first and later process the Layout. When the Liquid rendering happens, the variable assignment isn't available. @@ -63,9 +67,11 @@ This is a list: You include the file into an HTML file as follows: +{% raw %} ```liquid -{% raw %}{% include mycontent.md %}{% endraw %} +{% include mycontent.md %} ``` +{% endraw %} The Markdown is not processed because first the Liquid (`include` tag) gets processed, inserting `mycontent.md` into the HTML file. *Then* the Markdown would get processed. @@ -75,11 +81,13 @@ To make the code work, use HTML formatting in includes that are inserted into HT Note that `highlight` tags don't require Markdown to process. Suppose your include contains the following: +{% raw %} ```liquid -{% raw %}{% highlight javascript %} +{% highlight javascript %} console.log('alert'); -{% endhighlight %}{% endraw %} +{% endhighlight %} ``` +{% endraw %} The `highlight` tag *is* Liquid. (Liquid passes the content to Rouge or Pygments for syntax highlighting.) As a result, this code will actually convert to HTML with syntax highlighting. Jekyll does not need the Markdown filter to process `highlight` tags. @@ -87,8 +95,9 @@ The `highlight` tag *is* Liquid. (Liquid passes the content to Rouge or Pygments Suppose you try to mix Liquid's `assign` tag with JavaScript, like this: +{% raw %} ```javascript -{% raw %} +

@@ -97,15 +106,17 @@ Suppose you try to mix Liquid's `assign` tag with JavaScript, like this: function someFunction() { document.getElementById("intro").innerHTML = someContent; } -{% endraw %} + ``` +{% endraw %} This won't work because the `assign` tag is only available during the Liquid rendering phase of the site. In this JavaScript example, the script executes when a user clicks a button ("Click me") on the HTML page. At that time, the Liquid logic is no longer available, so the `assign` tag wouldn't return anything. However, you can use Jekyll's site variables or Liquid to *populate* a script that is executed at a later time. For example, suppose you have the following property in your front matter: `someContent: "This is some content"`. You could do this: +{% raw %} ```js -{% raw %} +

@@ -114,8 +125,9 @@ However, you can use Jekyll's site variables or Liquid to *populate* a script th function someFunction() { document.getElementById("intro").innerHTML = "{{ page.someContent }}"; } -{% endraw %} + ``` +{% endraw %} When Jekyll builds the site, this `someContent` property populates the script's values, converting `{% raw %}{{ page.someContent }}{% endraw %}` to `"This is some content"`. @@ -127,17 +139,21 @@ There's one more detail to remember: Liquid does not render when embedded in YAM For example, suppose you have a `highlight` tag in your `_data/mydata.yml` file: -``` -{% raw %}myvalue: > +{% raw %} +```liquid +myvalue: > {% highlight javascript %} console.log('alert'); - {% endhighlight %}{% endraw %} + {% endhighlight %} ``` +{% endraw %} On a page, you try to insert the value: +{% raw %} +```liquid +{{ site.data.mydata.myvalue }} ``` -{% raw %}{{ site.data.mydata.myvalue }}{% endraw %} -``` +{% endraw %} This would render only as a string rather than a code sample with syntax highlighting. To make the code render, consider using an include instead. diff --git a/docs/community/index.md b/docs/community/index.md index 3df84c37..fb3c8e40 100644 --- a/docs/community/index.md +++ b/docs/community/index.md @@ -4,9 +4,11 @@ title: Community permalink: /community/ --- +## Jekyllconf + [JekyllConf](http://jekyllconf.com) is a free, online conference for all things Jekyll hosted by [CloudCannon](http://cloudcannon.com). Each year members of the Jekyll community speak about interesting use cases, tricks they've learned, or meta Jekyll topics. -## Featured +### Featured {% assign random = site.time | date: "%s%N" | modulo: site.data.jekyllconf-talks.size %} {% assign featured = site.data.jekyllconf-talks[random] %} @@ -17,7 +19,7 @@ permalink: /community/ {% assign talks = site.data.jekyllconf-talks | group_by: 'year' %} {% for year in talks reversed %} -## {{ year.name }} +### {{ year.name }} {% for talk in year.items %} * [{{ talk.topic }}](https://youtu.be/{{ talk.youtube_id }}) - [{{ talk.speaker }}](https://twitter.com/{{ talk.twitter_handle }}) {% endfor %}