Components

Components are how you add more complex content to your site beyond basic Markdown. They are building blocks for visual and interactive elements, sometimes called "widgets".

This template comes with many pre-made and flexible components so you can assemble your website however you want with ease. Simply place the example code for one of the components below in one of your index.md's or other markdown files, and it will appear in your site.

The basic syntax is:

{% include some-component.html parameter="value" %}

Unless noted otherwise, all parameters are optional and have graceful fallbacks if not specified.

Section

Each page's main content can be split up into sections. The sections span the entire width of the page, and have alternating white and light-gray backgrounds by default.

Use this component to create a section break (i.e. end the previous section and start a new one) and style the next section.

Empty sections are automatically removed, so if you want to style the first section on a page, just put this component before any other content.

Previous section of content

{%
  include section.html
  background="images/some-bg-image.jpg"
  dark=true
  full=true
%}

Next section of content

background

Background image to show beneath the next section (blended in with the solid background color to ensure there is enough contrast for text to be readable). The image is scaled to cover the size of the section based on its contents.

Defaults to no image.

dark

Whether the next section should have a dark background color, instead of the default light background. All of your text content in the section will switch from dark to light to stay readable.

Defaults to false.

full

Whether to make the next section's content take up the full width of the page and full height of the section (i.e. no padding/margins). This is useful if you have a very detailed figure you want to show, or in combination with a banner.

Defaults to false.

Banner

A basic, full-width image. If used in combination with a full section component, it spans the entire width of the page.

Similar to using a section component with a background, except that the image isn't altered to maintain contrast for text readability (because no content can be put on top of this component). Also, with the former, you may not always see the full image. With this, you will always see the full image, in the original aspect ratio.

Use this only for decorative/presentational purposes. For images that contain or require important text content, use a figure component with a caption instead.

{% include banner.html image="images/banner.jpg" %}

image

Url to an image for the banner.

Figure

An image, a caption, and a link.

{%
  include figure.html
  image="images/group-photo.jpg"
  caption="The team at our annual Christmas party, 2025"
  link="team"
  width="400px"
%}

image

Url to an image for the figure.

caption

Caption for the figure. Can contain Markdown.

link

Url to link to when clicking on the image.

width / height

Explicitly set the width OR height of the image. width accepts percent or pixels, like 75% or 300px. height accepts pixels.

If neither are specified, defaults to the image's natural dimensions. If both are specified, width takes priority to preserve the aspect ratio of the original image.

Gallery

A gallery of image tiles, with links and tooltips.

{%
  include gallery.html
  image1="images/cell.jpg"
  link1="https://cell.com/"
  tooltip1="Cell"
  image2="images/virus.jpg"
  link2="https://virus.com/"
  tooltip2="Virus"
  image3="images/cell.jpg"
  image4="images/virus.jpg"
  image5="images/bacteria.jpg"
  style="square"
%}

imageX

Url to the image.

linkX

Url to link to when clicking the image.

tooltipX

Tooltip to show when hovering over the image.

style

The style variation of the gallery.

Set to square to make the tiles square and to cover-fit the images inside them.

Defaults to keeping the image tiles at their natural aspect ratio.

Feature

An image, a heading, some text, and a link. Useful for your home page, where you want to highlight key points about your lab. If you put multiple of these components in a row, the image and text sides alternate.

{%
  include feature.html
  image="images/group-photo.jpg"
  link="team"
  title="Meet our team"
  text="Our team is made up of people all around the globe, dedicated to transparent and reproducible science."
%}

image

Url to an image for the feature.

link

Url to link to when clicking on the image.

title

"Headline" for the feature. A few words work best.

text

Text to show below the heading. Can contain Markdown.

Link

A link with icon and/or text.

The template has many common link types built-in. To see the built-in types or to add your own, see /_data/links.yaml.

{%
  include link.html
  type="twitter"
  link="some_twitter_handle"
  icon="fab fa-twitter-square"
  text="Follow us on Twitter"
  tooltip="Follow us on Twitter for cool tweets about nothing"
  style="button"
%}

type

