02 CataLogger

Conceptualized and developed by Thomas Reimann¹ and Navneet Sinha¹

¹ TU Dresden, Institute for Groundwater Management

Content

  1. Overview
  2. The iNUX Resource Catalog
  3. Motivation for Catalogger and YAML2PDF
    1. The Challenge
    2. Design Goals
    3. Catalogger and YAML2PDF: Core Concepts, Roles, and Workflow
    4. Standardized Resource Format
  4. How to Use the Catalogger
    1. Before You Begin
      1. General Text Entry Guidelines
      2. Resetting the Form Between Submissions
    2. Create a New YAML or Edit an Existing One
      1. Option 1 — Create a New YAML
      2. Option 2 — Edit an Existing YAML
  5. How to Use YAML2PDF
    1. Input Requirements
    2. Step-by-Step Usage

1 Overview

The iNUX project produces a wide range of interactive educational resources, including Streamlit applications, Jupyter notebooks, videos, datasets, and supporting materials. To make these resources discoverable, consistent, and reusable, they are published through the iNUX Interactive Documents webpage, which functions as a structured resource catalog.

To support this workflow, two complementary utility tools were developed:

  • Catalogger– a submission and validation tool for creating standardized resource descriptions. You can access the Catalogger here.

  • YAML2PDF – a transformation tool for generating human-readable resource sheets from those descriptions.

Together, these tools form a lightweight yet scalable pipeline that connects contributors to the catalog with minimal manual intervention. Cataloggying

2 The iNUX Resource Catalog

The iNUX resource catalog acts as a central access point for learning and teaching materials developed within the iNUX project and its partner institutions. These resources span a wide range of formats, topics, and levels of complexity, making consistency, clarity, and discoverability essential requirements.

The catalog is organized using a category and sub-category structure that reflects both pedagogical intent and technical content. This structure enables users to efficiently browse, filter, and locate relevant materials across a broad thematic spectrum. The rationale behind the chosen categories and their hierarchical organization is documented separately in the Categorization Documentation.

Catalogger does not define this categorization logic. Instead, it implements and enforces it at the submission level, ensuring that all contributed resources align with the established catalog structure.

3 Motivation for Catalogger and YAML2PDF

3.1 The Challenge

As the iNUX project grew, several challenges became apparent:

  • Resources were created by different authors, institutions, and teams.
  • Resource descriptions varied widely in structure, depth, and terminology.
  • Manual curation did not scale with the increasing number of submissions.
  • The same information was required in multiple formats:
    • for the website
    • for internal review, and for downloadable documentation (e.g. PDFs).

Without a standardized process, maintaining quality, consistency, and clarity across the catalog became increasingly difficult.

3.2 Design Goals

To address these challenges, Catalogger and YAML2PDF were developed with the following goals:

  • Consistency – all resources follow a common structure
  • Flexibility – support for diverse resource types
  • Scalability – growth without increased editorial workload
  • Automation – reuse across downstream pipelines
  • Openness – open-source, extensible, and reusable design

3.3 Catalogger and YAML2PDF: Core Concepts, Roles, and Workflow

Catalogger and YAML2PDF are infrastructure tools developed to support the structured submission, review, and publication of educational resources within the iNUX project.

Catalogger serves as the interface between contributors and the iNUX resource catalog. It guides contributors through a form-based submission process, validates resource descriptions against defined format and consistency rules, and ensures compatibility with the established catalog structure.

By enforcing structure at the submission stage, Catalogger enables resources to be automatically integrated into the iNUX Interactive Documents webpage, while significantly reducing downstream errors, ambiguity, and maintenance effort.

YAML2PDF complements Catalogger by transforming the same standardized resource descriptions into human-readable PDF resource sheets suitable for review, dissemination, and archival use.

The intended workflow is straightforward:

  • Contributors submit a resource using Catalogger.
  • Editors review the generated YAML (and optionally the PDF).
  • YAML2PDF produces standardized outputs for publication.

This results in a one input pipeline that scales efficiently with minimal manual intervention.

Catalogger and YAML2PDF are not end-user learning applications. They are intended for contributors, editors, and project partners.

3.4 Standardized Resource Format

To meet these requirements, Catalogger relies on a YAML-based resource definition format.

Each submitted resource is described using a YAML file that captures a predefined set of parameters, including:

  • metadata (title, authors, affiliations),
  • categorization information,
  • resource type and format,
  • links to repositories or external platforms,
  • optional descriptive and pedagogical information,
  • optional figures and references.

This approach ensures that all resources are:

  • machine-readable,
  • human-readable,
  • easy to validate,
  • and suitable for automated processing.

4. How to Use the Catalogger

4.1 Before You Begin

4.1.1 General Text Entry Guidelines

Applies to all text-based fields

For all text fields (e.g. title, descriptions, keywords, prerequisites, captions, references):

  • Use plain text only.
  • Avoid special characters (such as :, ;, |, /, \) as well as emojis.
  • Do not use formatting or decorative symbols.

