Rich Content Showcase: Markdown Embed Examples

This article demonstrates every rich content directive available in our Markdown articles. Use this as a reference guide when writing articles. None of these require MDX — they all work in plain .md files.

---

#Video Embeds

#YouTube

Drop a YouTube video into any article with ::youtube{id="VIDEO_ID"}. The video ID is the part after v= in the YouTube URL.

Here’s the GSF Global Summit 2024 keynote:

You can also link to a specific start time (in seconds):

And here’s one using a short youtu.be-style ID:

Syntax reference:

::youtube{id="VIDEO_ID"}
::youtube{id="VIDEO_ID" start="120" caption="Optional caption text"}

---

#Google Embeds

These are particularly useful for reports, presentations, and data that we already maintain in Google Workspace.

#Google Slides

Perfect for embedding presentations and decks directly in articles. The writer just needs the presentation ID from the URL (the long string between /d/ and /edit).

Another example — the GSF Global Summit Tokyo presentation:

Syntax reference:

::google-slides{id="PRESENTATION_ID"}
::google-slides{id="PRESENTATION_ID" caption="Optional caption"}

#Google Docs

Embed a document for inline reading — great for policy documents, submissions, or shared reports.

Syntax reference:

::google-docs{id="DOCUMENT_ID"}
::google-docs{id="DOCUMENT_ID" title="Accessible title" caption="Optional caption"}

#Google Sheets

Useful for embedding data tables, carbon calculations, or research data.

Syntax reference:

::google-sheets{id="SPREADSHEET_ID"}
::google-sheets{id="SPREADSHEET_ID" caption="Optional caption"}

#Google Drive Files (PDFs, reports, etc.)

For files hosted on Google Drive (like our annual reports), use ::google-drive. This embeds the Google Drive preview viewer, which handles PDFs, images, and many other file types.

Here’s the 2022 annual report too:

Syntax reference:

::google-drive{id="FILE_ID"}
::google-drive{id="FILE_ID" caption="Optional caption"}

---

#PDF Embeds

For PDFs hosted elsewhere (not on Google Drive), use ::pdf. This embeds the browser’s native PDF viewer with a download fallback.

Syntax reference:

::pdf{src="https://example.com/paper.pdf" title="Accessible title"}
::pdf{src="/local/path/to/file.pdf" title="Local PDF" caption="Optional caption"}

---

#Buttons (CTAs)

Use ::button to add a centred call-to-action button anywhere in an article. Two variants are available: primary (filled) and outline.

Syntax reference:

::button{href="/path/" label="Button text"}
::button{href="/path/" label="Button text" variant="outline"}

---

#Rich Link Cards

Use ::link-card to create a visually rich link preview — like how Notion or Slack unfurl links. Provide the metadata yourself for full control.

Can AI Truly Be Green?Exploring the environmental impact of artificial intelligence and what the green software community can do about it.greensoftware.foundation

With an image:

Green Software PatternsAn online open-source database of software patterns reviewed and curated by the Green Software Foundation across a wide range of categories.patterns.greensoftware.foundation

Syntax reference:

::link-card{href="URL" title="Title" description="Description text"}
::link-card{href="URL" title="Title" description="..." image="https://example.com/og-image.png"}

---

#Article Cross-Links (Auto-Reading)

The ::article directive is the easiest way to link to another GSF article. Just provide the slug — the title and summary are automatically read from the article’s frontmatter at build time. No need to type them out.

GSF Announces Executive Director TransitionWe're sharing an important leadership update and what's ahead for the Foundation.greensoftware.foundation

After Five Years, I'm Stepping Down as Executive Director of the Green Software FoundationA personal message from Asim Hussain to the GSF community. greensoftware.foundation

Celebrating the Graduation of the Carbon Aware SDKWe recognize and appreciate the contributions from Avanade, Microsoft, UBS and NTT DATA in helping us achieve this milestone. greensoftware.foundation

Syntax reference:

::article{slug="article-slug-here"}

The slug is the folder name of the article in src/content/articles/en/. That’s it — one line, and you get a styled card with the real title and summary pulled automatically.

---

#Content Cards

Wrap any Markdown content in a :::card container to give it a bordered card treatment. Useful for highlighting key information, quotes, or callouts.

You can also nest embeds inside cards:

Syntax reference:

:::card
Any **Markdown** content here — headings, lists, images, even other embeds.
:::

---

#Combining Everything

Here’s a realistic example of how you might use these in an actual article section:

---

#Our 2024 Annual Report is Live

We’re proud to share the Green Software Foundation’s 2024 Annual Report, covering our progress across standards, tooling, and community growth.

Watch the highlights from our Global Summit where we presented these results:

---

#Existing Features (still available)

These were already supported before the embed directives — they still work exactly the same.

#GitHub-style Alerts

#Callout Blocks (legacy)

#Tables (GFM)

Directive	Type	Use Case
::youtube	Video	YouTube embeds
::vimeo	Video	Vimeo embeds
::google-slides	Document	Presentations
::google-docs	Document	Documents
::google-sheets	Document	Spreadsheets
::google-drive	Document	Drive files (PDFs, etc.)
::pdf	Document	External PDFs
::button	Interactive	CTA buttons
::link-card	Interactive	Rich link previews
:::card	Layout	Content card wrapper

#Math (KaTeX)

The SCI formula: $SCI = ((E \times I) + M)$ per functional unit $R$.

---

#Quick Reference for Writers

Video: Just need the video ID from the URL.

::youtube{id="dQw4w9WgXcQ"}
::youtube{id="dQw4w9WgXcQ" start="60" caption="Starting at 1 minute"}

Google Workspace: Just need the document ID from the URL.

::google-slides{id="LONG_ID_HERE"}
::google-docs{id="LONG_ID_HERE"}
::google-sheets{id="LONG_ID_HERE"}
::google-drive{id="LONG_ID_HERE"}

PDF: Full URL to the PDF file.

::pdf{src="https://example.com/paper.pdf" title="Paper Title"}

Buttons: Centre-aligned call-to-action.

::button{href="/path/" label="Click Me"}
::button{href="/path/" label="Click Me" variant="outline"}

Link cards: Rich preview card.

::link-card{href="URL" title="Title" description="Description"}

Article cross-link: Auto-reads title and summary from frontmatter.

::article{slug="article-folder-name"}

Content card: Wrap anything in a card.

:::card
Your content here.
:::

All directives also accept an optional caption="..." attribute for a styled caption below the embed.