Markdown Tips

These are some tips for writing content on the Hub, including things to know when you need to go beyond basic Markdown.

Basics

Content is written in GitHub Flavored Markdown (GFM). This covers headings, bold, italics, links, lists, tables, code blocks, and images. Prefer Markdown over raw HTML whenever possible — it’s easier to maintain and renders more consistently across the site.

Images

Include images in your .md files with standard Markdown syntax:

![alt text](/images/hub/contributing/markdown/image.jpg)

Place the image in the same directory as your index.md. The build system will copy it to the right place and rewrite the path automatically.

For images shared across multiple pages, put them in content/images/ and reference with an absolute path:

![galaxy logo](/images/logos/galaxy.jpg)

Posts from X (Twitter)

The Hub does not embed tweets. To show a post, save a screenshot of it next to your index.md and include it as an image. Put the author and the post text in the alt text, set width and height to half the image’s pixel size so a high-resolution screenshot is not stretched, and add a short caption with the author and date:

<img src="/images/hub/contributing/markdown/tweet-1234567890.webp" alt="Post by Galaxy Project (@galaxyproject): Galaxy 25.0 is out!" width="550" height="560" />

*Post by @galaxyproject on 12 May 2025*

Inserting HTML

You can use HTML in your .md files, but keep it separate from Markdown — put a blank line between blocks of Markdown and blocks of HTML. Mixing them on the same line can produce unexpected results.

A common use is wrapping content in a styled <div>:

<div class="float-right" style="width: 200px">

![alt text](/images/hub/contributing/markdown/image.jpg)

</div>

Components

The Hub has interactive components for common embeds. To use them, add components: true to your frontmatter:

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

Then use component tags in your content:

<Icon name="laptop" />

<VegaEmbed spec="chart.json" />

<VideoPlayer src="./demo.mp4" />

Available components

Component	Purpose	Example
`Icon`	Lucide icon	`<Icon name="laptop" />`
`VegaEmbed`	Vega-Lite chart	`<VegaEmbed spec="chart.json" />`
`Mastodon`	Mastodon embed	`<Mastodon url="..." />`
`VideoPlayer`	Video player	`<VideoPlayer src="./video.mp4" />`
`Carousel`	Image carousel	`<Carousel />`
`Flickr`	Flickr album	`<Flickr />`
`Supporters`	Supporter logos	`<Supporters />`
`Contacts`	Contact list	`<Contacts />`
`MarkdownEmbed`	Embed markdown	`<MarkdownEmbed />`
`CalendarEmbed`	Calendar widget	`<CalendarEmbed />`
`Insert`	Inline content snippet	`<Insert name="/path/to/snippet" />`

MDX compatibility notes

Files with components: true are processed as MDX, which adds a few restrictions compared to plain Markdown:

Comments: Use “ instead of . HTML comments will cause a build error in MDX files.
Bare angle brackets: <> must be written as <>.
Less-than before numbers: <500 looks like a JSX tag to the MDX parser. Use <500 or put it in backticks: `<500`.

These restrictions only apply to files with components: true. Regular Markdown files are not affected.

Icon names

Icons use the Lucide icon library. Browse the full set at lucide.dev/icons and use the icon name in the name attribute:

<Icon name="laptop" />
<Icon name="calendar" />
<Icon name="external-link" />

Lists

If you’re adding a sublist, indent it four spaces:

1. Item one
2. Item two
    * Subitem A
    * Subitem B
3. Item three

File download links

To link to a downloadable file, place it in content/media/ (for non-images) or content/images/ (for images) and use an absolute path:

[click to download](/media/paper.pdf)

Relative paths to files in the same directory also work for images and PDFs that live alongside the content.