Liquid Includes

GitHub Pages content is processed by Jekyll, which allows both parameterized file inclusion and the use of the liquid templating language. By combining these two features, macro-like functionality is possible.

Each section on this page illustrates liquid syntax that can be used to invoke macros provided by the programming pages theme.

• collapsible_example.liquid
• icon.liquid
• log.liquid
• ordered_child_list.liquid
• package_shortener.liquid
• page_root.liquid
• render_indices.liquid

collapsible_example.liquid

embeds a collapsed example that the user can expand if interested.

markdown

{% include collapsible_example.liquid file='snippets/hello_world.cpp' %}

result

/*
Hello World

  To compile and run this program:

  1. Save the code in a file with name "hello_world.cpp"
  2. Execute the following command in a terminal window:

    $ g++ -o /tmp/hello_world hello_world.cpp

      ..which invokes the Gnu C++ compiler, asking it to output
      an executable file into /tmp with name "hello_world".

  3. Execute the following command in a terminal window:

    $ /tmp/hello_world

      ..which will then run the program, causing the message
      "Hello World!" to be written to the terminal.
*/

#include <iostream>

int main()
{
   std::cout << "Hello World!" << std::endl;

   return 0;
}

icon.liquid

inserts SVG code for an icon. SVG icons are defined in _data/icons/theme.yml by the theme. See the markdown sampler for a list of icon ids.

Tip
Users may also define icons of their own, by adding additional icon data files under _data/icons/. See the source comments for more details.

markdown

{% include icon.liquid id='star' %}

result

log.liquid

generates a javascript function that logs information to the console.
the function is submitted to jQuery’s document ready function ($()).

markdown

{% include log.liquid msg='[programming-pages] hello, console' %}
{% include log.liquid msg='[programming-pages] warning, console' lvl='warn' %}
{% assign log_k = '' | split: '' %}
{% assign log_v = '' | split: '' %}
{% assign log_k = log_k | push: 'key 1' %}{% assign log_v = log_v | push: 'value one' %}
{% assign log_k = log_k | push: 'key 2' %}{% assign log_v = log_v | push: 'value two' %}
{% assign log_k = log_k | push: 'key 3' %}{% assign log_v = log_v | push: 'value three' %}
{% include log.liquid msg='[programming-pages] key/value pairs to table' keys=log_k values=log_v %}
(open the browser's javascript console to see the examples)

result

ordered_child_list.liquid

generates an html list of child pages, respecting their page.order value.
only first-level children are listed, grandchildren and beyond are ignored. order: 0 is first, -1 is last, undefined orders go in the middle alphabetically

markdown

{% include ordered_child_list.liquid docs=site.examples %}

result

package_shortener.liquid

abbreviates intermediary package names to their first letter:
foo.bar.bat.Baz → foo.b.b.Baz

markdown

{% assign packages = "foo.bar.bat, foo.bar.bat.Baz, foo.Qix" | split: ", " %}
{% for pkg in packages %}
- {% include package_shortener.liquid package=pkg %}
{% endfor %}

result

page_root.liquid

extracts the first component of a page url:
/examples/includes/ → /examples

markdown

{% include page_root.liquid page=page %}

result

render_indices.liquid

creates the individual links in the sidebar.
links are indented when parented, unless their page layout has been excluded with no_indent

Note
This include is made available for override, so that a site can customize how (or if) it renders the items in the side nav.

markdown

<div class="ui link list">
{% assign collection = site.collections | where:"title","Examples" | first %}
{% include render_indices.liquid doc_list=collection.docs collection_label=collection.label page_title=page.title %}
</div>

result