Skip to content

Variables

Jump to bottom
Dmitry Shevtsov edited this page Aug 24, 2021 · 3 revisions

We use Jekyll variables at the Magento Docs projects based on Jekyll.

There are three scopes of variables available:

  • global
  • page
  • local

Each variable is available using Liquid syntax for variables {{ }} and an object to get the variable from. For example, for the baseurl value of the site object, it is {{ site.baseurl }}.

Global

There are two objects available globally that we use for variables:

  • site
  • data

Site

Through the site object, you can get any key from the site's configuration, defined in _config.yml.

The most commonly used are:

  • {{ site.baseurl }} which returns value of the baseurl key of the _config.yml file. Typically, it is used for links to HTML pages of versionless topics. Example: {{ site.baseurl }}/cloud/bk-cloud.html. For more technical details, see Clearing Up Confusion Around baseurl -- Again.
  • {{ site.downloads }} which returns value of the downloads key of the _config.yml file. It points to the folder with downloadable files, which is not part of this repository. Example: {{ site.downloads }}/magento-commerce-cloud-prelaunch-checklist.pdf
  • {{ site.mage2bloburl }} which returns value of the mage2bloburl key of the _config.yml file. It contains starting part of a URL to blob of the magento2 repository. Use it when you want to add a link to code file from the magento2 repository. Examples:
    • in a versionless topic, to point to the latest released version of the code: {{ site.mage2bloburl }}/{{ site.version }}/auth.json.sample
    • in a versionless topic, to point to a specific version of the code: {{ site.mage2bloburl }}/2.3/auth.json.sample
    • in a versioned topic: {{ site.mage2bloburl }}/{{ page.guide_version }}/auth.json.sample
  • {{ site.gdeurl }} which returns value of the gdeurl key of the _config.yml file. It is used to reference versioned topics of the lates version from versionless pages.
  • {{ site.version }} which returns value of the version key of the _config.yml file. It contains the latest released minor version.

NOTE Versioned topics are topics, located at the guides directory and put under a particular version. All other topics are considered versionless.

Data

The data list is available via {{ site.data }}. It allows accessing the data stored in the src/_data directory. We use this data to generate tables or big chunks of content, as well as any other global data that does not relate to the site's configuration.

For example, the {{ site.data.var.ee }} value returns the ee key of the src/_data/var.yml file

See Data Files.

Page

Every topic is a page object. Page parameters can be assigned in different ways:

  • Default parameters are natively defined by Jekyll. Examples: {{ page.path }}, {{ page.content }}, {{ page.url }}. Default parameters can be overridden by plugins.
  • Custom parameters can be added to multiple pages using plugins. Examples: {{ page.github_path }}, {{ page.last_modified_at }}, {{ page.baseurl }}
  • Custom parameters can be added to multiple pages using defaults in the _config.yml. Examples: {{ page.guide_version }}, {{ page.github_repo }}
  • Custom parameters can be added to a single page using front matter. Examples: {{ page.title }}, {{ page.group }}. A value from front matter has the highest priority over above types of assignments.

Versionless and versioned pages

Versionless

Versionless are pages that do not contain a guide version in source path.

Example: src/cloud/bk-cloud.md. Page URL: https://devdocs.magento.com/cloud/bk-cloud.html

Versioned

Versioned are pages that include a guide version in path.

Example of 2.4 source page: src/guides/v2.4/install-gde/install-flow-diagram.md. Page URL: https://devdocs.magento.com/guides/v2.4/install-gde/install-flow-diagram.html

Example of 2.3 source page: src/guides/v2.3/install-gde/install-flow-diagram.md. Page URL: https://devdocs.magento.com/guides/v2.3/install-gde/install-flow-diagram.html

Different types of pages can link between each other. Depending on a source page and a destination page of the link, it will require different variables.

Linking from any page to versionless page

TIP: Replace https://devdocs.magento.com with {{ site.baseurl }}

Example 1. Linking from src/guides/v2.4/install-gde/install-flow-diagram.md to https://devdocs.magento.com/cloud/bk-cloud.html:

{{ site.baseurl }}/cloud/bk-cloud.html

Example 2. Linking from src/cloud/bk-cloud.md to https://devdocs.magento.com/cloud/architecture/cloud-architecture.html:

{{ site.baseurl }}/cloud/architecture/cloud-architecture.html

Linking from a versioned page to a versioned page

Example 1. Linking from src/guides/v2.4/install-gde/install-flow-diagram.md to https://devdocs.magento.com/guides/v2.4/install-gde/system-requirements.html:

{{ page.baseurl }}/install-gde/system-requirements.html

It will be automatically converted to appropriate version when converted to HTML. In 2.4 topic, to https://devdocs.magento.com/guides/v2.4/install-gde/system-requirements.html; in 2.3 topic, to https://devdocs.magento.com/guides/v2.3/install-gde/system-requirements.html; etc.

Example 2. Linking from src/guides/v2.4/install-gde/install-flow-diagram.md to https://devdocs.magento.com/guides/v2.3/install-gde/system-requirements.html:

{{ site.baseurl }}/guides/v2.3/install-gde/system-requirements.html

Use version explicitly when linking between different versions.

Linking from a versionless page to a versioned page

Example 1. Linking from src/cloud/architecture/cloud-architecture.md to https://devdocs.magento.com/guides/v2.4/install-gde/install-flow-diagram.html (latest):

{{ site.baseurl }}{{ site.gdeurl }}/install-gde/install-flow-diagram.html

This will always link to a latest version of .../install-gde/install-flow-diagram.html.

Example 2. Linking from src/cloud/architecture/cloud-architecture.md to https://devdocs.magento.com/guides/v2.3/install-gde/install-flow-diagram.html (not latest):

{{ site.baseurl }}/guides/v2.3/install-gde/install-flow-diagram.html

Local

A topic can have simple Liquid variables. For example, to avoid typing {{ site.data.var.ee }} when you have to use it multiple time in your topic, you can use a Liquid variable for this:

{% assign ce = site.data.var.ee %}

and refer to it as {{ce}}.

Good to know

search_only_key

Reference: {{ site.algolia.search_only_key }}

This key corresponds to the Search-only API key in Algolia. It is safe to use in production front-end code. We use at every page using a layout src/_includes/layout/header-scripts.html. Technically, it is possible to move it to the devdocs-theme, but this would require to move the entire block of parameters for algolia, because Jekyll configuration parameters are merged by overwriting, not by combining.

Contribution Guide

Projects

Builds

Documentation

Templates

Clone this wiki locally