Website Code IC D2MCM

IZD2MCM Website Documentation IZ D2MCM Team October 28, 2025 Text: CC BY 4.0 Images: All rights reserved. About this document This document is a copy of the GitLab wiki that serves as the knowledge base for developing and maintaining the IC D2MCM website at HU Berlin. The original structure as separate Markdown files has been emulated herein. Table of Contents File: 01-01-About-this-repository.md ........................................................................ 6 What is the IC D2MCM website for? ............................................................................. 6 File: 01-02-Directory-structure.md ............................................................................ 6 Explanation of folders and files in the root directory ..................................................... 7 Scripts ..................................................................................................................... 11 Content pages and sub-folders (inside of content_de / content_en) ............................ 11 File: 01-03-Naming-convention-for-folders-and-files.md ......................................... 13 How to name folders & files ....................................................................................... 13 File: 01-04-Local-testing-with-docker.md ................................................................ 14 First of all… what is Docker? ...................................................................................... 14 Installing Docker ....................................................................................................... 14 Testing the website locally with Docker ...................................................................... 14 File: 01-05-troubleshooting.md ............................................................................... 16 Troubleshooting the Website ..................................................................................... 16 Is the website server down? ................................................................................... 16 Is GitLab down? ........................................................................................................ 16 Problems with the CI/CD pipeline? ............................................................................ 16 File: 01-06-Using-Git-and-Branch-Management.md ................................................. 17 Using Git and Branch Management ............................................................................ 17 Git ........................................................................................................................ 17 File: 02-01-How-to-add-content.md ........................................................................ 17 What is content? ...................................................................................................... 17 Markdown ................................................................................................................ 17 Adding pages ............................................................................................................ 17 1. Decide if your page belongs in a folder ................................................................ 17 2. Create the file for the page ................................................................................. 18 3. Add Frontmatter ................................................................................................ 18 4. A guide for writing content with Markdown .......................................................... 19 How to add English content ....................................................................................... 20 File: 02-02-Events-section.md ................................................................................ 20 The Event Section ..................................................................................................... 20 1. Introduction ...................................................................................................... 21 2. How to add events ............................................................................................. 21 3. Individual event pages ....................................................................................... 23 4. ICS Template and Script ..................................................................................... 24 File: 02-03-blog.md ................................................................................................ 24 IZ D2MCM Blog ......................................................................................................... 24 Introduction .......................................................................................................... 25 Workflow .............................................................................................................. 25 Blog template ....................................................................................................... 25 Tags ...................................................................................................................... 26 Auto-generated thumbnails ................................................................................... 26 Notes ................................................................................................................... 27 File: 03-01-Jekyll-Kramdown-and-Liquid-Guide.md ................................................. 27 Jekyll documentation ................................................................................................ 27 Jekyll .................................................................................................................... 27 Kramdown ............................................................................................................ 28 Liquid ................................................................................................................... 28 File: 03-02-Includes.md .......................................................................................... 28 Includes ................................................................................................................... 28 Sources and useful links: ....................................................................................... 28 What are includes? ............................................................................................... 28 Passing parameters to includes ............................................................................. 28 Custom includes by the IC D2MCM ........................................................................ 29 Content ................................................................................................................ 30 Navigation ............................................................................................................ 32 Sliders .................................................................................................................. 32 File: 03-03-CSS-Guide.md ...................................................................................... 35 How CSS works in the IC D2MCM website .................................................................. 35 1. Introduction ...................................................................................................... 35 2. Origins of the IC D2MCM styles: The Phantom Jekyll Theme ................................. 36 3. Custom IC D2MCM Designs ............................................................................... 38 File: 03-04-Accessibility-Guidelines.md .................................................................. 45 Accessibility Guidelines ............................................................................................ 45 Images that tell you what they are .......................................................................... 45 Links that tell you where they go ............................................................................. 45 Contrast and Color ................................................................................................ 45 Responsive Design ................................................................................................ 45 Text Resizing: ........................................................................................................ 46 File: 03-05-helpful-developer-tips.md ..................................................................... 46 Helpful Developer Tips .............................................................................................. 46 Native Emmet abbreviations .................................................................................. 46 Custom Liquid Emmet abbreviations ..................................................................... 46 File: 03-06-tags.md ................................................................................................. 47 Tags ......................................................................................................................... 47 What are tags? ...................................................................................................... 47 How do we use tags for versioning? ........................................................................ 47 In short: ................................................................................................................ 48 File: 03-07-branches.md ......................................................................................... 48 Branch Management ................................................................................................. 48 1. master branch (deployment) ............................................................................. 48 2. test branch (testing) ........................................................................................... 48 3. Feature branches (development) ........................................................................ 48 Workflow .................................................................................................................. 49 File: 03-08-security-configs.md .............................................................................. 49 File: 03-09-event-validation.md .............................................................................. 50 Event Validation System ............................................................................................ 50 Overview ............................................................................................................... 50 What Gets Validated ............................................................................................. 50 Running Validation ................................................................................................ 52 CI Pipeline Integration ........................................................................................... 52 Common Validation Errors .................................................................................... 52 Example Event File ................................................................................................ 53 Validation Results ................................................................................................. 53 For Content Creators ............................................................................................. 53 For Developers ...................................................................................................... 53 Troubleshooting .................................................................................................... 54 File: 03-10-event-frontend.md ................................................................................ 54 Event Section Frontend ............................................................................................. 54 Appearance of the Events Section .......................................................................... 55 Event Backend ...................................................................................................... 55 File: 03-11-event-backend.md ................................................................................ 55 The Backend of the Event Section .............................................................................. 55 The Basics: Storage of Event Data with Markdwown Files ........................................ 55 Automatic Event Archiving ..................................................................................... 56 Automatic Validation of Event Data ........................................................................ 56 File: 03-12-RIDSCH-event-form.md ......................................................................... 57 RIDSCH Event form ................................................................................................... 57 What it does .......................................................................................................... 57 Files and purpose .................................................................................................. 57 Quick flow ............................................................................................................ 57 Deployment notes ................................................................................................. 57 🔒 Security statement ............................................................................................ 57 Security Features .................................................................................................. 58 File: 03-13-blog-section-for-developers.md ............................................................ 58 The Blog Section (for Developers) .............................................................................. 58 Overview ............................................................................................................... 58 The Blog Index Page ............................................................................................... 58 CSS ...................................................................................................................... 59 File: 03-14-redirects.md ......................................................................................... 59 Redirects .................................................................................................................. 59 Overview ............................................................................................................... 59 History .................................................................................................................. 60 File: 03-15-blogpost-pdf-generation.md .................................................................. 60 Blogpost PDF Generation .......................................................................................... 60 Overview ............................................................................................................... 60 Quick Start ............................................................................................................ 60 File Structure ........................................................................................................ 61 Features ............................................................................................................... 61 GitLab CI Integration ............................................................................................. 61 Supported Jekyll Features ...................................................................................... 62 Dependencies ....................................................................................................... 62 Troubleshooting .................................................................................................... 62 File: 03-16-SoGo-API.md ......................................................................................... 63 SoGo API .................................................................................................................. 63 SoGo_sync.py Script Details .................................................................................. 63 File: 03-17-guide-for-a-new-developer.md .............................................................. 64 File: 03-18-dealing-with-german-and-english.md .................................................... 65 Dealing with German and English Pages .................................................................... 65 File: 01-01-About-this-repository.md What is the IC D2MCM website for? The IC D2MCM is an information hub that serves to connect researchers and advanced students of its seven participating institutions at the Humboldt-Universität zu Berlin. Accordingly, the IC D2MCM website is the first place where that information can be accessed. The website offers information on: • Events and activites at the IC • How to participate with the IC, e.g. in working groups or in the Early Career Researcher Panel • Researchers in the fields of Digitality and Digital Methods and how to contact them File: 01-02-Directory-structure.md This page is an overview of the current website structure. Every folder and file in the root directory will be explained in the following list. Note for beginners: In our website system (Jekyll), pages are generated from Markdown files with front matter, which are compiled into HTML when the website gets built. This is important to know in order to understand this section. Maintenance note: This section will be updated to fit the new repo structure in April 2025. Explanation of folders and files in the root directory file / directory description _data Well-formatted site data should be placed here. The Jekyll engine will autoload all data files (using either the .yml, .yaml, .json, .csv or .tsv formats and extensions) in this directory, and they will be accessible via site.data. For example for the file members.yml in the directory, you can access contents of the file through site.data.tags. _events _events is a collection of wellformatted Markdown files that represent events at the IC D2MCM. These files have two functions: On the one hand they each generate their own individual event page, where unique information about events can be stored. On the other hand, the files, and especially their frontmatter, are the raw data for operations such as generating ics files to import into one’s calendar and generating the list of current events in the events section. _includes Includes are snippets, usually of HTML, that can be included on any page on the website. They are very useful when the same piece code has to be used in a lot of different places. Each of them has its own file in the folder _includes. You invoke them with the liquid tag {% include the-name-of-your-include-file %}. For an example have a look at the integration of tiles on the landing page (index.md) or the working groups section (workinggroups.md). In index.md, the include invocation looks like this {% include tiles_home.html %} _layouts Layouts are blueprints for web pages. They determine how a page is structured when it gets converted from Markdown to HTML. A layout is selected in the front matter of a page using the variable layout. Whatever you put in the part of the Markdown file that’s under the frontmatter (beneath the three dashes---), gets put into the liquid tag {{ content }}. The layout also is a good place for common includes. For example, pages get their header and footer from includes in their layout. _plugins Similar to the folder “scripts”, this folder holds ruby scripts that function as proper Jekyll plugins. _posts Stores the files of the blog posts that get displayed in the Blog Section. _sass SASS/SCSS is an advanced form of CSS (read more here). The _sass folder contains SASS files that can be imported into main.scss which will then be processed into a single stylesheet main.css that defines the styles to be used by the finished website. .gitlab_templates This folder contains templates for different types of issues, for example for bug reports, feature or design requests, content updates, etc. _site This is where the generated site will be placed (by default) once Jekyll is done transforming it. This has been added to the .gitignore file. assets This folder contains the CSS, JavaScript and font assets. See also the Jekyll documentation. content_de All German content pages go here. content_en All English web content that serves as a translation of German content should be placed in this folder. It mirrors the folder content_de. The German and English files have to be linked through the variable translation in their frontmatter. documents The folder documents contains: ics-files This folder contains the downloadable ics files for the events of the IC. (Ics files allow you to import events to your calendar.) images This folder contains any image files to be used for the general parts of the website, such as the logo of the IC D2MCM, design elements, etc.Note: Images for documenting events should be put into their own subfolder called img, inside a folder named after their event, which in turn should be inside /documents/event_files. scripts Miscellaneous code files (scripts) go here _config.yml Stores important configuration data. _config_docker.yml A configuration file that allows testing the website locally with docker. (See also Local testing with docker on our wiki) .gitignore A file that specifies which files and folders will not be pushed to the remote repository. .gitlab-ci.yml This file controls the build pipeline for the webpage. For more information see the [GitLab documentation](https://docs.gitlab. com/ee/ci/). File: 01-05-troubleshooting.md Troubleshooting the Website Work in Progress!! (PB 2025-02-25) Is the website server down? • If you have already set up an SSH connection between your computer and the webserver, check if you can reach the server through the command line using `ssh [email protected] `. • Alternatively, check in on the server through its web interface (The link is stored in the account management documentation in the HU Box) • Check the CMS server status page: https://www.cms.huberlin.de/en/stoerungen/phpstoerungen • If problems persist or are urgent, contact CMS Is GitLab down? Problems with the GitLab CI/CD pipeline may look like this: fatal: unable to access 'https://scm.cms.hu-berlin.de/izd2mcminfrastructure/izd2mcm-website.git/': Could not resolve host: scm.cms.huberlin.de • Check the CMS server status page: https://www.cms.huberlin.de/en/stoerungen/phpstoerungen If it’s clear that the problem lies on the side of the CMS, or things are unclear, contact the CMS. Problems with the CI/CD pipeline? • If the pipeline status is “pending”, there might be too many users running pipelines at the system right now. You may have to wait a couple of minutes for the system to have the capacity to run your pipeline. • For different problems, check the output log of the CI/CD job for error messages File: 01-06-Using-Git-and-Branch-Management.md Using Git and Branch Management Git We use Git for version control. With this software, we track every change to our files. For this Wiki Page, we’ll assume that you are familiar with the concept of commits and branches. In our workflow, we use three types of branches: 1. The master branch (permanent, protected) 2. The test branch (permanent, protected) 3. Feature branches (multiple) File: 02-01-How-to-add-content.md What is content? Content <-> Infrastructure In the context of the IC D2MCM, content are pieces of text or other media such as images and videos. The word content differentiates these pieces of information from the infrastructure that displays them. Roles In the current setup, some teammates focus mainly on the creation of content while others focus mainly on the development and maintenance of the infrastructure and frameworks that hold and display said content. Markdown The format in which content gets encoded for the IC D2MCM website is Markdown. Markdown is a compromise between plaintext (.txt files) and more advanced formats like Word documents (.docx files). There is a limited but versatile number of formatting options available in Markdown, such as headings, lists, tables, bold text, and italic text. The page you are reading right now is also written in Markdown. To learn more about how to write in Markdown, take a look at this page. Adding pages 1. Decide if your page belongs in a folder • New working group pages belong in the folder wg. • New events must be put into the folder _events. • New blog posts must be put into the folder _posts. 2. Create the file for the page • Pages on our website are created as Markdown files, which automatically get transformed into HTML when the website is built. • To create a Markdown file, in VSCode, right-click into the correct folder and select “New File…”. • Make sure that the file has the extension .md at the end of its filename. 3. Add Frontmatter • In order for the transformation into HTML to work, the Markdown file needs Frontmatter. Frontmatter looks like this: --- layout: default title: "My cool new webpage" --- • Make sure to add frontmatter to every new Markdown file you create. • Frontmatter follows the YAML syntax. o That means that every line has a key and a a value, separated by a colon. o The keys are called variables. • The layout variable determines how the finished page will look like, including elements such as headers and footers. o All pages must at least have a layout variable. o If you don’t have a specific layout in mind, use the value default • Event pages need a multitude of variables. See 04-07-Events-section for reference. • Important: All variables from the frontmatter can be accessed with Liquid Tags. Example: {{ page.title }} This returns and displays whatever string has been stored in the page’s title variable. • Learn more about using variables in Jekyll in the Jekyll docs. 3.1. Optional: Give the page a tile on the landing page • Some pages are so important that they get a place among the colourful square tiles on the landing page. • To give a tile to a page, add the variable category: home to its frontmatter. o Then, give it an order_id to determine its place among the tiles o Give it a fitting description that will show up like a tooltip when the tile is hovered over. • For getting a tile, it doesn’t matter what folder the page file is in. Example: ... category: home order_id: 6 ... 3.2. Special case: Working group pages • Landing pages for new working groups need these variables: ... category: workinggroup order_wg-id: 7 ... • The order_wg-id determines at which position among the working group tiles the page will be placed at. 4. A guide for writing content with Markdown Markdown gets converted to HTML when the website is built. This happens according to the rules of the kramdown framework See documentation here: https://kramdown.gettalong.org/quickref.html 4.1. Inline Attributes (Kramdown) In standard Markdown, the range of formatting options is limited. You can’t make links open in a new tab or change the color of text, for example. Writing Markdown that gets compiled into HTML with Kramdown, however, is much more versatile. Using curly brackets ({}), you can add Inline Attributes. These allow you to add attributes to the elements that you are creating with Markdown. See the example below for illustration. 4.1.1. Example: Making links open in a new tab with an inline attribute It’s possible to make links open in new tabs in Markdown without having to use a HTML <a target="_blank> tag. This is accomplished with this code snippet: {:target="_blank"} (Source: GeeksForGeeks) Example: [Link to IZ Website](https://izd2m.hu-berlin.de){:target="_blank"} 4.2. Inline HTML For adding regular content (i.e. text), you should always use Markdown syntax when possible. There are some special cases where you need HTML to create special effects or elements. In this case: 1. Check if there already exists an include for that. 2. If no include already exists, you can ask a developer to add an inline HTML element to your page. The developer will be able to advise you which HTML element will best fit the issue you’re trying to implement. 4.3. Markdown inside of HTML elements When using an inline HTML element, you usually can’t switch back to Markdown syntax before the closing HTML tag of that element. There is a way to work around that, however: If you give the element the attribute markdown="1", you can write normal markdown inside of it and the Kramdown parser will parse it correctly. Example: When you use markdown="1", you can add a heading by using #, ##, etc. and you don’t have to use <h1>,<h2, etc. How to add English content In order to add bilingual content, please follow this procedure: • Put the English file in the folder content_en • It has to be a Markdown file with the following variables in its frontmatter: ... en: true translation: /path-to-german-page.html ... The en variable controls whether automatically generated elements show English text or not. The translation points back to the German page. Make sure that the path to the translated file starts with a / and ends in .html, NOT .md. • A button that says ENor DEis automatically generated if the page as an existing translation variable. File: 02-02-Events-section.md The Event Section Maintenance note: This page will get updated for the new automatic event archiving system (2025-04-05 PB) 1. Introduction The events section keeps our community informed about upcoming events of the IC and its partner institutions. Users can add events to their calendars by downloading ICS files. The underlying data structure of the events section is a collection of Markdown files inside the _events directory. Data for every event (i.e. time, location, etc.) are stored in the frontmatter of its Markdown file. 2. How to add events 2.1. Naming and placing an event file Event files are Markdown files. They need to be named in the following pattern: YYYY-MM-DD-name-of-the-event.md YYYY-MM-DD stand for year, month and day. The ending .md stands for Markdown. Event files need to be placed inside the folder _events. 2.2. How an event file is structured • The metadata for the event are stored in the YAML-frontmatter of the Markdown file. o The frontmatter is the part between the two “---”-lines. • Free-form content for the webpage of the event is stored below the final “---”-line of the metadata. (See section 3 of this wiki page) 2.2.1. Frontmatter template An event should usually have these variables in its frontmatter: --- layout: event event_type: title: organizer: date_from: date_to: location: language: registration: contact: description: programme: series: archived: --- 2.2.2. Event variables/metadata Variable Description Usage notes/Form at Mandatory iCal template Newsletter event_type The category of the event Types in use: Veranstaltun g Arbeitsgrupp e Vortrag Workshop Cookietalk abgesagt The correct spelling and capitalizatio n need to be used. Yes title The official name of the event. Yes SUMMARY Titel date_from The date and time at which the event starts. This variable should have the following format: YYYY-MM-DD hh:mm Yes DTSTART Datum date_to The date and time at which the event starts. This variable should have the following format: YYYY-MM-DD hh:mm Yes DTEND Datum location Where the event takes place Yes LOCATION Ort organizer Who is responsible for the event. When this property has Yes ~~ORGANIZE R;CN=“{{ event.organi zer }}”:mailto:{{~ Veranstalter a value, contact must also be given a value. (see next field) ~~~event.co ntact~~~~}}~ ~ Note: no longer part of the ical template (3.06.2024) contact The email of the organizer to contact about the event. This variable has to be an email. ([email protected] z) Yes ~~ORGANIZE R;CN=“{{ event.organi zer }}”:mailto:{{~ ~~~event.co ntact~~~~}}~ ~Note: no longer part of the ical template (3.06.2024) Kontakt registratio n How to sign up for the event No - Anmeldung 2.3. Event Creation: User Workflow graph TD A[Start] --> B[Identify the metadata of your event] B --> C[Create a new branch to work on] C --> D[Create a new markdown file in the `_events` directory] D --> E[Test the page of the event] E --> F[Test the .ics file of the event] F --> G[Test how the event looks in the event section] G --> H[Merge the test branch into master] 3. Individual event pages For every event, an individual event page is generated. This page displays the metadata in a text box on the left-hand side. Whatever content is added to the Markdown file of the event below the frontmatter is included in the main part of that page (to the right of the metadata box). This is an example of how it looks like: image 4. ICS Template and Script For each event, an ics file is generated. This process is controlled by the following two files: 4.1 ICS template /_includes/ical-template.liquid The ICS template uses Jekyll’s liquid tags, that serve as placeholders for the corresponding data from the specific events front matter. 4.2 Ruby script /ci-cd/generate-ics.rb The ruby script parses the front matter section of the specific events files in the _events folder, renders the above ical template with the data and creates individual ical files, that will be saved in the folder data/ics-files. The script is always executed when updates are pushed to the test branch (see the CI/CD pipeline in .gitlab-ci.yml. File: 02-03-blog.md IZ D2MCM Blog Updated: 2025-09-09, PB Introduction The blog is a central part of the IZ D2MCM website. It is used to share news, updates, and insights related to the IZ D2MCM project Workflow 1. Create a new markdown file in the _posts directory 2. Ensure compliance to naming convention YYYY-MM-DD-bp-shortname.md (e.g. 2025-07-02-bp-izmv.md) 3. Copy frontmatter (see template below) 4. Fill in metadata into the frontmatter 5. Clarify who is author of the post 6. Write post (100-200 words) either in English or German 7. Structure of the post: description, main points and future/next steps (see examples for blogposts here) 8. Add at least one picture or illustration to the post. Use the blog-image Jekyll include to add the image (see bottom part of the template below) 9. Clarify copyright of the picture or illustration, add copyright attribute to the blogimage include. This will create a caption where the copyright symbol © is automatically added. 10. Review the post with all authors 11. Stage the changes and commit them with a meaningful commit message 12. Create merge request 13. Coordinate with the team whether this post should go into the slider Blog template --- layout: post <!-- Do not change. --> title: "abc" description: "abc" <!-- First sentence of the post in one line here --> date: 2024-11-30 <!-- Refers to the publication of the post on the website. --> updated: 2024-11-30 <!-- Refers to the update of the post of the website. --> authors: "Forename Surname, Forename Surename" <!-- list here authors that own the copy right. --> contributors: "Forename Surname" <!-- common case: Carolin Odebrecht, Paul Bayer, Melanie Althage. --> thumbnail: /documents/blog_files/img/YYYY-MM-DD_bp-abc.png <!-- choose an image (.jpg or .png) that illustrates the post. Check naming convention of the files. Check licences. --> tags: "abc" <!-- change. --> --- # Title ## Subtitle Include Description Parameters Include Path JavaScript. contain images. Postershow A section that displays posters related to an event. 3 Parameters: media/postershow.h tml Navigation Include Description Parameters Include Path Event Categories Nav A nav panel of buttons to skip to parts of the events section. JavaScript makes it dynamically become a sidebar when the user scrolls down. No parameters. (Looks really nice!!) navigation/eventcategories-nav.html Events section footer The dark blue part at the bottom of the events section that leads to the events archive. No parameters. navigation/eventssection-footer.html Navigation Icons Include Description Parameters Include Path Archive Navigation Icons Button at the bottom of event archive category pages that link back to the main event archive page. No parameters. navigationicons/archivenavigationicons.html Event Navigation Icons 3 square link buttons at the end of event pages: No parameters. navigationicons/eventnavigationicons.html Navigation Icons 5 square link buttons at the end of a page: No parameters. navigationicons/navigationicons.html WG Navigation Icons 2 square link buttons at the end of working group landing pages: No parameters. navigation-icons/wgnavigationicons.html Sliders Include Description Parameters Include Path Include Description Parameters Include Path Related Posts A variation of the slider (see below) that displays blog posts with the same tag as the page. Currently used for Working Groups. tag: Put page.tag here, or alterantively a string literal of the tag you want to query. sliders/relatedposts.html Slider first_frame, second_frame, third_frame: Pass a string of up to three post or event slugs, divided by comma. Any uniquely identifiable part of the file name will do. For the front page, a data file (izd2mcmwebsite/_data/slid er_settings.yml) is used to pass the strings to the slider. sliders/slider.html Other Includes Include Description Parameters Include Path Footer The footer of all pages. Gives information about contact and legal matters. It also has some declaration of JavaScript scripts, which are part of the underlying Jekyll framework. No parameters. footer.html Head Delivers the <head>- tag for every page. HTML properties such as description are automatically adjusted to the page No direct parameters. Note: head.html makes use of the optional page.excerpt variable for generating a HTML head.html Include Description Parameters Include Path data. description property. If none is provided, it takes site.description instead. Also makes use of page.title for the HTML title tag. Header The header for every page. It shows the IC D2MCM logo and the HU Berlin logo, as well as a button for opening the navigation menu. header.html Ical Template A configuration file for generating ics files. N/A ical-template.liquid Menu A floating openable menu at the top right corner of the website that links to all pages with the variable category: home No direct parameters. Note: Depends on the variable category: home in the pages it should link to. menu.html Slides A helper file for constructing the slider. (see sliders/slider.htm l) No parameters. slides.html Tiles_Home Generates the tiles at the bottom of the landing page that link to the main pages of the IC website (i.e. the pages that have category: home in their frontmatter). When included on an English page such as index_en.html, Takes the en parameter from the page frontmatter. Note: Only pages with the variable category: home will be included in this grid. tiles_home.html Include Description Parameters Include Path the English equivalents of the respective pages will be automatically selected by their translation property. If no translation property is found, it defaults to linking to the German page. Tiles_Workinggroups Generates a tile for every working group landing page (i.e. the pages that have category: workinggroups in their frontmatter). No parameters. Note: Depends on the variable category: workinggroups in the tiles_workinggroups. html Tiles Default tiles. Not in use. No parameters. tiles.html File: 03-03-CSS-Guide.md How CSS works in the IC D2MCM website 1. Introduction CSS (Cascading Style Sheets) is a language for giving browsers instructions on how to render the HTML elements of web pages. Beyond standard CSS, the IC D2MCM website uses the more advanced SASS/SCSS (Sassy CSS) language in its style sheet files1. SASS and SCSS will be used interchangably in this document. The SCSS files are stored within the folder _sass. 1.1. SCSS directory structure • There are four subfolders in the _sass folder: 1. base 2. components 1 Inline CSS still uses the default CSS syntax. 3. layout 4. libs • We mostly work with the components folder for day-to-day adjustments. o The other folders (base, layout and libs) address more fundamental aspects of the site, which should only be tampered with when absolutely neccesary. • The components folder is further divided into subfolder that represent different use cases for the CSS. For example, all the special styles for the events section are in the subfolder events. 1.2. SCSS syntax and features • SCSS allows nested declarations, which is why you often see the & symbol in the code. It stands for “the current selector”. • SCSS allows for an advanced use of variables. • SCSS allows for reusable code blocks (similiar to functions in other programming languages), which are called “mixins”. For more information see the official SCSS documentation: https://sass-lang.com/guide/ 2. Origins of the IC D2MCM styles: The Phantom Jekyll Theme The IC D2MCM website takes both its structure and its style from the Phantom theme by HTML5Up. The IC D2MCM team has expanded and modified parts of this original framework for to fit the specific needs of the IC D2MCM website. Here are some elements the Phantom theme came with: 2.1. Base variables The file”_vars.scss” has default values for fonts, borders. They ensure a uniform look to the different elements of the webiste. You access these variables using the syntax shown in these examples: border-radius: _size(border-radius); background-color: _palette(hu-blue); Here’s a screenshot of some of the variables in “_vars.scss”: 2.2. Breakpoints for Reactivty Web pages look different on phones, on laptops and even in different window sizes. Reactivity to different screen sizes is managed by providing styles for six different screen size breakpoints. When you add a new element, you should always test it in different screen sizes and decide which breakpoints need special rules. This can be accomplished by: 1. Using the inspector mode of your browser and then selecting “Responsive Design Mode”. 2. Running the website on Docker and then typing your IP address, followed by “:4000” in the browser of your phone. (Make sure that both your computer and your phone are in the same network) The screen size breakpoints are pre-defined and are stored in the main CSS file (/assets/css/main.scss): Using breakpoint is recommended over the classic CSS statement @media screen and (max-width: 500px) (using the exaple width of 500px in this instance) Further reading: Skel (the underlying reactivty framework, deprecated in 2018) 2.3. Basic page elements There are many HTML elements that are the same on every page of the IC D2MCM website. The origion of most of these elements is the Phantom theme. Basic structural elements such as the footer, the header and the drop-down navigational menu are styled through files in the _scss/layout folder: image 3. Custom IC D2MCM Designs See the designs in action: https://izd2m.hu-berlin.de/elements.html 3.1. Events Section The events section is a central and essential component of the IC D2MCM website. Click here for a detailed guide to its functionality. The events section uses a layout2 stored in the file “_layouts/events-section.html”. The body element of the page has the class “events-section”. The main element of the events section is a div with the class main-container. It contains a heading, an optional banner, and includes of several “event grids”, which are includes that query and display a specific type of event. The event grids consist of a heading and a div of the class event-grid. As the name implies, they use the modern CSS grid property to place the events on the screen in an orderly way. 3.2. Blog Section The Blog Section is one of the main PR channels of the IC D2MCM. It is where the team posts stories about what happens at the centre, i.e. the activities of working groups, reports from workshops, etc. The Blog Section tightly is tightly integrated with the IZ D2MCM Slider component: Posts can be featured on the home page slider and a special slider with suggested posts sits atop the Blog Section page itself (/blog.md). 3.3. Working Groups Section The Working Groups Section contains the landing pages of the six working groups at the IC D2MCM. Working groups are where researchers from different faculties come together to develop specific shared projects together. As of January 2025, the working group landing pages are quite uniform, but individual styles are possible if the working groups wish them. Further sub-pages are also possible. Infrastructure-wise, the Working Groups Section is structure section is structured as follows: • The page “workinggroups.md” is part of the “home” category3, which means that a tile is generated for it on the home page. o “workinggroups.md” contains tiles itself. Every working group landing page gets a tile that links to it. o These tiles get their CSS from “_sass/components/_tiles.scss”, just like the tiles on the home page. • The working group landing pages take their structure from the layout “_layouts/wglanding-page.html”. They have two elements that only appear under certain conditions: o Related Posts (_includes/sliders/related-posts.html) § This element is a variation of the slider include. It shows posts that share the same tag as the working group. 2 To learn more about layouts, see the Jekyll documentation. 3 The variable “category” is declared in the yaml frontmatter of a page. § Unlike the basic slider, Related Posts has a gray background to make it “pop” from the rest of the page. o Related Events (_includes/content/related-events.html) § This element is a variation of the event section grid but it only shows events which share the same tag as the working group and which are not regular meetings of that working group (determined by event_type: Arbeitsgruppe) Here is a screenshot of Related Posts in action: 3.4. The Home Page (index.md) The Home page is the first page that users see when going to izd2m.hu-berlin.de. The page features optional banners, the slider (see next section), a description of what the IC D2MCM is, and the home page tiles, which link to the main section of the website. Special CSS that should only apply to the home page is stored in: _sass/components/pagestyles/_index-page.scss Screenshots of the home page: 3.5. Slider SCSS file: _sass/components/announcements/_slider.scss implementation of the blog feature implemented not just new content but also several additional features (e.g. the sliders) resulting in the update of the first digit (e.g. v3.0.0). The third digit is supposed to represent (bug) fixes, which is, for now, not heavily in use. In short: • Schema: v0.0.0 > prefix, major, minor, bug fix • Prefix: v • First digit: A major functionality or improvement • Second digit: Content change/small features • Third digit: Bug fix File: 03-07-branches.md Branch Management The branching strategy of this project repository is loosely inspired by the GitHub-Flow strategy. We use a simple system consisting of a regularly updated deployment branch (master), a testing branch (test) and several development branches for new features, content, maintenance updates and fixes. 1. master branch (deployment) The master branch represents the current release state of the IC D2MCM website. This is the branch where the deployment of any changes to the www2 server takes place. It is protected and pushing and merging is only allowed for maintainers and owners of the repository. Before merging and pushing to master, changes should always be tested on the test branch. This branch cannot be deleted. Once per day, a build pipeline is run on the master branch. 2. test branch (testing) The test branch is used for final testing and reviewing of new developments before deployment; corrections can still be made. In addition, the generation of ICS files for events is triggered on this branch. It is protected and pushing and merging is only allowed for owners, maintainers and developers of the repository. After everything works fine on the test branch, the deployment may be initiated by merging to master. This branch cannot be deleted. 3. Feature branches (development) Starting from the test branch multiple feature branches may be created for specific tasks, features, corrections etc. It is advisable to create the feature branches directly from issues. In this way the branch is connected to the description of its purpose. Feature branches may be deleted after the changes have been tested and deployed. Workflow 1. Create an issue on GitLab for the task using the issue templates. Assign yourself and apply the appropriate labels (Priority and remaining labels such as content). 2. Create a branch from the test branch: Schema IssueNumber-Title. Example: 123add-wg-dates. 3. Publish the branch using the VS-Code GitLab function. o The new branch will now be displayed in the issue in the browser. 4. Work on the task. 5. Optionally, test changes locally with Docker. 6. Stage the changes. 7. Commit the staged changes. 8. Push the commits (e.g., using VS Code’s “Sync Changes” function). 9. Create a merge request from your feature branch to the test branch via the GitLab interface. Assign maintainers as assignees. PITFALL: Merge to test, not master! o Settings: Delete source branch. 10. Optionally, wait for authorization. 11. If the _events or _posts folders were modified: o Wait for pipeline outputs. o Check the status in the GitLab web interface on the test branch here <https://scm.cms.hu-berlin.de/izd2mcm-infrastructure/izd2mcm-website/- /jobs?kind=BUILD 12. Test the test branch with Docker. 13. If pipelines are successful: Request merge from test to master. o No complicated title. o No description. o Commit message: Schema merge to master: xyz (summary of all items included in the merge). 14. Very important: Check changes on the live website. For CSS changes: o Optionally, wait a few minutes for the server to update. o Optionally, reload the entire page with Ctrl+Shift+R. File: 03-08-security-configs.md [REMOVED] File: 03-09-event-validation.md Event Validation System The IZ D2MCM website includes a comprehensive event validation system that ensures data integrity and consistency across all event files. This system automatically validates event metadata and helps prevent common errors that could break the website or ICS file generation. Overview The validation system consists of three main components: 1. Validation Script (scripts/ci-cd/validate-events.rb) - The main validation engine 2. Test Suite (scripts/ci-cd/test_validate_events.rb) - Comprehensive tests that ensure the validation script works correctly by testing it against artificial valid and invalid event data 3. CI Integration - Automatic validation in GitLab CI pipeline What Gets Validated Required Fields All event files must include these fields: • layout: Must be “event” • event_type: Type of event (e.g., “Veranstaltung”, “Workshop”, “Seminar”) • title: Event title • date_from: Start date and time • date_to: End date and time • location: Event location Optional Fields The following fields are recognized and validated when present: • contact: Contact information (flexible format) • language: Event language • registration: Registration details • organizer: Event organizer • description: Event description • archived: Boolean flag for archived events • tags: Event tags • translation: Path to translated version • status: Event status (canceled, adjourned, date_changed) • programme: Event program details • series: Event series information • speaker: Speaker information • subtitle: Event subtitle (usually used for talks) • redirect: URL for redirects (Applies when events shouldn’t link to their own page.) • thumbnail: Image path for event thumbnail • thumbnail-adjust: Thumbnail position adjustment • background-image: Background image path (The background image appears at the top of the page) • background-style: CSS injection for styling the background image • en: Boolean for English content • thumbnail_small: Path of the small thumbnail that appears in the little circles in the event cards. Validation Rules Date Validation • Dates must be in valid format (YYYY-MM-DD HH:MM or YYYY-MM-DD) • End date must be after start date • Filename date should match event date Path Validation Local paths (for images, translations, etc.) must start with / to ensure proper linking: • ✅ Good: /images/event-photo.jpg • ❌ Bad: images/event-photo.jpg (causes broken links) Status Validation If present, the status field must be one of: • canceled • adjourned • date_changed File Structure The system supports both: • Full event files with frontmatter and content • Frontmatter-only files (e.g., for external events with redirects) Running Validation Local Validation # From the project root directory ruby scripts/ci-cd/validate-events.rb Test Suite # Run the validation tests ruby scripts/ci-cd/test_validate_events.rb Field Analysis # Analyze field usage across all events ruby scripts/analyze-event-fields.rb CI Pipeline Integration The validation system is fully integrated with the GitLab CI pipeline: 1. validate-events job: Runs validation on all event files 2. test-validation-script job: Runs the test suite 3. icsfiles job: Depends on validation passing before generating ICS files This ensures that: • No invalid events are deployed to the website • ICS file generation only runs with clean data • Data integrity is maintained across all branches Common Validation Errors Path Errors ERROR: Local path 'images/photo.jpg' should start with '/' Fix: Change to /images/photo.jpg Date Errors ERROR: End date must be after start date Fix: Ensure date_to is later than date_from Required Field Errors ERROR: Missing required field: location Fix: Add the missing field to the event frontmatter Status Errors ERROR: Invalid status 'cancelled'. Must be one of: canceled, adjourned, date_changed Fix: Use the correct status value (canceled not cancelled) Example Event File --- layout: event event_type: Workshop title: "Data Visualization with Python" date_from: 2025-07-15 09:00 date_to: 2025-07-15 13:00 location: "UL6, Room 123" contact: "[email protected]" description: "Learn to create compelling data visualizations" language: Deutsch registration: "Please register via email" organizer: "IZ D2MCM" thumbnail: /images/workshops/data-viz-2025.jpg tags: workshop --- Event content goes here... Validation Results Current status of the validation system: • ✅ 110 event files processed • ✅ 0 errors found • ✅ 0 warnings found • ✅ All tests passing (12 tests, 0 failures) For Content Creators When creating new events: 1. Use the event template to ensure all required fields are included 2. Check local paths - make sure they start with / 3. Validate dates - ensure end time is after start time 4. Test locally - run the validation script in the command line before committing: # Ensure you're in the root folder ruby scripts/ci-cd/validate-events.rb For Developers The validation system is extensible and well-tested. These are actions that may be required as the event system keeps evolving: • Add new fields: Update the OPTIONAL_FIELDS or REQUIRED_FIELDS arrays • Add new validation rules: Extend the validation methods • Update tests: Add test cases for new validation logic • CI integration: Validation runs automatically on push to the test branch. Branch rules may have to be reviewed in the future. Troubleshooting Validation Script Won’t Run • Ensure you’re in the project root directory • Check that Ruby is installed and accessible • Verify the scripts/ directory exists False Positives If the validation reports errors for valid content: 1. Check the field is in the recognized fields list 2. Verify the validation logic for that field type 3. Consider if the validation rule needs adjustment CI Failures If validation fails in CI but passes locally: 1. Check for differences in Ruby versions 2. Ensure all files are committed 3. Verify the CI environment has access to all required files The validation system helps maintain high data quality and prevents common issues that could break the website or user experience. File: 03-10-event-frontend.md Event Section Frontend Created: 2025-09-07 This page describes the frontend implementation of the Event Section of the IC D2MCM website. (The backend is a collection of Markdown files stored in the _events folder.) The live version of the events section can be found here: https://izd2m.huberlin.de/content_de/events.html. Appearance of the Events Section Grids The events section is a grid of event cards. This grid is divided into four categories which are highlighted with different background colors: • Upcoming Events (blue) • Cookietalks (yellow) • Events from the RIDSCH network (orange) • Meetings of the working groups (teal) Each of the categories is an instantiation of a Jekyll include called grid-for-eventsgeneric.html. The category-specific parameters (like title, background color, filter criteria for the events to be shown) are passed to the include via Liquid variables. ### Navigation At the top of the events section, there is a navigation bar that allows users to quickly jump to one of the four categories. When scrolling down the page, the top bar becomes a floating side bar on the left side of the screen. The buttons are keyed to the IDs of the category sections. (Example: <a href="#ridsch-events">RIDSCH Events</a>; <section id="ridsch-events">.) The logic for the side bar gets manage through a lightweight JavaScript file (/scripts/javascript/events-section-sidepanel-script.js) The animations are done with CSS. Event Backend See Section 03 11, “Event Backend” for a description of the backend implementation of the events section. File: 03-11-event-backend.md The Backend of the Event Section Created: 2025-09-07 This page describes the backend implementation of the Event Section of the IC D2MCM website. (The frontend is described in this page.) The live version of the events section can be found here: https://izd2m.huberlin.de/content_de/events.html. The Basics: Storage of Event Data with Markdwown Files The data of the events is stored in the _events folder as a collection of Markdown files. Each event has its own Markdown file. Event metadata (like title, date, location, etc.) is stored in the YAML front matter of each file. Automatic Event Archiving Historical note: The IC D2MCM website used to use a field called archived to manually move events to an archive section. This was later replaced by a more automatic approach that uses the event date (date_to) to determine whether an event is in the past or not. How that works is through the custom filter_events plugin. (Path: _plugins/filter_events.rb.) This plugin determines the current date every time the site is built and provides a list of upcoming events and a list of past events. The lists are then used in the frontend to display the events in the appropriate sections. To consistently determine the current date, we set up a pipeline job on GitLab to run every morning at 5am. This job simply triggers a rebuild of the website, which in turn triggers the filter_events plugin to update the event lists. Automatic Validation of Event Data See Section 03 09, “Event Validation” for a description of the automatic validation of event data. File: 03-12-RIDSCH-event-form.md RIDSCH Event form This page briefly documents the backend that powers the RIDSCH event submission form. What it does • Provides an OAuth-protected web form so HU Berlin GitLab users can submit RIDSCH events. • Submissions are turned into a markdown event file and a GitLab issue is created in the RIDSCH events repository for review. Files and purpose • ridsch-event-form.php — main entry: if unauthenticated it builds the GitLab OAuth authorize URL (using oauth-config.php), shows the login button; after login it displays the event form and handles logout. • oauth-callback.php — OAuth callback handler: exchanges the authorization code for an access token, fetches the authenticated user from the GitLab API, stores user + token in session, and redirects back to the form. • ridsch-submit.php — submission processor: validates and sanitises input, generates the event markdown (YAML frontmatter), and creates a GitLab issue (optionally attaching the generated file) via the GitLab API. • oauth-config.php.template — template used during CI deploy; contains placeholders for %%GITLAB_OAUTH_CLIENT_ID%% and %%GITLAB_OAUTH_CLIENT_SECRET%%. The CI pipeline replaces these with protected CI/CD variables to produce oauth-config.php on the server (this file is git-ignored). • .htaccess — webserver access/config rules for the backend directory. Quick flow 1. User visits ridsch-event-form.php and clicks “Login with HU GitLab”. 2. GitLab authorises the app and redirects to oauth-callback.php. 3. After successful auth the user returns to the form, fills it out, and submits. ridschsubmit.php creates the GitLab issue. Deployment notes • CI replaces oauth-config.php.template with real credentials at deploy time; do not commit oauth-config.php (it is ignored). 🔒 Security statement This system is safe because it delegates user authentication entirely to HU Berlin’s GitLab. That means: Arguments The script requires the following command-line arguments, which are masked with GitLab CI/CD variables for security: • --ridsch-url: URL for the RIDSCH SoGo calendar. • --ridsch-username: Username for the RIDSCH calendar. • --ridsch-password: Password for the RIDSCH calendar. • --team-calendar-url: URL for the Team SoGo calendar. • --team-calendar-username: Username for the Team calendar. • --team-calendar-password: Password for the Team calendar. • ics_files: A space-separated list of paths to the .ics files to be processed. Dependencies The script relies on the following Python packages: • caldav: For interacting with the CalDAV server. • icalendar: For parsing .ics files. • pyyaml: For parsing the YAML front matter from Markdown files. File: 03-17-guide-for-a-new-developer.md Workspace setup: • Use Visual Studio Code (VSCode) as your IDE • Clone both the izd2mcm-website repository and the izd2mcm-website.wiki repository to your local machine and put them in the same parent directory. • Open the parent directory in VSCode (not the individual repositories). That way you can easily keep the wiki fresh while working on the main website code (i.e., you modify or remove something and can just references to it with CTRL+SHIFT+F in both the repo and the wiki) • Install Docker (see: Local testing with Docker) o Run docker o Open a terminal in VSCode, type cd izd2mcm-website and ENTER, then run docker compose up o (TODO: Add documentation on how to use plain Jekyll with bundle exec jekyll serve instead of Docker) First steps: • Look at izd2m.hu-berlin.de/elements.html o Here you find all of our custom elements you can use for the website. [UNFINISHED PAGE AS OF 2025-10-28] File: 03-18-dealing-with-german-and-english.md Dealing with German and English Pages This is the guide for developers on how to handle the bilingual nature of the website. We have a path dependency in that we opted for a very specific way to handle the two languages. German is the “normal” language and every German page has an English counterpart with the _en suffix. German content lives in the content_de folder and English content in the content_en folder. Here are some code examples of how to link to the correct page depending on the language of the current page: event-card.html: <a href=" {%- unless event.redirect -%} {%- if page.en and event.translation -%} {{event.translation}} {%- else -%} {{ event.url }} {%- endif -%} {%- else -%} {%- if page.en and event.translation -%} {%- assign translation_slug = event.translation | split: '/' | last | split: '.' | first -%} {%- assign translated_page = site.pages where_exp: "item", "item.path contains 'content_en/events'" | where_exp: "item", "item.path contains translation_slug" | first -%} {%- if translated_page.redirect -%} {{ translated_page.redirect }} {%- else -%} {%- if page.en and event.event_type == "Arbeitsgruppe" - %} {%- assign new_redirect = event.redirect | replace: "content_de", "content_en" | replace: "about", "about_en" -%} {{new_redirect}} {%- else -%} {{ event.redirect }} {% endif %} {%- endif -%} {%- else -%} {%- if page.en and event.event_type == "Arbeitsgruppe" -%} {%- assign new_redirect = event.redirect | replace: "content_de", "content_en" | replace: "about", "about_en" -%} {{new_redirect}} {%- else -%} {{ event.redirect }} {% endif %} {%- endif -%} {%- endunless -%}" > tiles_home.html: {% assign sorted_pages = site.pages | sort: "order_id" | where: "category", "home"%} <!-- Check if English tiles should be shown (include.language)--> {% if include.language == 'en' %} {% assign english_pages = '' | split: '' %} {% for item in sorted_pages %} {% assign english_slug = item.path | split: "/" | last | split: "." | first | append: "_en" %} {% assign english_page = site.pages | where_exp: "page", "page.name contains english_slug" %} {% assign english_page = english_page | first %} {% if english_page %} {% assign english_pages = english_pages | push: english_page %} {% endif %} {% endfor %} {% assign sorted_pages = english_pages %} {% endif %}