docs: improvements for note boxes (#8037)

Merge pull request 8037
This commit is contained in:
Eric Knibbe 2020-02-28 14:29:47 -05:00 committed by GitHub
parent 53bb8bd7d3
commit b05e6ee8ae
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
27 changed files with 90 additions and 81 deletions

View File

@ -25,9 +25,11 @@ collections:
people: true
```
<div class="note">
<p>When defining a collection as a sequence, its pages will not be rendered by default. To enable this, <code>output: true</code> must be specified on the collection, which requires defining the collection as a mapping. For more information, see the section <a href="#output">Output</a></p>
</div>
{: .note .info}
When defining a collection as a sequence, its pages will not be rendered by
default. To enable this, <code>output: true</code> must be specified on the
collection, which requires defining the collection as a mapping. For more
information, see the section <a href="#output">Output</a>.
<div class="note">
<h5>Gather your collections {%- include docs_version_badge.html version="3.7.0" -%}</h5>

View File

@ -42,8 +42,8 @@ environment but not include it in production environments.
By specifying the option in the build command, you avoid having to change
values in your configuration files when moving from one environment to another.
<div class="note info">
<p>
To switch part of your config settings depending on the environment, use the <a href="/docs/configuration/options/#build-command-options">build command option</a>, for example <code>--config _config.yml,_config_development.yml</code>. Settings in later files override settings in earlier files.
</p>
</div>
{: .note}
To switch part of your config settings depending on the environment, use the
<a href="/docs/configuration/options/#build-command-options">build command option</a>,
for example <code>--config _config.yml,_config_development.yml</code>. Settings
in later files override settings in earlier files.

View File

@ -104,9 +104,9 @@ To check that your gem paths point to your home directory run:
gem env
```
And check that `GEM PATHS:` points to a path in your home directory
And check that `GEM PATHS:` points to a path in your home directory.
{: .note }
{: .note .info}
Every time you update Ruby to a version with a different first two digits, you will need to update your path to match.
### Global Install

View File

@ -35,7 +35,8 @@ That's it, you're ready to use Jekyll!
If you are using Windows 10 version 1607 or later, another option to run Jekyll is by
[installing](https://msdn.microsoft.com/en-us/commandline/wsl/install_guide) the Windows Subsystem for Linux.
*Note:* You must have [Windows Subsystem for Linux](https://msdn.microsoft.com/en-us/commandline/wsl/about) enabled.
{: .note .info}
You must have [Windows Subsystem for Linux](https://msdn.microsoft.com/en-us/commandline/wsl/about) enabled.
First let's make sure all our packages / repositories are up to date. Open a new Command Prompt instance, and type the following:
@ -89,7 +90,8 @@ with the current date in the filename.
the "Running Jekyll as Non-Superuser" instructions in <a href="/docs/troubleshooting/#no-sudo">Troubleshooting</a>.</p>
</div>
**Note:** Bash on Ubuntu on Windows is still under development, so you may run into issues.
{: .note .info}
Bash on Ubuntu on Windows is still under development, so you may run into issues.
## Encoding
@ -125,11 +127,11 @@ gem 'tzinfo-data', platforms: [:mingw, :mswin, :x64_mingw, :jruby]
<div class="note warning">
<h5>TZInfo 2.0 incompatibility</h5>
<p>
<code>v2.0</code> of the TZInfo library has introduced a change in how timezone offsets are calculated.
Version 2.0 of the TZInfo library has introduced a change in how timezone offsets are calculated.
This will result in incorrect date and time for your posts when the site is built with Jekyll 3.x on Windows.
</p>
<p>
We therefore recommend that you lock the Timezone library to <code>v1.2</code> and above by listing
We therefore recommend that you lock the Timezone library to version 1.2 and above by listing
<code>gem 'tzinfo', '~> 1.2'</code> in your <code>Gemfile</code>.
</p>
</div>

View File

@ -18,12 +18,11 @@ Jekyll has built in support for syntax highlighting of over 100 languages
thanks to [Rouge](http://rouge.jneen.net). Rouge is the default highlighter
in Jekyll 3 and above.
<div class="note warning">
<p>Using Pygments has been deprecated and is not supported in
Jekyll 4, the configuration setting <code>highlighter: pygments</code>
now automatically falls back to using <em>Rouge</em> which is written in Ruby
and 100% compatible with stylesheets for Pygments.</p>
</div>
{: .note .warning}
Using Pygments has been deprecated and is not supported in
Jekyll 4; the configuration setting <code>highlighter: pygments</code>
now automatically falls back to using <em>Rouge</em> which is written in Ruby
and 100% compatible with stylesheets for Pygments.
To render a code block with syntax highlighting, surround your code as follows:
@ -47,7 +46,7 @@ wiki](https://github.com/jayferd/rouge/wiki/List-of-supported-languages-and-lexe
<p>If you are using a language that contains curly braces, you
will likely need to place <code>{&#37; raw &#37;}</code> and
<code>{&#37; endraw &#37;}</code> tags around your code.
Since {% include docs_version_badge.html version="4.0" %} you can add <code>render_with_liquid: false</code> in your front matter to disable Liquid entirely for a particular document.</p>
Since Jekyll {% include docs_version_badge.html version="4.0" %}, you can add <code>render_with_liquid: false</code> in your front matter to disable Liquid entirely for a particular document.</p>
</div>
### Line numbers
@ -84,8 +83,8 @@ the syntax highlighter styles into your `main.css`:
## Links
{: .note }
Since Jekyll {% include docs_version_badge.html version="v4.0"%} you don't need to prepend `link` and `post_url` tags with `site.baseurl`
{: .note}
Since Jekyll {% include docs_version_badge.html version="4.0"%}, you don't need to prepend `link` and `post_url` tags with `site.baseurl`.
### Linking to pages {#link}

View File

@ -3,7 +3,7 @@ title: Affinity Team Captains
---
**This guide is for affinity team captains.** These special people are **team maintainers** of one of our [affinity teams][] and help triage and evaluate the issues and contributions of others. You may find what is written here interesting, but its definitely not for everyone.
{: .note .info }
{: .note .info}
## Affinity teams & their captains

View File

@ -3,7 +3,7 @@ title: "Avoiding Burnout"
---
**This guide is for maintainers.** These special people have **write access** to one or more of Jekyll's repositories and help merge the contributions of others. You may find what is written here interesting, but its definitely not for everyone.
{: .note .info }
{: .note .info}
# 1. Use Jekyll

View File

@ -3,7 +3,7 @@ title: "Becoming a Maintainer"
---
**This guide is for contributors.** These special people have contributed to one or more of Jekyll's repositories, but do not yet have write access to any. You may find what is written here interesting, but its definitely not for everyone.
{: .note .info }
{: .note .info}
So you want to become a maintainer of a Jekyll project? We'd love to have you! Here are some things we like to see from community members before we promote them to maintainers.

View File

@ -4,7 +4,7 @@ permalink: /docs/maintaining/
---
**This guide is for Jekyll contributors and maintainers.** These special people contribute to one or more of Jekyll's repositories or help merge the contributions of others. You may find what is written here interesting, but its definitely not for everyone.
{: .note .info }
{: .note .info}
Hello! This is where we document various processes for maintaining Jekyll. Being a maintainer for any Jekyll project is a big responsibility, so we put together some helpful documentation for various tasks you might do as a maintainer.

View File

@ -3,7 +3,7 @@ title: "Merging a Pull Request"
---
**This guide is for maintainers.** These special people have **write access** to one or more of Jekyll's repositories and help merge the contributions of others. You may find what is written here interesting, but its definitely not for everyone.
{: .note .info }
{: .note .info}
## Code Review

View File

@ -3,7 +3,7 @@ title: "Releasing a new version"
---
**This guide is for maintainers.** These special people have **write access** to one or more of Jekyll's repositories and help merge the contributions of others. You may find what is written here interesting, but its definitely not for everyone.
{: .note .info }
{: .note .info}
The most important thing to understand before making a release is that there's no need to feel nervous. Most things are revertable, and even if you do publish an incomplete gem version, we can always skip that one. Don't hestitate to contact the other maintainers if you feel unsure or don't know what to do next.

View File

@ -3,7 +3,7 @@ title: "Reviewing a Pull Request"
---
**This guide is for maintainers.** These special people have **write access** to one or more of Jekyll's repositories and help merge the contributions of others. You may find what is written here interesting, but its definitely not for everyone.
{: .note .info }
{: .note .info}
## Respond Kindly

View File

@ -3,7 +3,7 @@ title: "Special Labels"
---
**This guide is for maintainers.** These special people have **write access** to one or more of Jekyll's repositories and help merge the contributions of others. You may find what is written here interesting, but its definitely not for everyone.
{: .note .info }
{: .note .info}
We use a series of "special labels" on GitHub.com to automate handling of some parts of the pull request and issue process. @jekyllbot may automatically apply or remove certain labels based on actions taken by users or maintainers. Below are the labels and how they work:

View File

@ -3,7 +3,7 @@ title: "Triaging an Issue"
---
**This guide is for maintainers.** These special people have **write access** to one or more of Jekyll's repositories and help merge the contributions of others. You may find what is written here interesting, but its definitely not for everyone.
{: .note .info }
{: .note .info}
Before evaluating an issue, it is important to identify if it is a feature
request or a bug. For the Jekyll project the following definitions are used

View File

@ -15,8 +15,8 @@ and associated URLs might look like:
```
.
|-- about.md # => http://example.com/about.html
|-- index.html # => http://example.com/
├── about.md # => http://example.com/about.html
├── index.html # => http://example.com/
└── contact.html # => http://example.com/contact.html
```
@ -24,11 +24,11 @@ If you have a lot of pages, you can organize them into subfolders. The same subf
```
.
|-- about.md # => http://example.com/about.html
|-- documentation # folder containing pages
└── doc1.md # => http://example.com/documentation/doc1.html
|-- design # folder containing pages
└── draft.md # => http://example.com/design/draft.html
├── about.md # => http://example.com/about.html
├── documentation # folder containing pages
└── doc1.md # => http://example.com/documentation/doc1.html
├── design # folder containing pages
└── draft.md # => http://example.com/design/draft.html
```
## Changing the output URL

View File

@ -2,7 +2,7 @@
title: Commands
permalink: /docs/plugins/commands/
---
As of version 2.5.0, Jekyll can be extended with plugins which provide
As of version {% include docs_version_badge.html version="2.5.0"%}, Jekyll can be extended with plugins which provide
subcommands for the `jekyll` executable. This is possible by including the
relevant plugins in a `Gemfile` group called `:jekyll_plugins`:

View File

@ -52,7 +52,7 @@ You have 3 options for installing plugins:
</p>
</div>
<div class="note info">
<div class="note">
<h5>
<code>_plugins</code>, <code>_config.yml</code> and <code>Gemfile</code>
can be used simultaneously
@ -73,10 +73,7 @@ processing the rest of your source directory.
A gem included here will be activated even if its not explicitly listed under
the `plugins:` key in your site's config file.
<div class="note warning">
<p>
Gems included in the <code>:jekyll-plugins</code> group are activated
regardless of the <code>--safe</code> mode setting. Be aware of what
gems are included under this group!
</p>
</div>
{: .note .warning}
Gems included in the <code>:jekyll-plugins</code> group are activated
regardless of the <code>--safe</code> mode setting. Be aware of which
gems are included under this group!

View File

@ -107,9 +107,8 @@ And we would still get the same output as above on the page:
<p>page rendered at: Tue June 22 23:38:47 0500 2010</p>
```
<div class="note info">
<p>In the above example, the tag block and the tag are both registered with
the name <code>render_time</code> 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.</p>
</div>
{: .note .info}
In the above example, the tag block and the tag are both registered with
the name <code>render_time</code>, 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.

View File

@ -200,7 +200,7 @@ create a `_drafts` folder in your site's root and create your first draft:
```
.
├── _drafts
| └── a-draft-post.md
└── a-draft-post.md
...
```

View File

@ -11,9 +11,9 @@ Jekyll sites often use this structure to keep assets organized:
```
.
├── assets
| ├── css
| ├── images
| └── js
├── css
├── images
└── js
...
```

View File

@ -8,31 +8,31 @@ A basic Jekyll site usually looks something like this:
.
├── _config.yml
├── _data
| └── members.yml
└── members.yml
├── _drafts
| ├── begin-with-the-crazy-ideas.md
| └── on-simplicity-in-technology.md
├── begin-with-the-crazy-ideas.md
└── on-simplicity-in-technology.md
├── _includes
| ├── footer.html
| └── header.html
├── footer.html
└── header.html
├── _layouts
| ├── default.html
| └── post.html
├── default.html
└── post.html
├── _posts
| ├── 2007-10-29-why-every-programmer-should-play-nethack.md
| └── 2009-04-26-barcamp-boston-4-roundup.md
├── 2007-10-29-why-every-programmer-should-play-nethack.md
└── 2009-04-26-barcamp-boston-4-roundup.md
├── _sass
| ├── _base.scss
| └── _layout.scss
├── _base.scss
└── _layout.scss
├── _site
├── .jekyll-metadata
└── index.html # can also be an 'index.md' with valid front matter
```
<div class="note info">
<div class="note">
<h5>Directory structure of Jekyll sites using gem-based themes</h5>
<p>
Starting <strong>Jekyll 3.2</strong>, a new Jekyll project bootstrapped with <code>jekyll new</code> uses <a href="/docs/themes/">gem-based themes</a> to define the look of the site. This results in a lighter default directory structure : <code>_layouts</code>, <code>_includes</code> and <code>_sass</code> are stored in the theme-gem, by default.
Since version {% include docs_version_badge.html version="3.2"%}, a new Jekyll project bootstrapped with <code>jekyll new</code> uses <a href="/docs/themes/">gem-based themes</a> to define the look of the site. This results in a lighter default directory structure: <code>_layouts</code>, <code>_includes</code> and <code>_sass</code> are stored in the theme-gem, by default.
</p>
<br />
<p>

View File

@ -120,8 +120,8 @@ Jekyll will look first to your site's content before looking to the theme's defa
Note that making copies of theme files will prevent you from receiving any theme updates on those files. An alternative, to continue getting theme updates on all stylesheets, is to use higher specificity CSS selectors in your own additional, originally named CSS files.
Refer to your selected theme's documentation and source repository for more information on what files you can override.
{: .note .info}
Refer to your selected theme's documentation and source repository for more information on which files you can override.
## Converting gem-based themes to regular themes
@ -221,8 +221,8 @@ To install a gem-based theme:
bundle exec jekyll serve
```
{: .note .info}
You can have multiple themes listed in your site's `Gemfile`, but only one theme can be selected in your site's `_config.yml`.
{: .note .info }
If you're publishing your Jekyll site on [GitHub Pages](https://pages.github.com/), note that GitHub Pages supports only [some gem-based themes](https://pages.github.com/themes/). GitHub Pages also supports [using any theme hosted on GitHub](https://help.github.com/articles/adding-a-jekyll-theme-to-your-github-pages-site/#adding-a-jekyll-theme-in-your-sites-_configyml-file) using the `remote_theme` configuration as if it were a gem-based theme.
@ -320,8 +320,8 @@ Themes are visual. Show users what your theme looks like by including a screensh
To preview your theme as you're authoring it, it may be helpful to add dummy content in, for example, `/index.html` and `/page.html` files. This will allow you to use the `jekyll build` and `jekyll serve` commands to preview your theme, just as you'd preview a Jekyll site.
{: .note .info}
If you do preview your theme locally, be sure to add `/_site` to your theme's `.gitignore` file to prevent the compiled site from also being included when you distribute your theme.
{: .info .note}
### Publishing your theme

View File

@ -12,8 +12,8 @@ Before we dive in, go ahead and fetch the latest version of Jekyll:
gem update jekyll
```
Since v3.2 Jekyll requires Ruby version >= 2.1
{: .note .warning }
{: .note .warning}
Since version {% include docs_version_badge.html version="3.2"%}, Jekyll requires Ruby version >= 2.1.
<div class="note feature">
<h5>Diving in</h5>

View File

@ -991,6 +991,16 @@ code.output {
}
}
p.note {
color: #fff;
font-weight: 400;
font-size: .75em;
&:after {
line-height: 1.21;
}
}
.info {
background-color: #0389aa;
background-image: url(data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiA/Pgo8c3ZnIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgd2lkdGg9IjEwMCUiIGhlaWdodD0iMTAwJSIgdmlld0JveD0iMCAwIDEgMSIgcHJlc2VydmVBc3BlY3RSYXRpbz0ibm9uZSI+CiAgPGxpbmVhckdyYWRpZW50IGlkPSJncmFkLXVjZ2ctZ2VuZXJhdGVkIiBncmFkaWVudFVuaXRzPSJ1c2VyU3BhY2VPblVzZSIgeDE9IjAlIiB5MT0iMCUiIHgyPSIwJSIgeTI9IjEwMCUiPgogICAgPHN0b3Agb2Zmc2V0PSIwJSIgc3RvcC1jb2xvcj0iIzAzODlhYSIgc3RvcC1vcGFjaXR5PSIxIi8+CiAgICA8c3RvcCBvZmZzZXQ9IjEwMCUiIHN0b3AtY29sb3I9IiMwMDYxN2YiIHN0b3Atb3BhY2l0eT0iMSIvPgogIDwvbGluZWFyR3JhZGllbnQ+CiAgPHJlY3QgeD0iMCIgeT0iMCIgd2lkdGg9IjEiIGhlaWdodD0iMSIgZmlsbD0idXJsKCNncmFkLXVjZ2ctZ2VuZXJhdGVkKSIgLz4KPC9zdmc+);

View File

@ -83,8 +83,8 @@ cd my_jekyll_site
jekyll serve
```
If you have a Gemfile, [use Bundler](/docs/ruby-101/#bundler) by typing `bundle exec jekyll serve` instead.
{: .note .info}
If you have a Gemfile, [use Bundler](/docs/ruby-101/#bundler) by typing `bundle exec jekyll serve` instead.
When you serve the site, you get a preview URL such as `http://127.0.0.1:4000/` (which is the same as `http://localhost:4000/`). The site's files are built into the `_site` folder by default.

View File

@ -15,8 +15,8 @@ In contrast to [Docs](/docs/home/), Tutorials provide more detailed, narrative i
In short, tutorials aren't the core reference information in docs. They walk users through processes from beginning to end.
{: .info .note}
**Note:** The Tutorials section is new, so there aren't many tutorials yet. You can add a tutorial here to help populate this section.
{: .note .info}
The Tutorials section is new, so there aren't many tutorials yet. You can add a tutorial here to help populate this section.
Some of these techniques might even guide you through a supporting tool, script, service, or other hack used with your Jekyll site. Feel free to include tutorials involving external services with Jekyll as well. However, note that Jekyll in no way endorses any third-party tools mentioned in tutorials.

View File

@ -69,8 +69,8 @@ docs:
</ul>
</div>
{: .note .info }
For the results in these fictitious samples, `#` is manually substituted for the actual link value to avoid 404 errors.)
{: .note .info}
For the results in these fictitious samples, `#` is manually substituted for the actual link value (to avoid 404 errors.)
When you use a `for` loop, you choose how you want to refer to the items you're looping through. The variable you choose (in this case, `item`) becomes how you access the properties of each item in the list. Dot notation is used to get a property of the item (for example, `item.url`).