このページは、まだ日本語ではご利用いただけません。翻訳中です。
Reusable content
In Jekyll, reusable content is managed using include
snippets, which are located in the /app/_includes
folder. Use includes
to reuse snippets of the same content across multiple
pages.
The examples in this topic reference a short include
file with a snippet about installation.
Snippets from that include
file are called with an include
tag in a few
target files, such as the
Docker installation guide.
Create an include
File formats and directories
Add a Markdown (.md
) or HTML (.html
) file to the /app/_includes
directory at the root of the Kong/docs.konghq.com
repository.
- Markdown
includes
contain snippets of documentation content, for example, common installation steps. - HTML
includes
contain pieces of website layout and functionality, for example, the footer and top navigation bar.
If your Markdown include
does not need to belong to a particular product version, place it in a product directory. For example:
app/_includes/mesh
app/_includes/plugins-hub
If the include
will be used across products, place it directly in of the
app/_includes/md/
directory.
If you have different versions of the
include
content:
- Content for current version continues to live at the root of the product directory
- Versioned content (for non-current versions only!) lives in a sub-directory named {VERSION_NUMBER}
Markdown comments
At the top of an include
file, add a Markdown comment to note the instances
where this include
is being used. For example:
<!-- Shared between all Community Linux installation topics: Amazon Linux,
CentOS, Debian, RedHat, and Ubuntu -->
Page variables
If using page variables inside an include
, replace page
in the variable with
include
. For example, page.release
becomes include.release
.
This is an include that uses {{ include.release }}.
This is necessary because we use the jekyll_include_cache
plugin on the docs
site, and the plugin needs to know that the variable should not be cached.
Use an include
To add an include
, use the include
tag with the following basic syntax:
{% include_cached /md/install.md %}
- Declare the tag with
include_cached
- Add a path relative to the
_includes
directory
Depending on the content of the snippet, you can pass various parameters to the include
tag. If the include
content has a variable anywhere in the text, map it to the page variable:
{% include_cached /md/install.md release=page.release %}
This maps page.release
to the include.release
from the source include file.
Conditional content
You can add if
statements to an include
to create
variations of the content for use in different contexts. For example, in an
file named install.md
, you might have a snippet where the instructions are
specific to Docker:
{% if include.install == "docker" %}
your docker content goes here
{% endif %}
In the target file (the file where you want the content to display), call the
Docker section of the include
:
{% include_cached /md/install.md install='docker' %}
The syntax for the if statement and the
include
is not the same.
- When creating an if statement condition based on a string, the string must be enclosed in double quotes (
" "
) and use two equals signs:if include.install == "docker"
- When calling the section in an
include_cached
tag, use single quotes (' '
) and one equals sign:install='docker'
include-check script
The Kong docs site runs an include
check script on every change pushed to the repository. If you run into issues with an include
, the check will flag them. See more info about the include
check in our repository README.