From 8c3276133d6e5c7cb5ff6936ef3afad143444079 Mon Sep 17 00:00:00 2001 From: Eric Knibbe Date: Fri, 21 Feb 2020 06:08:48 -0500 Subject: [PATCH] docs: improve highlighting of code blocks (#8017) Merge pull request 8017 --- docs/_config.yml | 3 + docs/_docs/assets.md | 1 - docs/_docs/collections.md | 7 +- docs/_docs/community/community.md | 1 - .../configuration/front-matter-defaults.md | 1 - docs/_docs/configuration/markdown.md | 8 +- docs/_docs/configuration/options.md | 1 - .../_docs/continuous-integration/travis-ci.md | 2 +- docs/_docs/datafiles.md | 2 +- docs/_docs/deployment/automated.md | 2 +- docs/_docs/deployment/manual.md | 1 - docs/_docs/deployment/third-party.md | 1 - docs/_docs/includes.md | 2 +- docs/_docs/installation/macos.md | 12 +- docs/_docs/installation/other-linux.md | 2 +- docs/_docs/installation/windows.md | 4 +- docs/_docs/layouts.md | 14 +- docs/_docs/liquid.md | 2 +- docs/_docs/liquid/filters.md | 22 ++- docs/_docs/liquid/tags.md | 8 +- .../maintaining/merging-a-pull-request.md | 2 +- docs/_docs/pages.md | 4 +- docs/_docs/permalinks.md | 3 +- docs/_docs/plugins/installation.md | 12 +- docs/_docs/plugins/tags.md | 12 +- docs/_docs/posts.md | 14 +- docs/_docs/ruby-101.md | 1 - docs/_docs/step-by-step/01-setup.md | 12 +- docs/_docs/step-by-step/02-liquid.md | 3 +- docs/_docs/step-by-step/03-front-matter.md | 7 +- docs/_docs/step-by-step/04-layouts.md | 6 +- docs/_docs/step-by-step/05-includes.md | 4 +- docs/_docs/step-by-step/07-assets.md | 6 +- docs/_docs/step-by-step/08-blogging.md | 8 +- docs/_docs/step-by-step/09-collections.md | 10 +- docs/_docs/step-by-step/10-deployment.md | 12 +- docs/_docs/structure.md | 2 +- docs/_docs/themes.md | 63 +++++---- docs/_docs/troubleshooting.md | 8 +- docs/_docs/upgrading/0-to-2.md | 3 +- docs/_docs/upgrading/2-to-3.md | 8 +- docs/_docs/upgrading/3-to-4.md | 2 +- docs/_posts/2016-10-06-jekyll-3-3-is-here.md | 12 +- .../2018-01-25-jekyll-3-7-2-released.md | 2 +- docs/_tutorials/cache_api.md | 1 - .../convert-existing-site-to-jekyll.md | 133 +++++++++++------- docs/_tutorials/custom-404-page.md | 3 +- docs/_tutorials/index.md | 2 - docs/_tutorials/navigation.md | 9 +- docs/_tutorials/orderofinterpretation.md | 12 +- docs/_tutorials/using-jekyll-with-bundler.md | 1 - docs/_tutorials/video-walkthroughs.md | 2 - 52 files changed, 247 insertions(+), 228 deletions(-) diff --git a/docs/_config.yml b/docs/_config.yml index 35783109..bec8b14f 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -46,6 +46,9 @@ plugins: feed: categories: - release +kramdown: + syntax_highlighter_opts: + default_lang: plaintext sass: style: compressed strict_front_matter: true diff --git a/docs/_docs/assets.md b/docs/_docs/assets.md index 618b54aa..ee4e698b 100644 --- a/docs/_docs/assets.md +++ b/docs/_docs/assets.md @@ -79,7 +79,6 @@ sass: These are passed to Sass, so any output style options Sass supports are valid here, too. - ## Coffeescript To enable Coffeescript in Jekyll 3.0 and up you must diff --git a/docs/_docs/collections.md b/docs/_docs/collections.md index 67b80c3e..00e41181 100644 --- a/docs/_docs/collections.md +++ b/docs/_docs/collections.md @@ -15,7 +15,8 @@ example here's a collection of staff members: collections: - staff_members ``` -In this case `collections` is defined as a sequence (i.e array) with no additional metadata defined for each collection. + +In this case `collections` is defined as a sequence (i.e array) with no additional metadata defined for each collection. You can optionally specify metadata for your collection by defining `collections` as a mapping (i.e hashmap) instead of sequence, and then defining additional fields in it: ```yaml @@ -71,7 +72,7 @@ Jane has worked on Jekyll for the past *five years*. Do note that in spite of being considered as a collection internally, the above doesn't apply to [posts](/docs/posts/). Posts with a valid filename format will be marked for processing even if they do not contain front matter. - +
Be sure to name your directories correctly
@@ -96,7 +97,6 @@ using the `content` variable: ``` {% endraw %} - If you'd like Jekyll to create a rendered page for each document in your collection, you can set the `output` key to `true` in your collection metadata in `_config.yml`: @@ -285,7 +285,6 @@ you specified in your `_config.yml` (if present) and the following information:

- ### Documents In addition to any front matter provided in the document's corresponding diff --git a/docs/_docs/community/community.md b/docs/_docs/community/community.md index 36ba52c4..7176dfe5 100644 --- a/docs/_docs/community/community.md +++ b/docs/_docs/community/community.md @@ -28,7 +28,6 @@ There are a bunch of helpful community members on these services that should be * [How to file a bug](/docs/community/bug/) * [Guide for maintaining Jekyll](/docs/maintaining/) - ## Jekyllconf [Watch videos](/jekyllconf/) from members of the Jekyll community speak about interesting use cases, tricks they’ve learned or meta Jekyll topics. diff --git a/docs/_docs/configuration/front-matter-defaults.md b/docs/_docs/configuration/front-matter-defaults.md index ae5183d0..2f19954e 100644 --- a/docs/_docs/configuration/front-matter-defaults.md +++ b/docs/_docs/configuration/front-matter-defaults.md @@ -114,7 +114,6 @@ defaults:

- ### Precedence Jekyll will apply all of the configuration settings you specify in the `defaults` section of your `_config.yml` file. You can choose to override settings from other scope/values pair by specifying a more specific path for the scope. diff --git a/docs/_docs/configuration/markdown.md b/docs/_docs/configuration/markdown.md index 16090618..2b48a94e 100644 --- a/docs/_docs/configuration/markdown.md +++ b/docs/_docs/configuration/markdown.md @@ -51,7 +51,7 @@ currently supported options:

-For more details about these options have a look at the [Kramdown configuration documentation](https://kramdown.gettalong.org/options.html). +For more details about these options have a look at the [Kramdown configuration documentation](https://kramdown.gettalong.org/options.html). ### CommonMark @@ -78,9 +78,9 @@ extension for disabling fenced code. Note that you can also specify a language for highlighting after the first delimiter: - ```ruby - # ...ruby code - ``` + ```ruby + # ...ruby code + ``` With both fenced code blocks and highlighter enabled, this will statically highlight the code; without any syntax highlighter, it will add a diff --git a/docs/_docs/configuration/options.md b/docs/_docs/configuration/options.md index 8af5fa0c..1a5e96f0 100644 --- a/docs/_docs/configuration/options.md +++ b/docs/_docs/configuration/options.md @@ -346,7 +346,6 @@ class="flag">flags (specified on the command-line) that control them. - ### Serve Command Options In addition to the options below, the `serve` sub-command can accept any of the options diff --git a/docs/_docs/continuous-integration/travis-ci.md b/docs/_docs/continuous-integration/travis-ci.md index d87f4b7c..c93f70a1 100644 --- a/docs/_docs/continuous-integration/travis-ci.md +++ b/docs/_docs/continuous-integration/travis-ci.md @@ -34,7 +34,7 @@ Save the commands you want to run and succeed in a file: `./script/cibuild` ### The HTML Proofer Executable -```sh +```bash #!/usr/bin/env bash set -e # halt script on error diff --git a/docs/_docs/datafiles.md b/docs/_docs/datafiles.md index 742b3273..9a9961c7 100644 --- a/docs/_docs/datafiles.md +++ b/docs/_docs/datafiles.md @@ -42,7 +42,7 @@ In `_data/members.yml`: Or `_data/members.csv`: -```text +``` name,github Eric Mill,konklone Parker Moore,parkr diff --git a/docs/_docs/deployment/automated.md b/docs/_docs/deployment/automated.md index 5f6300c1..0e68e90f 100644 --- a/docs/_docs/deployment/automated.md +++ b/docs/_docs/deployment/automated.md @@ -11,7 +11,7 @@ CI. These services run a script when there's a commit on your Git repository. You might want this script to build the site, run tests over the output then deploy it to the -service of your choice. +service of your choice. We have guides for the following providers: diff --git a/docs/_docs/deployment/manual.md b/docs/_docs/deployment/manual.md index 14d65d4a..be1054a0 100644 --- a/docs/_docs/deployment/manual.md +++ b/docs/_docs/deployment/manual.md @@ -31,7 +31,6 @@ Most traditional web hosting provider let you upload files to their servers over If you have direct access to the deployment web server, the process is essentially the same, except you might have other methods available to you (such as `scp`, or even direct filesystem access) for transferring the files. Remember to make sure the contents of the generated `_site` folder get placed in the appropriate web root directory for your web server. - ## Rack-Jekyll [Rack-Jekyll](https://github.com/adaoraul/rack-jekyll/) allows you to deploy your site on any Rack server such as Amazon EC2, Slicehost, Heroku, and so forth. It also can run with [shotgun](https://github.com/rtomayko/shotgun/), [rackup](https://github.com/rack/rack), [mongrel](https://github.com/mongrel/mongrel), [unicorn](https://github.com/defunkt/unicorn/), and [others](https://github.com/adaoraul/rack-jekyll#readme). diff --git a/docs/_docs/deployment/third-party.md b/docs/_docs/deployment/third-party.md index efe00370..7c25c574 100644 --- a/docs/_docs/deployment/third-party.md +++ b/docs/_docs/deployment/third-party.md @@ -33,7 +33,6 @@ Kickster provides a basic Jekyll project setup packed with web best practises an Install the Kickster gem and you are good to go. More documentation can here found [here](https://github.com/nielsenramon/kickster#kickster). If you do not want to use the gem or start a new project you can just copy paste the deployment scripts for [Travis CI](https://github.com/nielsenramon/kickster/tree/master/snippets/travis) or [Circle CI](https://github.com/nielsenramon/kickster#automated-deployment-with-circle-ci). - ## Netlify Netlify provides Global CDN, Continuous Deployment, one click HTTPS and [much more](https://www.netlify.com/features/), providing developers the most robust toolset available for modern web projects, without added complexity. Netlify supports custom plugins for Jekyll and has a free plan for open source projects. diff --git a/docs/_docs/includes.md b/docs/_docs/includes.md index d92da1de..2112a6b0 100644 --- a/docs/_docs/includes.md +++ b/docs/_docs/includes.md @@ -69,7 +69,7 @@ You can also pass parameters to an include. For example, suppose you have a file ``` {% endraw %} -The `{% raw %}{{ include.content }}{% endraw %}` is a parameter that gets populated when you call the include and specify a value for that parameter, like this: +The {% raw %}`{{ include.content }}`{% endraw %} is a parameter that gets populated when you call the include and specify a value for that parameter, like this: {% raw %} ```liquid diff --git a/docs/_docs/installation/macos.md b/docs/_docs/installation/macos.md index d22cd77b..6bda6264 100644 --- a/docs/_docs/installation/macos.md +++ b/docs/_docs/installation/macos.md @@ -13,7 +13,7 @@ xcode-select --install ## Install Ruby Jekyll requires **Ruby > {{ site.data.ruby.min_version }}**. -macOS Catalina 10.15 comes with ruby 2.6.3, so you're fine. +macOS Catalina 10.15 comes with ruby 2.6.3, so you're fine. If you're running a previous macOS system, you'll have to install a newer version of Ruby. ### With Homebrew {#brew} @@ -26,9 +26,9 @@ To run the latest Ruby version you need to install it through [Homebrew](https:/ brew install ruby ``` -Add the brew ruby path to your shell config : +Add the brew ruby path to your shell config: -``` +```bash export PATH=/usr/local/opt/ruby/bin:$PATH ``` @@ -56,10 +56,10 @@ Ruby versions. This is very useful when you need to be able to run a given Ruby # Install rbenv and ruby-build brew install rbenv -# Setup rbenv integration to your shell +# Set up rbenv integration with your shell rbenv init -# Check your install +# Check your installation curl -fsSL https://github.com/rbenv/rbenv-installer/raw/master/bin/rbenv-doctor | bash ``` @@ -94,7 +94,7 @@ ruby -v Then append your path file with the following, replacing the `X.X` with the first two digits of your Ruby version. -``` +```bash export PATH=$HOME/.gem/ruby/X.X.0/bin:$PATH ``` diff --git a/docs/_docs/installation/other-linux.md b/docs/_docs/installation/other-linux.md index 88f14775..a220b898 100644 --- a/docs/_docs/installation/other-linux.md +++ b/docs/_docs/installation/other-linux.md @@ -6,7 +6,7 @@ Installation on other Linux distributions works similarly as on [Ubuntu](../ubun On Fedora, the dependencies can be installed as follows: - ```sh +```sh sudo dnf install ruby ruby-devel @development-tools ``` diff --git a/docs/_docs/installation/windows.md b/docs/_docs/installation/windows.md index ceda22b0..73020ba8 100644 --- a/docs/_docs/installation/windows.md +++ b/docs/_docs/installation/windows.md @@ -8,7 +8,6 @@ redirect_from: While Windows is not an officially-supported platform, it can be used to run Jekyll with the proper tweaks. This page aims to collect some of the general knowledge and lessons that have been unearthed by Windows users. - ## Installing Jekyll ### Installation via RubyInstaller @@ -43,11 +42,13 @@ First let's make sure all our packages / repositories are up to date. Open a new ```sh bash ``` + Your Command Prompt instance should now be a Bash instance. Now we must update our repo lists and packages. ```sh sudo apt-get update -y && sudo apt-get upgrade -y ``` + Now we can install Ruby. To do this we will use a repository from [BrightBox](https://www.brightbox.com/docs/ruby/ubuntu/), which hosts optimized versions of Ruby for Ubuntu. @@ -90,7 +91,6 @@ with the current date in the filename. **Note:** Bash on Ubuntu on Windows is still under development, so you may run into issues. - ## Encoding If you use UTF-8 encoding, make sure that no `BOM` header characters exist in your files or very, very bad things will happen to diff --git a/docs/_docs/layouts.md b/docs/_docs/layouts.md index 053da0e5..1ef7c2a2 100644 --- a/docs/_docs/layouts.md +++ b/docs/_docs/layouts.md @@ -24,17 +24,14 @@ from this as needed.

- ## Usage The first step is to put the template source code in `default.html`. `content` is a special variable, the value is the rendered content of the post or page being wrapped. - - {% raw %} -``` +```liquid @@ -67,7 +64,7 @@ You can also use [front matter defaults](/docs/configuration/front-matter-defaults/) to save you from having to set this on every page. -``` +```markdown --- title: My First Page layout: default @@ -78,7 +75,7 @@ This is the content of my page The rendered output of this page is: -``` +```html @@ -102,7 +99,6 @@ The rendered output of this page is: ``` - ## Inheritance Layout inheritance is useful when you want to add something to an existing @@ -115,7 +111,7 @@ layout in front matter. For example this layout will live at `_layouts/post.html`: {% raw %} -``` +```liquid --- layout: default --- @@ -134,7 +130,7 @@ using in Liquid, you need to use the `layout` variable instead of `page`. For example: {% raw %} -``` +```liquid --- city: San Francisco --- diff --git a/docs/_docs/liquid.md b/docs/_docs/liquid.md index 7151cb19..d09ba99b 100644 --- a/docs/_docs/liquid.md +++ b/docs/_docs/liquid.md @@ -5,7 +5,7 @@ redirect_from: "/docs/templates/" --- Jekyll uses the [Liquid](https://shopify.github.io/liquid/) templating language -to process templates. +to process templates. Generally in Liquid you output content using two curly braces e.g. {% raw %}`{{ variable }}`{% endraw %} and perform logic statements by diff --git a/docs/_docs/liquid/filters.md b/docs/_docs/liquid/filters.md index fbd9acdb..9025251a 100644 --- a/docs/_docs/liquid/filters.md +++ b/docs/_docs/liquid/filters.md @@ -108,15 +108,21 @@ The default is `default`. They are as follows (with what they filter): You can use the `where` filter to detect documents and pages with properties that are `nil` or `""`. For example, +{% raw %} ```liquid -// Using `nil` to select posts that either do not have `my_prop` defined or `my_prop` has been set to `nil` explicitly. -{% raw %}{% assign filtered_posts = site.posts | where: 'my_prop', nil %}{% endraw %} +// Using `nil` to select posts that either do not have `my_prop` +// defined or `my_prop` has been set to `nil` explicitly. +{% assign filtered_posts = site.posts | where: 'my_prop', nil %} ``` +{% endraw %} +{% raw %} ```liquid -// Using Liquid's special literal `empty` or `blank` to select posts that have `my_prop` set to an empty value. -{% raw %}{% assign filtered_posts = site.posts | where: 'my_prop', empty %}{% endraw %} +// Using Liquid's special literal `empty` or `blank` to select +// posts that have `my_prop` set to an empty value. +{% assign filtered_posts = site.posts | where: 'my_prop', empty %} ``` +{% endraw %} ### Binary operators in `where_exp` filter {%- include docs_version_badge.html version="4.0" -%} @@ -125,15 +131,19 @@ conditionals in the operation. For example, to get a list of documents on English horror flicks, one could use the following snippet: +{% raw %} ```liquid -{% raw %}{{ site.movies | where_exp: "item", "item.genre == 'horror' and item.language == 'English'" }}{% endraw %} +{{ site.movies | where_exp: "item", "item.genre == 'horror' and item.language == 'English'" }} ``` +{% endraw %} Or to get a list of comic-book based movies, one may use the following: +{% raw %} ```liquid -{% raw %}{{ site.movies | where_exp: "item", "item.sub_genre == 'MCU' or item.sub_genre == 'DCEU'" }}{% endraw %} +{{ site.movies | where_exp: "item", "item.sub_genre == 'MCU' or item.sub_genre == 'DCEU'" }} ``` +{% endraw %} ### Standard Liquid Filters diff --git a/docs/_docs/liquid/tags.md b/docs/_docs/liquid/tags.md index cc181593..50868452 100644 --- a/docs/_docs/liquid/tags.md +++ b/docs/_docs/liquid/tags.md @@ -71,8 +71,8 @@ end In order for the highlighting to show up, you’ll need to include a highlighting stylesheet. For Pygments or Rouge you can use a stylesheet for Pygments, you -can find an example gallery -[here](https://jwarby.github.io/jekyll-pygments-themes/languages/ruby.html) +can find an example gallery +[here](https://jwarby.github.io/jekyll-pygments-themes/languages/ruby.html) or from [its repository](https://github.com/jwarby/jekyll-pygments-themes). Copy the CSS file (`native.css` for example) into your css directory and import @@ -117,11 +117,11 @@ The path to the post, page, or collection is defined as the path relative to the For example, suppose you're creating a link in `page_a.md` (stored in `pages/folder1/folder2`) to `page_b.md` (stored in `pages/folder1`). Your path in the link would not be `../page_b.html`. Instead, it would be `/pages/folder1/page_b.md`. -If you're unsure of the path, add `{% raw %}{{ page.path }}{% endraw %}` to the page and it will display the path. +If you're unsure of the path, add {% raw %}`{{ page.path }}`{% endraw %} to the page and it will display the path. One major benefit of using the `link` or `post_url` tag is link validation. If the link doesn't exist, Jekyll won't build your site. This is a good thing, as it will alert you to a broken link so you can fix it (rather than allowing you to build and deploy a site with broken links). -Note you cannot add filters to `link` tags. For example, you cannot append a string using Liquid filters, such as `{% raw %}{% link mypage.html | append: "#section1" %} {% endraw %}`. To link to sections on a page, you will need to use regular HTML or Markdown linking techniques. +Note you cannot add filters to `link` tags. For example, you cannot append a string using Liquid filters, such as {% raw %}`{% link mypage.html | append: "#section1" %}`{% endraw %}. To link to sections on a page, you will need to use regular HTML or Markdown linking techniques. ### Linking to posts diff --git a/docs/_docs/maintaining/merging-a-pull-request.md b/docs/_docs/maintaining/merging-a-pull-request.md index 0403d05a..34fa1fec 100644 --- a/docs/_docs/maintaining/merging-a-pull-request.md +++ b/docs/_docs/maintaining/merging-a-pull-request.md @@ -20,7 +20,7 @@ We have [a helpful little bot](https://github.com/jekyllbot) which we use to mer To merge a pull request, leave a comment thanking the contributor, then add the special merge request: -```text +``` Thank you very much for your contribution. Folks like you make this project and community strong. :heart: @jekyllbot: merge +dev diff --git a/docs/_docs/pages.md b/docs/_docs/pages.md index fb4bce83..98b21b7d 100644 --- a/docs/_docs/pages.md +++ b/docs/_docs/pages.md @@ -13,7 +13,7 @@ a `.md` extension which converts to HTML on build. For a site with a homepage, an about page, and a contact page, here’s what the root directory and associated URLs might look like: -```sh +``` . |-- about.md # => http://example.com/about.html |-- index.html # => http://example.com/ @@ -22,7 +22,7 @@ and associated URLs might look like: If you have a lot of pages, you can organize them into subfolders. The same subfolders that are used to group your pages in your project's source will then exist in the `_site` folder when your site builds. However, when a page has a *different* permalink set in the front matter, the subfolder at `_site` changes accordingly. -```sh +``` . |-- about.md # => http://example.com/about.html |-- documentation # folder containing pages diff --git a/docs/_docs/permalinks.md b/docs/_docs/permalinks.md index 24e98c13..6ab7994b 100644 --- a/docs/_docs/permalinks.md +++ b/docs/_docs/permalinks.md @@ -16,7 +16,7 @@ For example, you might have a page on your site located at `/my_pages/about-me.html` and you want the output url to be `/about/`. In front matter of the page you would set: -``` +```yaml --- permalink: /about/ --- @@ -46,7 +46,6 @@ For example, a permalink style of Here's the full list of placeholders available: -
diff --git a/docs/_docs/plugins/installation.md b/docs/_docs/plugins/installation.md index ad2bcdd5..02e7b628 100644 --- a/docs/_docs/plugins/installation.md +++ b/docs/_docs/plugins/installation.md @@ -27,12 +27,12 @@ You have 3 options for installing plugins: example: ```ruby - group :jekyll_plugins do - gem "jekyll-gist" - gem "jekyll-coffeescript" - gem "jekyll-assets" - gem "another-jekyll-plugin" - end + group :jekyll_plugins do + gem "jekyll-gist" + gem "jekyll-coffeescript" + gem "jekyll-assets" + gem "another-jekyll-plugin" + end ``` Now you need to install all plugins from your Bundler group by running single command `bundle install`. diff --git a/docs/_docs/plugins/tags.md b/docs/_docs/plugins/tags.md index a5a3af57..fff0a45f 100644 --- a/docs/_docs/plugins/tags.md +++ b/docs/_docs/plugins/tags.md @@ -60,7 +60,7 @@ In the example above, we can place the following tag anywhere in one of our pages: {% raw %} -```ruby +```liquid

{% render_time page rendered at: %}

``` {% endraw %} @@ -73,7 +73,7 @@ And we would get something like this on the page: ## Tag Blocks -The `render_time` tag seen above can also be rewritten as a tag block by +The `render_time` tag seen above can also be rewritten as a tag block by inheriting the `Liquid::Block` class. Look at the example below: ```ruby @@ -108,8 +108,8 @@ And we would still get the same output as above on the page: ```
-

In the above example, the tag block and the tag are both registered with - the name render_time but to register a tag and a tag block using - the same name in the same project is not recommended as this may lead to +

In the above example, the tag block and the tag are both registered with + the name render_time but to register a tag and a tag block using + the same name in the same project is not recommended as this may lead to conflicts.

-
\ No newline at end of file + diff --git a/docs/_docs/posts.md b/docs/_docs/posts.md index 9274ecd3..6fff5a08 100644 --- a/docs/_docs/posts.md +++ b/docs/_docs/posts.md @@ -58,8 +58,6 @@ I hope you like it!

- -
Be aware of character sets

@@ -102,7 +100,7 @@ Creating an index of posts on another page should be easy thanks to simple example of how to create a list of links to your blog posts: {% raw %} -```html +```liquid

    {% for post in site.posts %}
  • @@ -166,7 +164,7 @@ post. By default this is the first paragraph of content in the post, however it can be customized by setting a `excerpt_separator` variable in front matter or `_config.yml`. -```yaml +```markdown --- excerpt_separator: --- @@ -199,9 +197,11 @@ Drafts are posts without a date in the filename. They're posts you're still working on and don't want to publish yet. To get up and running with drafts, create a `_drafts` folder in your site's root and create your first draft: -```text -|-- _drafts/ -| |-- a-draft-post.md +``` +. +├── _drafts +| └── a-draft-post.md +... ``` To preview your site with drafts, run `jekyll serve` or `jekyll build` diff --git a/docs/_docs/ruby-101.md b/docs/_docs/ruby-101.md index 0b6f32c4..6beb166f 100644 --- a/docs/_docs/ruby-101.md +++ b/docs/_docs/ruby-101.md @@ -18,7 +18,6 @@ A gem is code you can include in Ruby projects. It allows you to package up func [jekyll-seo-tag](https://github.com/jekyll/jekyll-seo-tag) and [jekyll-archives](https://github.com/jekyll/jekyll-archives). - ## Gemfile A `Gemfile` is a list of gems required for your site. For a simple Jekyll site it might look something like this: diff --git a/docs/_docs/step-by-step/01-setup.md b/docs/_docs/step-by-step/01-setup.md index e6a7dae1..adfabac5 100644 --- a/docs/_docs/step-by-step/01-setup.md +++ b/docs/_docs/step-by-step/01-setup.md @@ -6,7 +6,7 @@ position: 1 --- Welcome to Jekyll's step-by-step tutorial. The goal of this tutorial is to take you from having some front end web development experience to building your -first Jekyll site from scratch — not relying on the default gem-based theme. +first Jekyll site from scratch — not relying on the default gem-based theme. Let's get into it! ## Installation @@ -18,25 +18,25 @@ instructions for your operating system. With Ruby setup you can install Jekyll by running the following in your terminal: -``` +```sh gem install jekyll bundler ``` To create a new `Gemfile` to list your project's dependencies run: -``` +```sh bundle init ``` -Now edit the `Gemfile`and add jekyll as a dependency: +Now edit the `Gemfile` and add jekyll as a dependency: -``` +```ruby gem "jekyll" ``` Finally run `bundle` to install jekyll for your project. -You can now prefix all jekyll commands listed in this tutorial with `bundle exec` +You can now prefix all jekyll commands listed in this tutorial with `bundle exec` to make sure you use the jekyll version defined in your `Gemfile`. ## Create a site diff --git a/docs/_docs/step-by-step/02-liquid.md b/docs/_docs/step-by-step/02-liquid.md index cd5a9ebf..63f66751 100644 --- a/docs/_docs/step-by-step/02-liquid.md +++ b/docs/_docs/step-by-step/02-liquid.md @@ -7,7 +7,6 @@ Liquid is where Jekyll starts to get more interesting. Liquid is a templating language which has three main parts: [objects](#objects), [tags](#tags) and [filters](#filters). - ## Objects Objects tell Liquid where to output content. They're denoted by double curly @@ -68,7 +67,7 @@ Now it's your turn, change the Hello World! on your page to output as lowercase: To get our changes processed by Jekyll we need to add [front matter](../03-front-matter/) to the top of the page: -```markdown +```yaml --- # front matter tells Jekyll to process Liquid --- diff --git a/docs/_docs/step-by-step/03-front-matter.md b/docs/_docs/step-by-step/03-front-matter.md index f8ab67ac..73279ee6 100644 --- a/docs/_docs/step-by-step/03-front-matter.md +++ b/docs/_docs/step-by-step/03-front-matter.md @@ -7,7 +7,7 @@ Front matter is a snippet of [YAML](http://yaml.org/) which sits between two triple-dashed lines at the top of a file. Front matter is used to set variables for the page, for example: -```liquid +```yaml --- my_number: 5 --- @@ -27,7 +27,7 @@ example to output the variable above you would use: Let's change the `` on your site to populate using front matter: {% raw %} -```html +```liquid --- title: Home --- @@ -44,12 +44,11 @@ title: Home ``` {% endraw %} - Note that in order for Jekyll to process any liquid tags on your page, you _must_ include front matter on it. The most minimal snippet of front matter you can include is: -```liquid +```yaml --- --- ``` diff --git a/docs/_docs/step-by-step/04-layouts.md b/docs/_docs/step-by-step/04-layouts.md index 4bbc28d8..4a9510f1 100644 --- a/docs/_docs/step-by-step/04-layouts.md +++ b/docs/_docs/step-by-step/04-layouts.md @@ -50,7 +50,7 @@ matter. The layout wraps around the content of the page so all you need in `index.html` is: {% raw %} -```html +```liquid --- layout: default title: Home @@ -70,8 +70,7 @@ layout. Add the following to `about.md`: -{% raw %} -```html +```markdown --- layout: default title: About @@ -80,7 +79,6 @@ title: About This page tells you a little bit about me. ``` -{% endraw %} Open <a href="http://localhost:4000/about.html" target="_blank" data-proofer-ignore>http://localhost:4000/about.html</a> in your browser and view your new page. diff --git a/docs/_docs/step-by-step/05-includes.md b/docs/_docs/step-by-step/05-includes.md index 84b2cc0a..6513952d 100644 --- a/docs/_docs/step-by-step/05-includes.md +++ b/docs/_docs/step-by-step/05-includes.md @@ -17,14 +17,14 @@ in an `_includes` folder. Includes are useful for having a single source for source code that repeats around the site or for improving the readability. Navigation source code can get complex so sometimes it's nice to move it into an -include. +include. ## Include usage Create a file for the navigation at `_includes/navigation.html` with the following content: -```liquid +``` <nav> <a href="/">Home</a> <a href="/about.html">About</a> diff --git a/docs/_docs/step-by-step/07-assets.md b/docs/_docs/step-by-step/07-assets.md index 9b6c2544..18c0873d 100644 --- a/docs/_docs/step-by-step/07-assets.md +++ b/docs/_docs/step-by-step/07-assets.md @@ -8,7 +8,7 @@ them in your site folder and they’ll copy across to the built site. Jekyll sites often use this structure to keep assets organized: -```sh +``` . ├── assets | ├── css @@ -38,13 +38,11 @@ to CSS baked right into Jekyll. First create a Sass file at `/assets/css/styles.scss` with the following content: -{% raw %} -```css +```sass --- --- @import "main"; ``` -{% endraw %} The empty front matter at the top tells Jekyll it needs to process the file. The `@import "main"` tells Sass to look for a file called `main.scss` in the sass diff --git a/docs/_docs/step-by-step/08-blogging.md b/docs/_docs/step-by-step/08-blogging.md index 64869e43..07c6ae32 100644 --- a/docs/_docs/step-by-step/08-blogging.md +++ b/docs/_docs/step-by-step/08-blogging.md @@ -39,7 +39,7 @@ The `post` layout doesn't exist so you'll need to create it at `_layouts/post.html` with the following content: {% raw %} -```html +```liquid --- layout: default --- @@ -65,7 +65,7 @@ Jekyll makes posts available at `site.posts`. Create `blog.html` in your root (`/blog.html`) with the following content: {% raw %} -```html +```liquid --- layout: default title: Blog @@ -139,7 +139,7 @@ golden flesh with rows of tiny, black, edible seeds. The fruit has a soft texture, with a sweet and unique flavor. ``` -Open <a href="http://localhost:4000" target="_blank" data-proofer-ignore>http://localhost:4000</a> and have -a look through your blog posts. +Open <a href="http://localhost:4000" target="_blank" data-proofer-ignore>http://localhost:4000</a> +and have a look through your blog posts. Next we'll focus on creating a page for each post author. diff --git a/docs/_docs/step-by-step/09-collections.md b/docs/_docs/step-by-step/09-collections.md index 44ae7425..b4100329 100644 --- a/docs/_docs/step-by-step/09-collections.md +++ b/docs/_docs/step-by-step/09-collections.md @@ -60,7 +60,7 @@ collection available at `site.authors`. Create `staff.html` and iterate over `site.authors` to output all the staff: {% raw %} -```html +```liquid --- layout: default title: Staff @@ -117,7 +117,7 @@ You can link to the output page using `author.url`. Add the link to the `staff.html` page: {% raw %} -```html +```liquid --- layout: default title: Staff @@ -141,7 +141,7 @@ Just like posts you'll need to create a layout for authors. Create `_layouts/author.html` with the following content: {% raw %} -```html +```liquid --- layout: default --- @@ -203,7 +203,7 @@ Iterate over this filtered list in `_layouts/author.html` to output the author's posts: {% raw %} -```html +```liquid --- layout: default --- @@ -228,7 +228,7 @@ The posts have a reference to the author so let's link it to the author's page. You can do this using a similar filtering technique in `_layouts/post.html`: {% raw %} -```html +```liquid --- layout: default --- diff --git a/docs/_docs/step-by-step/10-deployment.md b/docs/_docs/step-by-step/10-deployment.md index 3fc03530..321f0b1e 100644 --- a/docs/_docs/step-by-step/10-deployment.md +++ b/docs/_docs/step-by-step/10-deployment.md @@ -13,7 +13,7 @@ different environments. Create `Gemfile` in the root with the following: -``` +```ruby source 'https://rubygems.org' gem 'jekyll' @@ -27,7 +27,7 @@ creates `Gemfile.lock` which locks the current gem versions for a future When using a `Gemfile`, you'll run commands like `jekyll serve` with `bundle exec` prefixed. So the full command is: -```bash +```sh bundle exec jekyll serve ``` @@ -51,7 +51,7 @@ with SEO To use these first you need to add them to your `Gemfile`. If you put them in a `jekyll_plugins` group they'll automatically be required into Jekyll: -``` +```ruby source 'https://rubygems.org' gem 'jekyll' @@ -65,7 +65,7 @@ end Then add these lines to your `_config.yml`: -``` +```yaml plugins: - jekyll-feed - jekyll-sitemap @@ -109,7 +109,7 @@ To do this you can use [environments](/docs/configuration/environments/). You can set the environment by using the `JEKYLL_ENV` environment variable when running a command. For example: -```bash +```sh JEKYLL_ENV=production bundle exec jekyll build ``` @@ -130,7 +130,7 @@ on production you would do the following: The final step is to get the site onto a production server. The most basic way to do this is to run a production build: -```bash +```sh JEKYLL_ENV=production bundle exec jekyll build ``` diff --git a/docs/_docs/structure.md b/docs/_docs/structure.md index b94193ad..33a74aa7 100644 --- a/docs/_docs/structure.md +++ b/docs/_docs/structure.md @@ -4,7 +4,7 @@ permalink: /docs/structure/ --- A basic Jekyll site usually looks something like this: -```sh +``` . ├── _config.yml ├── _data diff --git a/docs/_docs/themes.md b/docs/_docs/themes.md index dcb5dd07..a518ee2b 100644 --- a/docs/_docs/themes.md +++ b/docs/_docs/themes.md @@ -23,6 +23,7 @@ With gem-based themes, some of the site's directories (such as the `assets`, `_l In the case of Minima, you see only the following files in your Jekyll site directory: ``` +. ├── Gemfile ├── Gemfile.lock ├── _config.yml @@ -75,33 +76,34 @@ To locate a theme's files on your computer: A Finder or Explorer window opens showing the theme's files and directories. The Minima theme gem contains these files: - ``` - ├── LICENSE.txt - ├── README.md - ├── _includes - │   ├── disqus_comments.html - │   ├── footer.html - │   ├── google-analytics.html - │   ├── head.html - │   ├── header.html - │   ├── icon-github.html - │   ├── icon-github.svg - │   ├── icon-twitter.html - │   └── icon-twitter.svg - ├── _layouts - │   ├── default.html - │   ├── home.html - │   ├── page.html - │   └── post.html - ├── _sass - │   ├── minima - │   │   ├── _base.scss - │   │   ├── _layout.scss - │   │   └── _syntax-highlighting.scss - │   └── minima.scss - └── assets - └── main.scss - ``` + ``` + . + ├── LICENSE.txt + ├── README.md + ├── _includes + │   ├── disqus_comments.html + │   ├── footer.html + │   ├── google-analytics.html + │   ├── head.html + │   ├── header.html + │   ├── icon-github.html + │   ├── icon-github.svg + │   ├── icon-twitter.html + │   └── icon-twitter.svg + ├── _layouts + │   ├── default.html + │   ├── home.html + │   ├── page.html + │   └── post.html + ├── _sass + │   ├── minima + │   │   ├── _base.scss + │   │   ├── _layout.scss + │   │   └── _syntax-highlighting.scss + │   └── minima.scss + └── assets + └── main.scss + ``` With a clear understanding of the theme's files, you can now override any theme file by creating a similarly named file in your Jekyll site directory. @@ -129,7 +131,7 @@ To do this, copy the files from the theme gem's directory into your Jekyll site Then you must tell Jekyll about the plugins that were referenced by the theme. You can find these plugins in the theme's gemspec file as runtime dependencies. If you were converting the Minima theme, for example, you might see: -``` +```ruby spec.add_runtime_dependency "jekyll-feed", "~> 0.12" spec.add_runtime_dependency "jekyll-seo-tag", "~> 2.6" ``` @@ -191,7 +193,8 @@ To install a gem-based theme: # This is an example, declare the theme gem you want to use here gem "jekyll-theme-minimal" ``` - Or if you've started with the `jekyll new` command, replace `gem "minima", "~> 2.0"` with the gem you want, e.g: + + Or if you've started with the `jekyll new` command, replace `gem "minima", "~> 2.0"` with the gem you want, e.g: ```diff # ./Gemfile @@ -274,7 +277,7 @@ Your theme's stylesheets should be placed in your theme's `_sass` folder, again, ``` _sass -├── jekyll-theme-awesome.scss +└── jekyll-theme-awesome.scss ``` Your theme's styles can be included in the user's stylesheet using the `@import` directive. diff --git a/docs/_docs/troubleshooting.md b/docs/_docs/troubleshooting.md index 31103e51..c1df7c58 100644 --- a/docs/_docs/troubleshooting.md +++ b/docs/_docs/troubleshooting.md @@ -111,7 +111,7 @@ possible to run Jekyll as a non-superuser and without having to install gems to system-wide locations by adding the following lines to the end of your `.bashrc` file: -``` +```bash # Ruby exports export GEM_HOME=$HOME/gems @@ -252,7 +252,7 @@ specified elsewhere. **Note: From v3.3.0 onward, Jekyll does not process `node_modules` and certain subdirectories within `vendor`, by default. But, by having an `exclude:` array defined explicitly in the config file overrides this default setting, which results in some users to encounter an error in building the site, with the following error message:** -```sh +``` ERROR: YOUR SITE COULD NOT BE BUILT: ------------------------------------ Invalid date '<%= Time.now.strftime('%Y-%m-%d %H:%M:%S %z') %>': @@ -262,7 +262,6 @@ specified elsewhere. Adding `vendor/bundle` to the `exclude:` list will solve this problem but will lead to having other sub-directories under `/vendor/` (and also `/node_modules/`, if present) be processed to the destination folder `_site`. - The proper solution is to incorporate the default setting for `exclude:` rather than override it completely: For versions up to `v3.4.3`, the `exclude:` setting must look like following: @@ -281,7 +280,6 @@ exclude: From `v3.5` onward, `Gemfile` and `Gemfile.lock` are also excluded by default. So, in most cases there is no need to define another `exclude:` array in the config file. So an existing definition can either be modified as above, or removed completely, or commented out to enable easy edits in future. - ## Markup Problems The various markup engines that Jekyll uses may have some issues. This @@ -293,7 +291,7 @@ problems. Liquid version 2.0 seems to break the use of `{{ "{{" }}` in templates. Unlike previous versions, using `{{ "{{" }}` in 2.0 triggers the following error: -```sh +``` '{{ "{{" }}' was not properly terminated with regexp: /\}\}/ (Liquid::SyntaxError) ``` diff --git a/docs/_docs/upgrading/0-to-2.md b/docs/_docs/upgrading/0-to-2.md index f3575963..5ea82190 100644 --- a/docs/_docs/upgrading/0-to-2.md +++ b/docs/_docs/upgrading/0-to-2.md @@ -120,13 +120,12 @@ such as previewing locally before pushing to GitHub Pages. Jekyll 1.0 makes that easier with the new `--baseurl` flag. To take advantage of this feature, first add the production `baseurl` to your site's `_config.yml` file. Then, throughout the site, prefix relative URLs -with `{% raw %}{{ site.baseurl }}{% endraw %}`. +with {% raw %}`{{ site.baseurl }}`{% endraw %}. When you're ready to preview your site locally, pass along the `--baseurl` flag with your local baseurl (most likely `/`) to `jekyll serve` and Jekyll will swap in whatever you've passed along, ensuring all your links work as you'd expect in both environments. - <div class="note warning"> <h5 markdown="1">All page and post URLs contain leading slashes</h5> <p markdown="1">If you use the method described above, please remember diff --git a/docs/_docs/upgrading/2-to-3.md b/docs/_docs/upgrading/2-to-3.md index 5f4ef8fb..0c45fe02 100644 --- a/docs/_docs/upgrading/2-to-3.md +++ b/docs/_docs/upgrading/2-to-3.md @@ -36,11 +36,11 @@ When iterating over `site.collections`, ensure the above conversions are made. For `site.collections.myCollection` in Jekyll 2, you now do: -```liquid {% raw %} +```liquid {% assign myCollection = site.collections | where: "label", "myCollection" | first %} -{% endraw %} ``` +{% endraw %} This is a bit cumbersome at first, but is easier than a big `for` loop. @@ -83,7 +83,7 @@ Introducing: `layout`. In Jekyll 2 and below, any metadata in the layout was mer the `page` variable in Liquid. This caused a lot of confusion in the way the data was merged and some unexpected behaviour. In Jekyll 3, all layout data is accessible via `layout` in Liquid. For example, if your layout has `class: my-layout` in its front matter, -then the layout can access that via `{% raw %}{{ layout.class }}{% endraw %}`. +then the layout can access that via {% raw %}`{{ layout.class }}`{% endraw %}. ### Syntax highlighter changed @@ -101,7 +101,7 @@ In Jekyll 3 and above, relative permalinks have been deprecated. If you created your site using Jekyll 2 and below, you may receive the following error when trying to **serve** or **build**: -```text +``` Since v3.0, permalinks for pages in subfolders must be relative to the site source directory, not the parent directory. Check https://jekyllrb.com/docs/upgrading/ for more info. diff --git a/docs/_docs/upgrading/3-to-4.md b/docs/_docs/upgrading/3-to-4.md index 9e9a2f96..c234dfb7 100644 --- a/docs/_docs/upgrading/3-to-4.md +++ b/docs/_docs/upgrading/3-to-4.md @@ -42,7 +42,6 @@ gem update jekyll {% endhighlight %} </div> - ## Template rendering We've slightly altered the way Jekyll parses and renders your various templates @@ -161,6 +160,7 @@ Notes: end end ``` + * Vendors that provide a versioned Jekyll Environment Image (e.g. Docker Image, GitHub Pages, etc) will have to manually whitelist kramdown's extension gems in their distributions for Jekyll 4.0. diff --git a/docs/_posts/2016-10-06-jekyll-3-3-is-here.md b/docs/_posts/2016-10-06-jekyll-3-3-is-here.md index 0d8d7c5c..458f896c 100644 --- a/docs/_posts/2016-10-06-jekyll-3-3-is-here.md +++ b/docs/_posts/2016-10-06-jekyll-3-3-is-here.md @@ -38,31 +38,31 @@ new filters have you covered. When working locally, if you set your then `relative_url` will ensure that this baseurl is prepended to anything you pass it: -{% highlight liquid %} {% raw %} +```liquid {{ "/docs/assets/" | relative_url }} => /myproject/docs/assets +``` {% endraw %} -{% endhighlight %} By default, `baseurl` is set to `""` and therefore yields (never set to `"/"`): -{% highlight liquid %} {% raw %} +```liquid {{ "/docs/assets/" | relative_url }} => /docs/assets +``` {% endraw %} -{% endhighlight %} A result of `relative_url` will safely always produce a URL which is relative to the domain root. A similar principle applies to `absolute_url`. It prepends your `baseurl` and `url` values, making absolute URLs all the easier to make: -{% highlight liquid %} {% raw %} +```liquid {{ "/docs/assets/" | absolute_url }} => https://jekyllrb.com/myproject/docs/assets +``` {% endraw %} -{% endhighlight %} ### 3. `site.url` is set by the development server diff --git a/docs/_posts/2018-01-25-jekyll-3-7-2-released.md b/docs/_posts/2018-01-25-jekyll-3-7-2-released.md index e7c6efa5..04d6bbc6 100644 --- a/docs/_posts/2018-01-25-jekyll-3-7-2-released.md +++ b/docs/_posts/2018-01-25-jekyll-3-7-2-released.md @@ -46,7 +46,7 @@ The highlights being: Ergo, if you set a custom location for your collections, please ensure you move all of your collections into that directory. **This includes posts and drafts as well**. Your links generated by - `{% raw %}{% post_url %}{% endraw %}` or `{% raw %}{% link %}{% endraw %}` + {% raw %}`{% post_url %}`{% endraw %} or {% raw %}`{% link %}`{% endraw %} will adapt automatically. * We also found out that `gem "wdm"` boosts performance while directories are diff --git a/docs/_tutorials/cache_api.md b/docs/_tutorials/cache_api.md index 2690dc16..84a7d047 100644 --- a/docs/_tutorials/cache_api.md +++ b/docs/_tutorials/cache_api.md @@ -64,7 +64,6 @@ is built. This will clear all cached objects from a particular Cache. The Cache will be empty, both in memory and on disk. - ### The following methods will probably only be used in special circumstances ## cache[key] → value diff --git a/docs/_tutorials/convert-existing-site-to-jekyll.md b/docs/_tutorials/convert-existing-site-to-jekyll.md index d84620f1..cbfd8593 100644 --- a/docs/_tutorials/convert-existing-site-to-jekyll.md +++ b/docs/_tutorials/convert-existing-site-to-jekyll.md @@ -19,6 +19,7 @@ First, let's start with a grounding in the basics. Stripping a Jekyll site down We'll start with a *basic Jekyll site* consisting of three files: ``` +. ├── _config.yml ├── _layouts │   └── default.html @@ -28,8 +29,8 @@ We'll start with a *basic Jekyll site* consisting of three files: Manually create these three files in a folder called `my_jekyll_site` or whatever suits you the most, and place `default.html` inside a folder named `_layouts`. ```sh -$ touch _config.yml index.md default.html -$ mkdir _layouts && mv default.html _layouts +touch _config.yml index.md default.html +mkdir _layouts && mv default.html _layouts ``` Fire up your favorite editor, and populate the contents of the `default.html` and `index.md` files as follows: @@ -42,35 +43,42 @@ name: My Jekyll Website **_layouts/default.html** +{% raw %} ```html <!DOCTYPE html> <html> <body> - {% raw %}{{ content }}{% endraw %} + {{ content }} </body> </html> ``` +{% endraw %} **index.md** -```yaml +{% raw %} +```markdown --- title: My page layout: default --- -# {% raw %}{{ page.title }}{% endraw %} +# {{ page.title }} -Content is written in [Markdown](https://learnxinyminutes.com/docs/markdown/). Plain text format allows you to focus on your **content**. +Content is written in [Markdown](https://learnxinyminutes.com/docs/markdown/). +Plain text format allows you to focus on your **content**. <!-- -You can use HTML elements in Markdown, such as the comment element, and they won't be affected by a markdown parser. However, if you create an HTML element in your markdown file, you cannot use markdown syntax within that element's contents. +You can use HTML elements in Markdown, such as the comment element, and they won't +be affected by a markdown parser. However, if you create an HTML element in your +markdown file, you cannot use markdown syntax within that element's contents. --> ``` +{% endraw %} Now `cd` to `my_jekyll_site` and serve the site with the built-in server: -``` +```sh cd my_jekyll_site jekyll serve ``` @@ -84,7 +92,7 @@ This is a Jekyll site at the most basic functional level. Here's what is happeni * The `_config.yml` file contains settings that Jekyll uses as it processes your site. An empty config file will use default values for building a Jekyll site. For example, to convert [Markdown](https://learnxinyminutes.com/docs/markdown/) to HTML, Jekyll will automatically use the [kramdown Markdown filter](https://rubygems.org/gems/kramdown/), without any need to specify it. * Jekyll looks for files with [front matter tags]({% link _docs/front-matter.md %}) (the two sets of dashed lines `---` like those in `index.md`) and processes the files (populating site variables, rendering any [Liquid](https://shopify.github.io/liquid/), and converting Markdown to HTML). - * Jekyll pushes the content from all pages and posts into the `{% raw %}{{ content }}{% endraw %}` variable in the layout specified (`default`) in the front matter tags. + * Jekyll pushes the content from all pages and posts into the {% raw %}`{{ content }}`{% endraw %} variable in the layout specified (`default`) in the front matter tags. * The processed files get written as `.html` files in the `_site` directory. You can read more about how Jekyll processes the files in [order of Interpretation]({% link _tutorials/orderofinterpretation.md %}). @@ -110,21 +118,25 @@ For example, if the paths were relative on the site you copied, you'll need to e Jekyll provides some [filters](/docs/liquid/filters) to prepend a site URL before path. For example, you could preface your stylesheet like this: +{% raw %} ```liquid -{% raw %}{{ "/assets/style.css" | relative_url }}{% endraw %} +{{ "/assets/style.css" | relative_url }} ``` +{% endraw %} -The `relative_url` filter will prepend the [`baseurl`](https://byparker.com/blog/2014/clearing-up-confusion-around-baseurl/) value from your config file (as`blog` for instance) to the input. This is useful if your site is hosted at a subpath rather than at the root of the domain (for example, `http://mysite.com/blog/`). +The `relative_url` filter will prepend the [`baseurl`](https://byparker.com/blog/2014/clearing-up-confusion-around-baseurl/) value from your config file (as `blog` for instance) to the input. This is useful if your site is hosted at a subpath rather than at the root of the domain (for example, `http://mysite.com/blog/`). You can also use an `absolute_url` filter. This filter will prepend the `url` *and* `baseurl` value to the input: +{% raw %} ```liquid -{% raw %}{{ "/assets/style.css" | absolute_url }}{% endraw %} +{{ "/assets/style.css" | absolute_url }} ``` +{% endraw %} Again, both `url` and `baseurl` can be defined in your site's config file, like this: -``` +```yaml url: http://mysite.com baseurl: /blog ``` @@ -141,9 +153,9 @@ In the next section, you'll blank out the content of the layout and replace it w ## 2. Identify the content part of the layout -In `default.html`, find where the page content begins (usually at `h1` or `h2` tags). Replace the title that appears inside these tags with `{% raw %}{{ page.title }}{% endraw %}`. +In `default.html`, find where the page content begins (usually at `h1` or `h2` tags). Replace the title that appears inside these tags with {% raw %}`{{ page.title }}`{% endraw %}. -Remove the content part (keep everything else: navigation menu, sidebar, footer, etc.) and replace it with `{% raw %}{{ content }}{% endraw %}`. +Remove the content part (keep everything else: navigation menu, sidebar, footer, etc.) and replace it with {% raw %}`{{ content }}`{% endraw %}. Check the layout again in your browser and make sure you didn't corrupt or alter it up by inadvertently removing a crucial `div` tag or other element. The only change should be to the title and page content, which are now blanked out or showing the placeholder tag. @@ -153,7 +165,7 @@ Create a couple of files (`index.md` and `about.md`) in your root directory. In your `index.md` file, add some front matter tags containing a `title` and `layout` property, like this: -```yaml +```markdown --- title: Home layout: default @@ -171,13 +183,13 @@ If you don't specify a layout in your pages, Jekyll will simply render that page Add a `_config.yml` file in your root directory. In `_config.yml`, you can optionally specify the markdown filter you want. By default, [kramdown](https://kramdown.gettalong.org/) is used (without the need to specify it). If no other filter is specified, your config file will automatically apply the following as a default setting: -``` +```yaml markdown: kramdown ``` You can also specify [some options](https://kramdown.gettalong.org/converter/html.html) for kramdown to make it behave more like [GitHub Flavored Markdown (GFM)](https://github.github.com/gfm/): -``` +```yaml kramdown: input: GFM auto_ids: true @@ -193,7 +205,7 @@ You've now extracted your content out into separate files and defined a common l You could define any number of layouts you want for pages. Then just identify the layout you want that particular page to use. For example: -``` +```yaml --- title: Sample page layout: homepage @@ -206,7 +218,7 @@ You can even set [default front matter tags](/docs/configuration/front-matter-de ## 6. Configure site variables -You already configured the page title using `{% raw %}{{ page.title }}{% endraw %}` tags. But there are more `title` tags to populate. Pages also have a [`title`](https://moz.com/learn/seo/title-tag) tag that appears in the browser tab or window. Typically you put the page title followed by the site title here. +You already configured the page title using {% raw %}`{{ page.title }}`{% endraw %} tags. But there are more `title` tags to populate. Pages also have a [`title`](https://moz.com/learn/seo/title-tag) tag that appears in the browser tab or window. Typically you put the page title followed by the site title here. In your `default.html` layout, look for the `title` tags below your `head` tags: @@ -216,13 +228,15 @@ In your `default.html` layout, look for the `title` tags below your `head` tags: Insert the following site variables: +{% raw %} +```liquid +<title>{{ page.title }} | {{ site.title }} ``` -{% raw %}{{ page.title }} | {{ site.title }}{% endraw %} -``` +{% endraw %} Open `_config.yml` and add a `title` property for your site's name. -``` +```yaml title: ACME Website ``` @@ -247,7 +261,7 @@ Add some posts in a `_posts` folder following the standard `YYYY-MM-DD-title.md` In each post, add some basic content: -``` +```markdown --- title: My First Post layout: default @@ -258,43 +272,44 @@ Some sample content... Now let's create a layout that will display the posts. Create a new file in `_layouts` called `home.html` and add the following logic: -``` +{% raw %} +```liquid --- layout: default --- -{% raw %}{{ content }} +{{ content }}
      {% for post in site.posts %}
    • {{ post.title}} {{ post.date | date: "%b %-d, %Y" }}
      • {% endfor %} -
    {% endraw %} +
``` +{% endraw %} Create a file called `blog.md` in your root directory and specify the `home` layout: -``` +```yaml --- title: Blog layout: home --- ``` -In this case, contents of `blog.md` will be pushed into the `{% raw %}{{ content }}{% endraw %}` tag in the `home` layout. Then the `home` layout will be pushed into the `{% raw %}{{ content }}{% endraw %}` tag of the `default` layout. - +In this case, contents of `blog.md` will be pushed into the {% raw %}`{{ content }}`{% endraw %} tag in the `home` layout. Then the `home` layout will be pushed into the {% raw %}`{{ content }}`{% endraw %} tag of the `default` layout. ### How layouts work -When a layout specifies another layout, it means the content of the first layout will be stuffed into the `{% raw %}{{ content }}{% endraw %}` tag of the second layout. As an analogy, think of Russian dolls that fit into each other. Each layout fits into another layout that it specifies. +When a layout specifies another layout, it means the content of the first layout will be stuffed into the {% raw %}`{{ content }}`{% endraw %} tag of the second layout. As an analogy, think of Russian dolls that fit into each other. Each layout fits into another layout that it specifies. The following diagram shows how layouts work in Jekyll: Concept of Jekyll layouts {: .image-description} -In this example, the content from a Markdown document `document.md` that specifies `layout: docs` gets pushed into the `{% raw %}{{ content }}{% endraw %}` tag of the layout file `docs.html`. Because the `docs` layout itself specifies `layout: page`, the content from `docs.html` gets pushed into the `{% raw %}{{ content }}{% endraw %}` tag in the layout file `page.html`. Finally because the `page` layout specifies `layout: default`, the content from `page.html` gets pushed into the `{% raw %}{{ content }}{% endraw %}` tag of the layout file `default.html`. +In this example, the content from a Markdown document `document.md` that specifies `layout: docs` gets pushed into the {% raw %}`{{ content }}`{% endraw %} tag of the layout file `docs.html`. Because the `docs` layout itself specifies `layout: page`, the content from `docs.html` gets pushed into the {% raw %}`{{ content }}`{% endraw %} tag in the layout file `page.html`. Finally because the `page` layout specifies `layout: default`, the content from `page.html` gets pushed into the {% raw %}`{{ content }}`{% endraw %} tag of the layout file `default.html`. You don't need multiple layouts. You could just use one: `default`. You have options for how you design your site. In general, it's common to define one layout for pages and another layout for posts, but for both of these layouts to inherit the `default` template (which usually defines the top and bottom parts of the site). @@ -302,7 +317,7 @@ In your browser, go to `blog.html` and see the list of posts. Note that you don't have to use the method described here. You could have simply added the `for` loop to any page, such as `index.md`, to display these posts. But given that you may have more complex logic for other features, it can be helpful to store your logic in templates separate from the page area where you frequently type your content. {: .note .info} -At minimum, a layout should contain `{% raw %}{{ content }}{% endraw %}`, which acts as a receiver for the *content* to be rendered. +At minimum, a layout should contain {% raw %}`{{ content }}`{% endraw %}, which acts as a receiver for the *content* to be rendered. ### For loops @@ -310,15 +325,17 @@ By the way, let's pause here to look at the `for` loop logic a little more close We've only scratched the surface of what you can do with `for` loops in retrieving posts. For example, if you wanted to display posts from a specific category, you could do so by adding a `categories` property to your post's front matter and then look in those categories. Further, you could limit the number of results by adding a `limit` property. Here's an example: +{% raw %} ```liquid -{% raw %}
    +
      {% for post in site.categories.podcasts limit:3 %}
    • {{ post.title}} {{ post.date | date: "%b %-d, %Y" }}
      • {% endfor %} -
    {% endraw %} +
``` +{% endraw %} This loop would get the latest three posts that have a category called `podcasts` in the front matter. @@ -330,18 +347,20 @@ In this tutorial, we'll assume you've got a simple list of pages you want to gen Identify the part of your code where the list of pages appears. Usually this is a `
    ` element with various child `
  • ` elements. Replace the code with the following: -```html -{% raw %}
      +{% raw %} +```liquid +
        {% assign mypages = site.pages | sort: "order" %} {% for page in mypages %}
      • {{ page.title }}
        • {% endfor %} -
      {% endraw %} +
    ``` +{% endraw %} This example assumes each page would have front matter containing both a `title` and `order` property like this: -``` +```yaml --- title: My page order: 2 @@ -372,13 +391,15 @@ You can store additional properties for each item in this data file as desired. To print the list of pages from the data file, use code like this: -```html -{% raw %}
      +{% raw %} +```liquid +{% endraw %} +
    ``` +{% endraw %} If you have more sophisticated requirements around navigation, such as when building a documentation site, see the [detailed tutorial on navigation](/tutorials/navigation/). @@ -392,9 +413,11 @@ Remove your sidebar code from your `default.html` layout and insert it into the Where the sidebar code previously existed in `default.html`, pull in your "include" like this: +{% raw %} ```liquid -{% raw %}{% include sidebar.html %}{% endraw %} +{% include sidebar.html %} ``` +{% endraw %} You can break up other elements of your theme like this, such as your header or footer. Then you can apply these common elements to other layout files. This way you won't have duplicate code. @@ -402,12 +425,13 @@ You can break up other elements of your theme like this, such as your header or Your Jekyll site needs an RSS feed. Here's the [basic RSS feed syntax](http://www.w3schools.com/xml/xml_rss.asp). To create an RSS file in Jekyll, create a file called `feed.xml` in your root directory and add the following: -```xml +{% raw %} +```liquid --- layout: null --- -{% raw %} + @@ -431,8 +455,9 @@ layout: null {% endfor %} -{% endraw %} + ``` +{% endraw %} Make sure your `_config.yml` file has properties for `title`, `url`, and `description`. @@ -440,9 +465,11 @@ This code uses a `for` loop to look through your last 20 posts. The content from In your `default.html` layout, look for a reference to the RSS or Atom feed in your header, and replace it with a reference to the file you just created. For example: -```html - +{% raw %} +```liquid + ``` +{% endraw %} You can also auto-generate your posts feed by adding a gem called [`jekyll-feed`](https://help.github.com/articles/atom-rss-feeds-for-github-pages/). This gem will also work on GitHub Pages. @@ -450,13 +477,14 @@ You can also auto-generate your posts feed by adding a gem called [`jekyll-feed` Finally, add a [site map](https://www.sitemaps.org/protocol.html). Create a `sitemap.xml` file in your root directory and add this code: -```xml +{% raw %} +```liquid --- layout: null search: exclude --- -{% raw %} + {% for page in site.pages %} @@ -477,8 +505,9 @@ search: exclude {% endfor %} -{% endraw %} + ``` +{% endraw %} Again, we're using a `for` loop here to iterate through all posts and pages to add them to the sitemap. @@ -501,7 +530,7 @@ As you integrate code for these services, note that **if a page in your Jekyll s If you do want Jekyll to process some page content (for example, to populate a variable that you define in your site's config file), just add front matter tags to the page. If you don't want any layout applied to the page, specify `layout: null` like this: -``` +```yaml --- layout: null --- diff --git a/docs/_tutorials/custom-404-page.md b/docs/_tutorials/custom-404-page.md index a05aca50..d739735d 100644 --- a/docs/_tutorials/custom-404-page.md +++ b/docs/_tutorials/custom-404-page.md @@ -6,7 +6,6 @@ title: Custom 404 Page You can easily serve custom 404 error pages with Jekyll to replace the default **Error 404 -- File Not Found** page displayed when one tries to access a broken link on your site. - ## On GitHub Pages Any `404.html` at the **root of your `_site` directory** will be served automatically by GitHub Pages and the local WEBrick development server. @@ -48,7 +47,6 @@ Where the path is relative to your site's domain. More info on configuring Apache Error Pages can found in [official documentation](https://httpd.apache.org/docs/current/mod/core.html#errordocument). - ## Hosting on Nginx server The procedure is just as simple as configuring Apache servers, but slightly different. @@ -63,6 +61,7 @@ server { } } ``` + If the `server` block already exists, only add the code inside the `server` block given above. The `location` directive prevents users from directly browsing the 404.html page. diff --git a/docs/_tutorials/index.md b/docs/_tutorials/index.md index e0eacfa6..ec537203 100644 --- a/docs/_tutorials/index.md +++ b/docs/_tutorials/index.md @@ -31,5 +31,3 @@ We welcome your tutorial contributions. To add your tutorial: 6. Follow the regular git workflow to submit the pull request. When you submit your pull request, the Jekyll documentation team will review your contribution and either merge it or suggest edits. - - diff --git a/docs/_tutorials/navigation.md b/docs/_tutorials/navigation.md index 3b5eecb5..7ba036ef 100644 --- a/docs/_tutorials/navigation.md +++ b/docs/_tutorials/navigation.md @@ -371,12 +371,14 @@ For more information, see [Expressions and Variables](https://github.com/Shopify In addition to inserting items from the YAML data file into your list, you also usually want to highlight the current link if the user is viewing that page. You do this by inserting an `active` class for items that match the current page URL. **CSS** + ```css .result li.active a { color: lightgray; cursor: default; - } +} ``` + **Liquid** {% raw %} @@ -408,13 +410,14 @@ In addition to inserting items from the YAML data file into your list, you also In this case, assume `Deployment` is the current page. -To make sure the `item.url` (stored in the YAML file) matches the `page.url`, it can be helpful to print the `{% raw %}{{ page.url }}{% endraw %}` to the page. +To make sure the `item.url` (stored in the YAML file) matches the `page.url`, it can be helpful to print the {% raw %}`{{ page.url }}`{% endraw %} to the page. ## Scenario 7: Including items conditionally You might want to include items conditionally in your list. For example, maybe you have multiple site outputs and only want to include the sidebar item for certain outputs. You can add properties in each list item and then use those properties to conditionally include the content. **YAML** + ```yaml docs2_list_title: ACME Documentation docs2: @@ -588,7 +591,7 @@ Let's walk through the code. First, we assign a variable (`mydocs`) to the colle The `group_by` filter groups the collection content by `category`. More specifically, the `group_by` filter converts `mydocs` into an array with `name`, `items`, and `size` properties, somewhat like this: -```yaml +```json [ {"name": "getting-started", "items": [Sample 1, Sample 2],"size": 2}, {"name": "configuration", "items": [Topic 1, Topic 2], "size": 2}, diff --git a/docs/_tutorials/orderofinterpretation.md b/docs/_tutorials/orderofinterpretation.md index 46cbd802..e5aa4ea6 100644 --- a/docs/_tutorials/orderofinterpretation.md +++ b/docs/_tutorials/orderofinterpretation.md @@ -17,13 +17,13 @@ Jekyll converts your site in the following order: 1. **Site variables**. Jekyll looks across your files and populates [site variables]({% link _docs/variables.md %}), such as `site`, `page`, `post`, and collection objects. (From these objects, Jekyll determines the values for permalinks, tags, categories, and other details.) 2. **Liquid**. Jekyll processes any [Liquid](https://github.com/Shopify/liquid) formatting in pages that contain [front matter]({% link _docs/front-matter.md %}). You can identify Liquid as follows: - * **Liquid tags** start with `{% raw %}{%{% endraw %}` and end with a `{% raw %}%}{% endraw %}`. For example: `{% raw %}{% highlight %}{% endraw %}` or `{% raw %}{% seo %}{% endraw %}`. Tags can define blocks or be inline. Block-defining tags will also come with a corresponding end tag — for example, `{% raw %}{% endhighlight %}{% endraw %}`. - * **Liquid variables** start and end with double curly braces. For example: `{% raw %}{{ site.myvariable }}{% endraw %}` or `{% raw %}{{ content }}{% endraw %}`. - * **Liquid filters** start with a pipe character (`|`) and can only be used within **Liquid variables** after the variable string. For example: the `relative_url` filter in `{% raw %}{{ "css/main.css" | relative_url }}{% endraw %}`. + * **Liquid tags** start with {% raw %}`{%`{% endraw %} and end with a {% raw %}`%}`{% endraw %}. For example: {% raw %}`{% highlight %}`{% endraw %} or {% raw %}`{% seo %}`{% endraw %}. Tags can define blocks or be inline. Block-defining tags will also come with a corresponding end tag — for example, {% raw %}`{% endhighlight %}`{% endraw %}. + * **Liquid variables** start and end with double curly braces. For example: {% raw %}`{{ site.myvariable }}`{% endraw %} or {% raw %}`{{ content }}`{% endraw %}. + * **Liquid filters** start with a pipe character (`|`) and can only be used within **Liquid variables** after the variable string. For example: the `relative_url` filter in {% raw %}`{{ "css/main.css" | relative_url }}`{% endraw %}. 3. **Markdown**. Jekyll converts Markdown to HTML using the Markdown filter specified in your config file. Files must have a Markdown file extension and front matter in order for Jekyll to convert them. -4. **Layout**. Jekyll pushes content into the layouts specified by the page's front matter (or as specified in the config file). The content from each page gets pushed into the `{% raw %}{{ content }}{% endraw %}` tags within the layouts. +4. **Layout**. Jekyll pushes content into the layouts specified by the page's front matter (or as specified in the config file). The content from each page gets pushed into the {% raw %}`{{ content }}`{% endraw %} tags within the layouts. 5. **Files**. Jekyll writes the generated content into files in the [directory structure]({% link _docs/structure.md %}) in `_site`. Pages, posts, and collections get structured based on their [permalink]({% link _docs/permalinks.md %}) setting. Directories that begin with `_` (such as `_includes` and `_data`) are usually hidden in the output. @@ -115,7 +115,7 @@ This won't work because the `assign` tag is only available during the Liquid ren 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 +```javascript

    @@ -129,7 +129,7 @@ function someFunction() { ``` {% endraw %} -When Jekyll builds the site, this `someContent` property populates the script's values, converting `{% raw %}{{ page.someContent }}{% endraw %}` to `"This is some content"`. +When Jekyll builds the site, this `someContent` property populates the script's values, converting {% raw %}`{{ page.someContent }}`{% endraw %} to `"This is some content"`. The key to remember is that Liquid renders when Jekyll builds your site. Liquid is not available at run-time in the browser when a user executes an event. diff --git a/docs/_tutorials/using-jekyll-with-bundler.md b/docs/_tutorials/using-jekyll-with-bundler.md index 0acbad28..069602e2 100644 --- a/docs/_tutorials/using-jekyll-with-bundler.md +++ b/docs/_tutorials/using-jekyll-with-bundler.md @@ -105,4 +105,3 @@ _site/ .bundle/ vendor/ ``` - diff --git a/docs/_tutorials/video-walkthroughs.md b/docs/_tutorials/video-walkthroughs.md index c673434a..635b883f 100644 --- a/docs/_tutorials/video-walkthroughs.md +++ b/docs/_tutorials/video-walkthroughs.md @@ -31,5 +31,3 @@ title: Video Walkthroughs 17. [Data Files](https://www.youtube.com/watch?v=M6b0KmLB-pM&list=PLLAZ4kZ9dFpOPV5C5Ay0pHaa0RJFhcmcB&index=17) 18. [Static Files](https://www.youtube.com/watch?v=knWjmVlVpso&index=18&list=PLLAZ4kZ9dFpOPV5C5Ay0pHaa0RJFhcmcB) 19. [Hosting on Github Pages](https://www.youtube.com/watch?v=fqFjuX4VZmU&list=PLLAZ4kZ9dFpOPV5C5Ay0pHaa0RJFhcmcB&index=19) - -