The "type" of the link (see above). Determines fallback icon/text/etc, and determines the full url to link to.

link

Where to link to, without any prefixes like @, www., etc. This field gets inserted into a fully prefixed/formatted url based on the link type (see above).

If not specified, the link is not shown at all.

icon

The Font Awesome Free icon class to use, or the filename of a custom (preferably SVG) icon in /_includes.

If not specified, no icon is shown. If set to "", defaults to the fallback icon for the link type.

text

Text for the link, to the right of the icon.

If not specified, no text is shown. If set to "", defaults to the fallback text for the link type.

tooltip

Text to show when hovering over the link.

If not specified, no tooltip is shown. If set to "", defaults to the fallback tooltip for the link type.

style

The style variation of the link.

Set to button to make the link look like a button (rounded rectangle with a solid fill).

Defaults to a plain style.

List

A generic and flexible way to automatically list large sets of items. Takes any list, filters it, and displays each item with as a component of your choice.

{%
  include list.html
  data="citations"
  component="citation"
  filters="group: featured"
  style="rich"
%}

data

The name of the set of items to loop through. Can be the name of a file in /_data without the extension (such as citations), or a collection (such as posts or members).

If your list has date fields, it is also sorted from newest to oldest, and grouped into sections by year.

component

The component to show for each item in the list, such as a card, portrait, etc.

The fields in your list data should match what the chosen component takes as parameters (except for the style parameter, see below). For example, the card component will look for image, name, tags, etc. on each item in the list.

filters

Allows you to split your list into groups by any field, only displaying a "sub-list". This is useful for splitting or sorting your list by certain traits, like displaying your students before your programmers.

Comma-separate filters to use multiple. Leave a value blank to select all items that don't have that field specified. Prefix a value with a ~ to look for partial matches instead of exact/full matches.

style

A style parameter to set on all of the components in the sub-list, so you don't have to set it manually on every item (see above). This is the only field that works this way, because all other fields are likely to be different for each item, but you'll likely always want the style parameter to be the same for an entire sub-list.

Examples

This component is probably the most complex one, so here are some more examples:

{% include list.html data="members" component="portrait" filters="role: programmer, status: current" %}
{% include list.html data="members" component="portrait" filters="role: programmer, status: alumni" style="small" %}

Shows a list of team members who have role equal to programmer AND status equal to current. Then shows a list of former team members with smaller portraits.

{% include list.html data="posts" component="post-excerpt" filters="category: story" %}
{% include list.html data="posts" component="post-excerpt" filters="category: workshop" %}
{% include list.html data="posts" component="post-excerpt" filters="category: " %}

Shows blog posts with the category story, then ones with workshop, then finally ones with no specified category at all (that is, all the rest).

{% include list.html data="events" component="card" filters="date: ~2020" %}

Shows a list of events in /_data/events.yaml with the card component, only showing ones whose date fields contain "2020", effectively only showing the events from the year 2020.

Card

A multi-size, flexible card with an image, link, text, and tags.

{%
  include card.html
  image="images/space.jpg"
  link="https://nasa.gov/"
  title="A Large Card"
  subtitle="A cool card"
  description="A cool description"
  tooltip="A cool tooltip"
  tags="tag A, tag B, tag C"
  repo="greenelab/lab-website-template"
  style="small"
%}

image

Url to an image for the card.

link

Url to link to when clicking the image or the title of the card.

title

Title for the card.

subtitle

Subtitle for the card.

description

Paragraph of text or Markdown to show under the card name.

tooltip

Text to show when hovering over the card.

tags

Tags to show at the bottom of the card.

See the tags component.

repo

GitHub repository to automatically fetch additional tags from.

See the tags component.

style

The style variation of the card.

Set to small to make the card a bit smaller.

Defaults to a larger card.

Citation

A citation for a particular source, with publication title, authors, publisher, date, thumbnail, tags, and extra links. See Citations.

{%
  include citation.html
  id="doi:10.7554/eLife.32822"
  style="rich"
%}

id

Identifier for the source you want to cite. The component finds this id in /_data/citations.yaml and automatically displays the rest.

