Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
169 lines (114 loc) · 7.44 KB

CONTRIBUTING.md

File metadata and controls

169 lines (114 loc) · 7.44 KB

Contributing to the Galaxy Community Hub

The Galaxy Community Hub is the community and documentation website for the Galaxy Project. The site is built with Astro and content is written in Markdown. Anyone can contribute through GitHub.

Quick start

Content lives in the /content/ directory. Most pages are an index.md file inside a directory whose path becomes the URL. News pages are the exception: they route by frontmatter slug, while the filesystem layout is just for organization:

File path URL
content/events/2025-10-20-galaxy-workshop/index.md galaxyproject.org/events/2025-10-20-galaxy-workshop/
content/news/2025/2025-01-galaxy-update/index.md galaxyproject.org/news/2025-01-galaxy-update/

Editing an existing page

The easiest way is to use the edit link on any Hub page — click the GitHub icon in the upper right corner. This takes you to the source file in GitHub where you can edit it directly and submit a pull request.

Creating a new page

In the GitHub web interface, navigate to the appropriate directory under /content/ and click "Add file" → "Create new file". For news items, create the year bucket first, then add your-page-name/index.md inside it (for example content/news/2026/my-news-item/index.md). GitHub will create the directory for you.

Directory naming rules: Use lowercase letters, numbers, and hyphens. The directory name becomes the URL slug.

community/galaxy-south-africa/     ✓
community/GalaxySouthAfrica/       ✗  (camelCase)
events/2025-05-06-spoc_meet/       ✗  (underscore)

A CI lint check enforces these rules on every PR. If your directory name doesn't match, the check will fail and tell you what to rename.

What gets normalized automatically: If a legacy directory has camelCase or underscores, the build normalizes it — GalaxySouthAfrica becomes galaxy-south-africa, spoc_meet becomes spoc-meet. Redirects are generated from the old name.

Letters next to numbers are fine as-is: gcc2026, pag31, lkj34 are all valid and won't be split. You can also write gcc-2026 if you prefer — it's your choice. The normalizer does not insert or remove hyphens at letter-digit boundaries.

Date-prefixed directories (like 2025-10-15-my-event) keep the date prefix unchanged; only the part after the date is normalized.

Writing content

Frontmatter

Each file starts with YAML metadata between --- markers:

---
title: "My Page Title"
---

Common fields:

Field Used in Description
title All pages Page title (required)
date News, events Publication or start date in 'YYYY-MM-DD' format
tease News, events Short description shown in listings
tags All pages Array of tags, e.g. [training, webinar]
autotoc All pages Show table of contents (default: true)
components All pages Set to true to enable interactive components

Events have additional fields:

Field Description
days Duration in days
continent Two-letter code: AF, AS, AU, EU, GL, NA, SA
location Object with name: and optional url:
contact Event contact information
subsites Array of subsites to display on, e.g. [global, eu]

Markdown

Content is written in standard GitHub Flavored Markdown. Prefer Markdown over raw HTML whenever possible — it's easier to maintain and renders more consistently.

Images

Place images in the same directory as your index.md and reference them with relative paths:

![Screenshot](./screenshot.png)

For images shared across pages, use /images/... paths (these are served from content/images/). Example: /images/logos/galaxy_project_logo.jpg.

Contributions metadata and Hall of Fame recognition

For news and event posts, credit organisers and supporters in frontmatter using contributions:

---
title: "My Event"
date: 2026-03-05
contributions:
  organisers:
    - bgruening
    - deNBI
  funding:
    - deNBI         # organisation
    - elixir-europe # organisation
    - eosc-life     # grant
    - edctp-eu      # grant
---
  • contributions.organisers supports contributor and organisation IDs
  • contributions.funding supports organisation and grant IDs, and can include multiple funders
  • IDs should come from CONTRIBUTORS.yaml, ORGANISATIONS.yaml, and GRANTS.yaml shared with the GTN, please edit them directly in the GTN repository.

This metadata is used to build recognition on the Hub, including /hall-of-fame/ listings and each profile's attributed news/event contributions.

Using components

The Hub provides interactive components like icons, video embeds, and social media embeds. To use them, add components: true to your frontmatter:

---
title: "My Page"
components: true
---

Check out this tool: <Icon name="laptop" />

<Twitter user="galaxyproject" />

<VegaEmbed spec="chart.json" />

Available components: Icon, VegaEmbed, Twitter, Mastodon, VideoPlayer, Carousel, Flickr, Supporters, Contacts, MarkdownEmbed, CalendarEmbed, Insert.

Important: Files with components: true are processed as MDX, which means a few things that work in regular Markdown need different syntax:

  • Use {/* comment */} instead of <!-- comment -->
  • Avoid bare <> (use &lt;&gt;)
  • Escape angle brackets before numbers like <500 (use &lt;500)

The content:lint check will catch files where components: true is missing or unnecessary.

Running locally

For previewing changes beyond what GitHub's preview offers:

git clone https://github.com/your-username/galaxy-hub.git
cd galaxy-hub
make dev

This starts a dev server at http://localhost:4321 with hot reload. See astro/README.md for build, test, and lint commands.

Before opening a PR, run:

make content-lint
make validate-metadata

Note: The dev server is case-insensitive for URLs but production is case-sensitive. Always use lowercase URLs.

Submitting changes

  1. Fork the repository and create a branch
  2. Make your changes
  3. Submit a pull request with a description of what you changed and why

After a PR or two, maintainers will add you to the Editors group so you can commit directly.

License

The content of the Galaxy Hub is licensed under the Creative Commons Attribution 4.0 International License. The code is licensed under the MIT License.