These guidelines ensure consistent rendering across the website, PDFs, and downstream processing tools.

4.1.2 Resetting the Form Between Submissions (Important)

Always reload the page before starting a new resource submission or after completing a YAML/PDF generation. Catalogger retains form values during a session to support iterative editing therefore when creating multiple submissions in sequence, it is strongly recommended to reset the form between runs.

To reset all fields: Use the browser reload / refresh button.

Reloading the page clears all entered values and prevents unintended carry-over of data from a previous submission (for example, residual text, images, or image captions).

4.2 Create a New YAML or Edit an Existing One

Catalogger helps you create or edit a YAML-based resource description for the iNUX resource catalog. You can either:

  • Create a new YAML from scratch, or

  • Upload an existing YAML to prefill fields and edit it.

At the end of the process, you will download:

  • a YAML file (always),

  • a PDF resource sheet (always),

  • and, if images were uploaded, a ZIP folder containing the YAML, PDF, and images.

4.2.1 Option 1 — Create a New YAML

Step 0: Open the App

Access the Catalogger at the following link: Click here

Step 1: Language of the Resource

Field: Select the main language of this resource

Select the language in which the resource is written (e.g. English, German).

Step 2: Choose the Topic Area (Catalog Location)

This step defines where your resource will appear in the iNUX resource catalog. Selecting an appropriate catalog location ensures that users can easily find your contribution.

Field: Category

Select the main category that best represents the topic area of your resource.

  • Choose the category where your resource most naturally belongs.

  • If no suitable category exists, select ➕ Define new category to propose a new one.

  • In most cases, an existing category should be used.

Field: Subcategory

Select the subcategory that best matches the focus of your resource.

  • Choose the most appropriate existing subcategory from the list.

  • If none of the available options fit, select ➕ Define new subcategory to propose a new one.

  • If you are unsure, choose the closest matching subcategory.

Field: Sub-subcategory (optional)

Sub-subcategories provide additional thematic refinement and are currently optional. Most submissions do not require a sub-subcategory.

Leave this field unchanged to attach the resource directly to the selected subcategory.

  • Select an existing sub-subcategory only if it is clearly appropriate.

  • Select ➕ Define new sub-subcategory to propose a new one.

  • If unsure, attaching the resource at the subcategory level is sufficient.

Step 3: Describe Your Submission (Main Identity Fields)

Field: Title of the resource

Enter the title exactly as it should appear in the catalog.

  • Use a clear, concise, descriptive title.

  • Avoid special characters and decorative symbols

Field: Submission type

Choose one:

  • Streamlit app

  • Jupyter Notebook

  • Other

If Streamlit app is selected, additional options appear:

  • Is this a multipage Streamlit app? → Enter the approximate number of pages.

  • Does the app contain interactive plots? → Enter the approximate number.

  • Does the app include assessments (questions)? → Enter the approximate number.

  • Does the app include embedded videos or tutorials? → Enter the approximate number.

If exact counts are not known, reasonable estimates are acceptable.

Step 4: Author(s)

This section allows you to add one or more authors.

  • Field: Author name

Enter the author’s full name.

  • Field: Author affiliation

Enter the institution or organization.

  • Field: Additional Authors (Optional)

  • Use:

    • ➕ to add author

    • ➖ to remove author

Step 5: Resource Details

  • Field: Access link (URL)

Paste the direct link to the resource (e.g. Streamlit app, GitHub repository, Binder link, or video).

  • Field: Estimated time required

Select one of the predefined ranges or choose Custom to enter your own.

  • Field: Short description (1–2 paragraphs)

Briefly explain what the resource does and what the learner will gain from it.

  • Field: Keywords (comma-separated)

Enter keywords describing the main topics of the resource.

Separate keywords using commas.

  • Example: groundwater, vadose zone, soil water retention

Keywords are used by site-wide search and filtering tools to help users find your resource.

  • Field: Best suited for

Select one or more:

  • classroom teaching

  • online teaching

  • self learning

  • exam preparation

  • Field: Prerequisites (comma-separated)

Example: Darcy’s law, basic hydrology, Python basics

  • Field: References (one per line)

Enter one reference per line (e.g. DOI, paper, dataset, textbook).

Step 6 Figures (Optional Images)

Although optional, contributors are strongly encouraged to include figures. Images help users understand what to expect from the resource and improve visibility in the catalog.

Field: Optional figures (PNG/JPG)

You may upload images such as:

  • screenshots,

  • diagrams or schematics,

  • illustrative figures.

For each image, you may specify:

  • Type (e.g. Screenshot, Diagram, Photo),

  • Caption,

  • Use as cover image (optional).

Cover Image Selection

If multiple images are uploaded:

  • You may designate one image as the cover image.

  • If no cover image is selected, the system will automatically use one of the uploaded images as the default cover image.

Step 7: Preview and Generate Files

Click Submit / Generate YAML to process the entered information.

Preview Before Generation (Optional)