style

The style variation of the citation.

Set to rich to include thumbnail, tags, and extra links.

Defaults to a plain card with publication title, authors, publisher, and date.

Portrait

A portrait for a team member, with image, link, name, and role. You probably won't need to use this component standalone, but rather with the list component to list groups of members in your organization. If you want to show a single team member on a particular page, use the following example:

{%
  include portrait.html
  id="tim-member"
%}

id

Filename of the team member page (without .md extenion).

Role

A team member role, with icon, text, and description. You probably wont need to use this component directly, as it's already included in the portrait component and on the member pages.

However you may want to extend the types of roles. The template has a few common role types built-in. To see the built-in types or to add your own, see /_data/links.yaml.

{%
  include role.html
  type="phd"
  description="Senior Researcher"
  text=true
%}

type

The "type" of the role (see above). Determines the icon and text to show.

description

Team member's job title/position to show under the role text.

text

Whether to show text next to the icon, or in a tooltip when hovering over the icon.

Defaults to false.

Two Col

A generic two-column layout (that collapses into a single column when the screen is smaller). A good use of this is to put two figure components side by side.

You can give it plain text like col1="Some text". Using Liquid's capture function, you can also give it markdown, other components, or any other arbitrary content.

{% capture col1content %}
{% include figure.html ... %}
{% endcapture %}
{% capture col2content %}
{% include figure.html ... %}
{% endcapture %}

{% include two-col.html col1=col1content col2=col2content %}

col1 / col2

Left/right column content.

Post Excerpt

Excerpt and some metadata from a blog post. You probably won't need to use this component standalone, but rather with the list component to list several posts as a group. If you want to show a single post excerpt on a particular page, use the following example:

{%
  include post-excerpt.html
  id="example-blog-post-1"
%}

id

Filename of the blog post (without YYYY-MM-DD date prefix or .md extension).

Search

The template can automatically, instantaneously hide/filter certain components on the page based on a search query. A search can happen in a few different ways:

Search box component - Putting a search box component on a page like {% include search-box.html %} lets the user type in their own search.
Tags component - Clicking on a tag in the tags component automatically searches the page for items that contain that tag.
Permalink - Appending ?search=some search to the url automatically runs a search on that page (see /_layouts/member.html for a good use case).

To show info about what items are being filtered, e.g. Showing 12 of 60, you can put a search info component on a page like {% include search-info.html %} (only visible if something being searched).

Search syntax

You can search for terms, phrases, and tags, like term1 term2 "full phrase 1" "full phrase 2" "tag: some tag" "tag: another tag". Items that contain all of the terms, at least one of the phrases, and at least one of the tags will be considered a match. Search words will be highlighted in the results (if they're longer than 2 characters). Searching is case insensitive.

Site Search

The regular search box component explained above only searches the current page. This site search component searches your whole site, using Google.

This is most notably used on the template's 404 page, but you may find it valuable to put on your home page for your users.

{% include site-search.html %}

Note that currently, this is a just a simple search box that links to a Google search of your site. In the future it may be extended to allow instantaneous searching right on the page, i.e. without having to navigate away to Google to see results.

Embeds

Most social media sites have some sort of way to embed content posted there into other websites. Here is Twitter's for embedding timelines and the like. For YouTube, go to a video, click share, then embed.

To put these embeds in your site, all you have to do is paste the code they give you straight into your markdown, like this:

### Latest Tweets

<a class="twitter-timeline" data-width="400" data-height="400" href="https://twitter.com/GreeneScientist?ref_src=twsrc%5Etfw">Tweets by GreeneScientist</a> <script async src="https://platform.twitter.com/widgets.js" charset="utf-8"></script>

### Latest YouTube Videos

<iframe width="600" height="400" src="https://www.youtube.com/embed/GMEHQQ7_4Yo" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>

⚠️ This wiki is legacy documentation for the pre-release version(s) of the template, and will eventually go away!
✨ The documentation for v1.0.0 and above are now at https://greene-lab.gitbook.io/lab-website-template-docs.

🧠 Background Knowledge

💡 Tips

❓ Support