Publishing guidelines

This guide explains how to prepare NAIF news posts and event pages. It is written for project partners and anyone contributing content.

Who we are writing for

Primary audiences

  • NAIF project partners: shared alignment, progress transparency, coordination signals (public-facing).
  • swissuniversities: public reporting, relevance for the sector, evidence of progress.
  • ETH Board and other governance stakeholders: strategic value, interoperability outcomes, sustainability pathway.

Secondary audiences

  • Researchers, libraries, repository teams, the open science community, and the interested public.

A simple structure that works well

  • Why it matters: interoperability, metadata quality, responsible indicators, findability of Swiss research.
  • What we did: activities, methods, consultations, analyses.
  • What we found: interim insights, constraints, recommendations.
  • What’s next: planned actions, opportunities to engage, upcoming events.
  • What to reuse: outputs with persistent identifiers (DOIs, ROR, ORCID references as relevant).

Where content goes

  • News posts: posts/<yyyy-mm-dd>-<slug>/index.qmd
  • Events: events/<yyyy-mm-dd>-<slug>/index.qmd
  • Images for a post go in that post’s images/ folder.
  • Images for an event go in that event’s images/ folder.
  • Do not edit files in _site/.

Language and spelling

  • Use British English for news posts and for event pages that are not reposts.
  • Use sentence case for page titles and section headings by default.
  • Preserve official branded styling for proper nouns, acronyms, and formal event names.
  • Reposts may keep the original wording and spelling when needed.

News post guidance

Use a news post for updates, findings, progress reports, or opinion pieces.

Required information at the top of the page

  • title (<= 70 chars; use sentence case unless it reproduces an official branded name)
  • subtitle (optional; concise one-line context)
  • date (YYYY-MM-DD)
  • author
  • description (<= 280 chars)
  • other-links (when there is a related event page)
  • categories: choose one of Track 1, Track 2, Track 3, Track 4, General
  • tags: exactly 3 tags
  • proofread: true or false
  • image: path to a local image

Writing tips

  • Put the teaser in description.
  • Do not add a separate lead section at the start of the page.
  • Follow the simple structure above.
  • Keep the post concise.
  • If you are not using automatic references, add links in the text or use a ## Sources or ## Further reading section.
  • Use academic titles (Dr, Prof, etc.) consistently where known.

Event guidance

Use an event page for announcements and for documenting past events.

Required information at the top of the page

  • title (<= 70 chars; use sentence case unless it reproduces an official branded name)
  • date (YYYY-MM-DD)
  • author (organiser name)
  • author-title: Organizer
  • description (<= 280 chars)
  • other-links (when there is a related post page)
  • categories: choose one of Organised by NAIF, Participation by NAIF, or Related Topic
  • tags: exactly 3 tags
  • proofread: true or false
  • image: path to a local image

Event details to include

  • Include the date and, where available, the time, location, registration link, and event page.
  • For future events, keep the registration and event page links clickable.
  • For past events, show old registration links as plain crossed-out text and add a short note that the event has already taken place.
  • If a detail is not available, say so plainly.

Images and rights

  • Use 1-3 good-quality images where possible.
  • Every image needs alt text, a caption, and a note on rights or source.
  • For inline images, write ![Caption incl. credit](path){fig-alt="..."}: the bracket text is the visible caption, fig-alt holds the alt text. fig-cap= is not a valid attribute on markdown images and is silently dropped, so never use it.

Reposts of external content

  • Republishing material that has already appeared elsewhere requires permission from the original publisher.
  • Add a visible note near the top linking back to the original URL.

External mentions

  • Brief mentions of NAIF in newsletters, partner blogs, or internal channels should be added to mentions/items.yml.
  • Use that page for short notices and link collections. Use a full news post only when we republish the original text with permission.

Drafts

  • Use draft: true for work in progress.
  • Drafts appear in preview, but not in the published site.

Reuse and identifiers

  • Add stable identifiers such as DOIs, ROR IDs, or ORCID iDs when they are useful.
  • NAIF deliverables are archived on Zenodo: Zenodo community

Templates

News post template

---
title: "<Title (<= 70 chars)>"
subtitle: "<Short one-line subtitle (optional)>"
date: "YYYY-MM-DD"
author:
  - name: "<Author name>"
    orcid: "<0000-0000-0000-0000>"
    affiliation: "<Affiliation>"
description: "<Lead / teaser (<= 280 chars)>"
other-links:
  - text: "Related event: <Event title>"
    href: "../../events/<yyyy-mm-dd-slug>/"
categories:
  - "Track 1" # or: Track 2, Track 3, Track 4, General
tags:
  - "<tag 1>"
  - "<tag 2>"
  - "<tag 3>"
proofread: false
image: "images/<listing-card-image>"
image-alt: "<Describe the image for screen readers>"
image-caption: "<Caption with rights attribution>"
toc: true
---

<!--
Checklist (manual):
- Title <= 70 characters
- Title uses sentence case unless it reproduces an official branded name
- Text 500-3000 characters (guideline)
- British English spelling and style (unless this is a repost)
- `lang: en-UK` if page-level language metadata is set
- Optional subtitle: concise one-line context
- Teaser <= 280 characters
- Exactly 1 category: Track 1-4 or General
- Exactly 3 tags
- 1-3 images, each with alt text + caption + rights attribution
- Proofread true/false is set
- Optional: author portrait, institution portrait (<= 280 chars each)
- References section only when using Pandoc citeproc (`bibliography` + `[@key]`)
-->

## Why it matters

<Write the post>

![Caption. Rights: ...](images/<image>.jpg){fig-alt="Alt text describing the image content"}

Event template

---
title: "<Title (<= 70 chars)>"
date: "YYYY-MM-DD"
author: "<Organizer name>"
author-title: "Organizer"
description: "<Teaser (<= 280 chars)>"
other-links:
  - text: "Related post: <Post title>"
    href: "../../posts/<yyyy-mm-dd-slug>/"
categories:
  - "Organised by NAIF" # or: Participation by NAIF, Related Topic
tags:
  - "<tag 1>"
  - "<tag 2>"
  - "<tag 3>"
proofread: false
image: "images/<listing-card-image>" # For NAIF-run events you may use: ../../images/logos/all-logos.jpg
image-alt: "<Describe the image for screen readers>"
image-caption: "<Caption with rights attribution>"
toc: true
---

<!--
Checklist (manual):
- Title <= 70 characters
- Title uses sentence case unless it reproduces an official branded name
- Text 500-3000 characters (guideline)
- British English spelling and style (unless this is a repost)
- `lang: en-UK` if page-level language metadata is set
- Teaser <= 280 characters
- Exactly 1 category: Organised by NAIF, Participation by NAIF, or Related Topic
- Exactly 3 tags
- 1-3 images, each with alt text + caption + rights attribution
- Proofread true/false is set
-->

## Details

- Date:
- Time: <optional>
- Location: <optional>
- Registration: <https://example.org/registration> (or plain text if not offered)
- Event page: <https://example.org/event> (if available)

## About

<Describe the event>

Code of conduct

All contributors are expected to follow this repository’s code of conduct: CODE_OF_CONDUCT.md.