Field: Show preview before download

If selected:

  • A preview is shown before any files are generated.

  • Review the preview carefully.

  • If changes are needed, edit the fields and click Submit / Generate YAML again.

At this stage, no files are generated.

Once satisfied, click Looks good – create download file. Only then are the output files generated.

Step 8: Download Your Files

After file generation, the following files are available:

  • YAML file

  • PDF resource sheet

  • If images are uploaded, a ZIP folder is provided containing:

    • the YAML file,

    • the PDF resource sheet,

    • all uploaded images, renamed consistently.

Select the file you wish to download and click on it to start the download.

4.2.2 Option 2 — Edit an Existing YAML

Catalogger allows you to upload an existing YAML file to modify, update, or correct a previously created resource description.

This option is useful for:

  • updating metadata (e.g. title, description, keywords),

  • correcting errors,

  • adapting an existing resource for a new version,

  • reusing a YAML file as a starting point for a similar resource.

Step 1: Upload an Existing YAML

Use the upload option to select an existing .yaml or .yml file.

Once uploaded:

  • Catalogger reads the file and prefills most form fields automatically.

  • You may then review and edit the prefilled values as needed.

Important Notes About Prefilled Fields

When editing an existing YAML, the following behavior applies:

  • Text-based fields (e.g. title, description, keywords, authors, links) are restored where possible.

  • Catalog location fields(category, subcategory, sub-subcategory) are not restored and must be selected again manually.

  • Images are not imported. If figures are required, they must be uploaded again, captions must be re-entered, and a cover image must be selected as usual.

This behavior is intentional and ensures compatibility with the current catalog structure and image handling.

All general rules for text entry, image handling, and catalog selection apply in the same way as for new submissions.

Step 2: Re-select the Catalog Location

After uploading the YAML:

  • Go to Choose the Topic Area (Catalog Location).

  • Select the appropriate category, subcategory, and (if applicable) sub-subcategory.

This step is mandatory, even when editing an existing YAML file.

Step 3: Review and Edit the Fields

  • Proceed through the form sections in the same way as for a new submission:

  • Update titles, descriptions, keywords, or links as required.

  • Add, remove, or update authors and affiliations.

  • Adjust metadata such as estimated time, prerequisites, or references.

  • Re-upload figures if they should be included in the updated version.

Step 4: Generate and Download Outputs

Preview, file generation, and download follow the same process as described in Option A (Create a New YAML).

Please refer to Step 7: Preview and Generate Files and Step 8: Download Your Files for the detailed workflow

Resetting the Form Between Edits (Important)

When editing multiple YAML files in sequence, it is strongly recommended to reload the browser page before uploading the next YAML file.

Reloading the page ensures a clean form state and prevents unintended carry-over of values, images, or image captions from a previous edit.

5. How to Use YAML2PDF

YAML2PDF is a standalone utility that converts a YAML resource description into a formatted PDF resource sheet. It is intended for review, dissemination, and archival purposes. Unlike Catalogger, YAML2PDF does not modify or validate metadata. It only renders the provided YAML into a PDF.

5.1 Input Requirements

To use YAML2PDF, you need:

  • a valid YAML file describing an iNUX resource (typically generated using Catalogger).

  • optionally, one or more image files (PNG or JPG) to be included as figures in the PDF

5.2 Step-by-Step Usage

Step 1: Upload the YAML File

  • Upload a .yaml or .yml file using the file upload field.

  • Once uploaded:

  • The YAML content is displayed as a read-only preview.

  • No files are generated at this stage.

Step 2: Select the Language Label

Select the language to be shown in the PDF header.

This does not modify the YAML content. It only affects how the language is displayed in the generated PDF.

Step 3 — Upload Figures (Optional)

  • You may optionally upload one or more images (PNG or JPG):

    • screenshots,

    • diagrams,

    • or other illustrative figures.

  • If figures are uploaded:

    • they are appended to the PDF in a dedicated Figures and illustrations section,

    • captions and ordering are derived from the YAML where available.

    • If no figures are uploaded, the PDF is generated without a figures section.

Step 4: Generate and Download the PDF

  • Click Generate PDF to create the PDF resource sheet.

  • Once generation is complete:

    • a Download PDF button appears,

  • Click the button to download the generated PDF file.

Resetting the Tool Between Runs (Important)

Always reload the page before uploading a new YAML file or generating a PDF for a different resource as YAML2PDF retains uploaded files and settings from previous session. When generating PDFs for multiple YAML files, it is strongly recommended to reset the tool between runs.

To reset all inputs:

  • use the browser reload / refresh button.

  • Reloading the page ensures:

    • the previous YAML file is cleared,

    • previously uploaded figures were removed,

    • The next PDF is generated from a clean state.

Co-funded by the European Union
This project is co-funded by the European Union. However, the views and opinions expressed are solely those of the author(s) and do not necessarily reflect those of the European Union or the National Agency DAAD. Neither the European Union nor the granting authority can be held responsible for them.