Data Handling

Taxonomy data files

(New in v0.0.30) You can include custom taxonomy data files to include additional data for each taxonomy term (e.g., author biographies, category descriptions) by creating YAML files in the _includes/yamls/[taxonomy_name]/ directory. For example, if you have a taxonomy called "authors" and you want to add a biography for the author "Richard M Ritviks", you can create a file called _includes/yamls/authors.yaml file and put an id field with the value "someoneCool" (this is the unique id of the author). Then you can use any number of fields you want to include for the author "Richard M Ritviks", including the name as "Name: Richard M Ritviks" field.

Please the following example (created in _includes/yamls/authors.yaml file):

1
2
3
4
5
6
7

id:
  someoneCool:
    Name: Richard M Ritviks
    description: "**Ritviks** is _really, really_ cool." # You can use standard markdown here.
  someonefunny:
    Name: Adam R Smith
    description: "**Adam R Smith** is _really_ funny."

Now, you can use {{ taxonomy_yamls.authors.id.someoneCool.Name }} for the name of the author "Richard M Ritviks" in your templates, or {{ taxonomy_yamls.authors.id.someonefunny.Name }} for the name of the author "Adam R Smith" in your templates.

If you want to use a variable to dynamically access the author ID, use bracket notation:

1
2

{% set author_id = "someoneCool" %}
{{ taxonomy_yamls.authors.id[author_id].Name }}

Note that, to use this feature correctly, your theme needs to have a proper authors.html.jinja2 template file in the templates directory. There, you can use the {{ taxonomy_yaml['id'][taxonomy_term].Name }} syntax to access the data you have added to the YAML file.

Custom data files

(New in v0.0.36) You can include custom data files to include additional data for your website. This can come really handy if you are dealing with structured, repetitive data that you want to include in your website. Currently, both .yaml and .csv files are supported.

CSV files

CSV files allow you to manage structured, tabular data that can be easily displayed on your website. This is particularly useful for publications, team members, project lists, or any repetitive data.

Step 1: Create your CSV file

Place your CSV file in the _includes/datafiles/ directory. For example, create _includes/datafiles/publications.csv:

1
2
3

Authors,Title,Journal,Year,DOI,Notes
John Doe,The Title of the Paper,The Journal,2025,10.1000/1234567890,"This is a note"
"Steve H Lee, Robert Doe, and **Adam R Smith**",The Title of Paper 2,The Journal 2,2024,10.1000/1234567891,"Another note"

Note: You can use markdown formatting (like **bold**) within CSV fields, and it will be rendered properly.

Step 2: Reference data files in frontmatter

In your page's frontmatter, list the CSV files you want to use (in order):

1
2
3
4
5
6
7

---
title: Publications
slug: papers
template: pubs.html.jinja2
section: true
data_files: publications.csv, conferences.csv
---

Step 3: Use markers in your content

Use the {[!data!]} marker where you want each data file to appear. The first marker uses the first data file, the second marker uses the second data file, and so on:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

#### Journal Articles {.splitsection}

Below is a list of our recent papers:

{[!data!]}

#### Conferences {.splitsection}

Below is our conference presentations:

{[!data!]}

Step 4: Create a custom template

Create a custom template (e.g., pubs.html.jinja2) in your theme's templates directory to display the data. Here's an example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

{% if sections %}
    {# Parse data_files from page metadata #}
    {% set data_file_list = [] %}
    {% if page.metadata.data_files %}
        {% set data_files_str = page.metadata.data_files | string %}
        {% for df in data_files_str.split(',') %}
            {% set df_clean = df.strip().replace('.csv', '') %}
            {% set _ = data_file_list.append(df_clean) %}
        {% endfor %}
    {% endif %}

    {% set data_file_index = namespace(value=0) %}

    {% for section in sections %}
        {% set section_content_str = section.content | join('') | string %}
        {% set has_data_marker = '{[!data!]}' in section_content_str %}

        {% if has_data_marker %}
            <h4>{{ section.heading }}</h4>
        {% endif %}

        {# Display section content without the marker #}
        {% for content in section.content %}
            {% if '{[!data!]}' not in content %}
                {{ content | safe }}
            {% endif %}
        {% endfor %}

        {# Render data file if marker was found #}
        {% if has_data_marker and data_file_index.value < data_file_list | length %}
            {% set current_file_name = data_file_list[data_file_index.value] %}
            {% if data_files and current_file_name in data_files %}
                <ul>
                    {% for item in data_files[current_file_name] %}
                        <li>{{ item.Authors }}, {{ item.Title }}, {{ item.Journal }}, {{ item.Year }}</li>
                    {% endfor %}
                </ul>
            {% endif %}
            {% set data_file_index.value = data_file_index.value + 1 %}
        {% endif %}
    {% endfor %}
{% endif %}

Key features:

• Sections without {[!data!]} markers will display content only (no heading)
• Sections with {[!data!]} markers will display the heading, content, and data
• Data files are processed sequentially in the order specified in frontmatter
• Use | markdown filter to render markdown formatting in CSV fields

YAML files

YAML files are ideal for structured data with nested information or when you need more flexibility than CSV provides.

Step 1: Create your YAML file

Place your YAML file in the _includes/datafiles/ directory. For example, create _includes/datafiles/members.yaml:

1
2
3
4
5
6
7
8
9

- name: John Doe, PhD
  role: Software Engineer
  email: john.doe@example.com
  expertise: Machine Learning, Computer Vision, and solving real-world problems.

- name: Stacy H Lee, PhD
  role: Senior Researcher
  email: jane.doe@example.com
  expertise: Machine Learning, Computer Vision, and writing awesome Python libraries.

Important: Each item in the list starts with a dash (-) and fields are indented consistently.

Step 2: Reference in frontmatter and use markers

The usage is identical to CSV files:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

---
title: Team Members
slug: members
template: members.html.jinja2
section: true
data_files: members.yaml
---

#### Our Team {.splitsection}

Meet our talented team:

{[!data!]}

Step 3: Access in templates

YAML data is accessed the same way as CSV data:

1
2
3
4
5
6

{% for member in data_files[current_file_name] %}
    <h5>{{ member.name }}</h5>
    <p>{{ member.role }}</p>
    <p>Email: <a href="mailto:{{ member.email }}">{{ member.email }}</a></p>
    <p>{{ member.expertise }}</p>
{% endfor %}

YAML vs CSV: - Use CSV for simple tabular data (publications, events, etc.) - Use YAML for complex nested data or when you need better readability - Both work with the same {[!data!]} marker system

Markdown data files

You can include one or more supplementary markdown files into one of your main markdown file (i.e, files inside the posts or pages directory, or their sub-directories, that would be finally converted to a proper HTML page) using the {!path/to/file.md!} syntax. This can be useful for reusing common content across multiple pages, including code snippets or examples from external files. For more details, see the Markdown Processing page.