Component Usage Guide

This guide is designed specifically to understand how to incorporate and use new components within articles effectively. This resource is not publicly available and can only be accessed through direct links shared within our editorial team.

Important Notes on Using MDX

To use Astro components like Card and Separator in your articles, you will need to ensure a couple of things:

File Extension: Change the file extension from .md to .mdx. This change allows the Astro framework to process the file as an MDX document, enabling the embedding of interactive components directly within the content.
Import Components: At the beginning of your .mdx file, import each component you plan to use. Here is an example of how to import components:

import Card from 'src/components/Card.astro';
import Link from 'src/components/Link.astro';

Components usage

Button

The Button component renders an HTML <button>, or an <a> when given an href.

label: Optional text label. Omit for an icon-only button.
icon / iconEnd: Optional leading and/or trailing icon. Accepts a class name (e.g. iconEnd="fa-solid fa-caret-down" for a dropdown button) or a URL to an SVG.
size: Optional: medium (default), small, or xSmall.
importance: Optional: default or loud
disabled: Optional true/false
href: Optional. When set, the button renders as a link rather than a <button>.
type: Optional: button (default), submit, or reset. Ignored when href is set.
as: Optional: button (default) or summary. Use summary for a button that opens a <details> disclosure. Ignored when href is set.

An icon-only button has no visible text, so include an aria-label to give it an accessible name.

Any other attribute is passed through to the rendered element, so a class of your own reaches the button and you can position or reshape it from the parent component. Astro scopes each component’s <style> to its own markup, so a rule aimed at that class needs :global() to cross into Button — keep it behind a scoped ancestor (e.g. .my-toolbar :global(.my-toolbar__action) { ... }) so it stays contained. Never copy the btn classes into your own markup: the styles are scoped to Button and will not apply.

<Button label="Label" />
<Button label="Label" size="small" />
<Button label="Label" size="xSmall" />

Button with icons

<Button label="Copy" icon="fa-solid fa-copy" />
<Button
  label="Label"
  icon="fa-solid fa-copy"
  iconEnd="fa-solid fa-caret-down"
/>
<Button label="Actions" iconEnd="fa-solid fa-caret-down" />
<Button icon="fa-solid fa-gear" aria-label="Settings" />

Links

Docs Docs Next Start

<Button label="Docs" href="/docs" />
<Button label="Docs" href="/docs" disabled={true} />
<Button label="Next" href="/docs" iconEnd="fa-solid fa-arrow-right" />
<Button label="Start" href="/docs" importance="loud" />

Disabled

<Button
  label="Label"
  icon="fa-solid fa-copy"
  iconEnd="fa-solid fa-caret-down"
  disabled={true}
/>
<Button label="Label" size="small" disabled={true} />
<Button label="Label" size="xSmall" disabled={true} />

SplitButton

A Button with a second, narrower half that opens a menu of related actions. It has the same anatomy and tokens as Button, so it takes the same icon, size and importance, and adds the menu.

label / href / icon: The primary action, passed straight to Button. The primary is always a link.
items: The menu, as an array of { label, href, icon?, iconEnd? }. Icons take the same values Button’s do: a class name or a URL to an SVG.
menuLabel: Required. The caret half has no text, so this gives it an accessible name.
size / importance: Optional, applied to both halves so they stay the same height.
target / rel: Optional, applied to the primary and every menu item.

The menu closes on Escape or a click outside, and opens towards whichever side has room, so it does not need positioning from the parent. Convention is to repeat the primary action as the first menu item, as a split button’s two halves should never offer a different set of actions.

Give it a class of your own to style what you passed in: the icons land on elements SplitButton renders, so a rule aimed at them needs :global() behind that class.

Reach for a class name rather than a URL when the icon is one of the design system’s. Those assets are drawn in currentColor, and an <img> gives them nothing to take a color from, so they come out black in both themes. A class whose rule masks the asset and sets background-color: currentColor picks up the color the button gives its icon box instead.

Two of them sit side by side below, each with its own menu, so it is clear that a menu belongs to the control it hangs from.

Open in Claude

Copy

<SplitButton
  label="Open in Claude"
  href="/some/url"
  icon="my-icon my-icon--claude"
  menuLabel="Open in another assistant"
  items={[
    { label: 'Open in Claude', href: '/some/url', icon: 'my-icon my-icon--claude', iconEnd: 'my-icon my-icon--external' },
    { label: 'Open in ChatGPT', href: '/another/url', icon: 'my-icon my-icon--chatgpt', iconEnd: 'my-icon my-icon--external' },
  ]}
/>

Avatar

<Avatar size="medium" shape="circle">JD</Avatar>
<Avatar size="medium" shape="rounded">JD</Avatar>
<Avatar size="medium" shape="circle" isMuted={true}>JD</Avatar>
<Avatar size="medium" shape="circle" src="/path/to/image.png" alt="">JD</Avatar>

TopNav

Temporary showcase for the new, work-in-progress TopNav component.

Changelog Sign in Start for free

Card

The Card component displays content in a card format, suitable for highlights, features, or related topics.

Example Title

Example description of the feature.

<Card
  title="Example Title"
  description="Example description of the feature."
  imgSrc="/docs/img/octopus-deploy-logo.png"
  imgAlt="Example Alt Text"
  link="/docs/deployments/kubernetes"
/>

<Card
  imgAlt="Example Alt Text"
  imgSrc="/docs/img/octopus-deploy-logo.png"
  link="https://www.youtube.com/watch?v=example"
  title="Watch Our Tutorial"
  variant="related-topics"
/>

<Card
  imgAlt="Example Alt Text"
  imgSrc="/docs/img/octopus-deploy-logo.png"
  link="/docs/deployments/kubernetes"
  title="Watch Our Tutorial"
  variant="related-topics"
/>

Card padded

Padded Example Title

Example description with added padding for emphasis.

<Card
  description="Example description with added padding for emphasis."
  imgAlt="Example Alt Text"
  imgSrc="/docs/img/octopus-deploy-logo.png"
  link="/docs/deployments/kubernetes"
  title="Padded Example Title"
  variant="padded"
/>

IconTile

The IconTile component is used for creating clickable tiles with an icon, a title, and a description.

iconAlt: Alternative text for the icon (not required with font awesome icon)
title: Keep it short for this component
description: Keep it short for this component

Kubernetes Deployment

Learn more about deploying applications with Kubernetes using Octopus Deploy.

<IconTile
  description="Learn more about deploying applications with Kubernetes using Octopus Deploy."
  iconSrc="/docs/img/octopus.svg"
  iconAlt="Example Alt Text"
  link="/docs/deployments/kubernetes"
  title="Kubernetes Deployment"
/>

Kubernetes Deployment

<IconTile
  iconSrc="/docs/img/octopus.svg"
  iconAlt="Example Alt Text"
  link="/docs/deployments/kubernetes"
  title="Kubernetes Deployment"
/>

Image

<Image src="/docs/img/octopus.svg" alt="Example Alt Text" />

Image with caption

<Image
  src="/docs/img/octopus.svg"
  alt="Example Alt Text"
  caption="Example caption"
/>

Link

The Link component is designed to provide a standardized way to display links with icons

iconAlt: Alternative text for the icon (not required with font awesome icon)
noFollow: Optional; Accepts true/false values. If true, adds rel="nofollow" to the link
newTab: Optional;; Accepts true/false values. If true, the link opens in a new tab target="_blank".

Link with Icon Example

<Link
  link="/docs/deployments/kubernetes"
  text="Link with Icon Example"
  icon="/docs/img/icon-example.svg"
  iconAlt="Example Icon Description"
/>

Code block

Every fenced code block is given a header carrying its language and a copy button. There is no component to import, so this works in .md as well as .mdx.

Label

Text after the language on the opening fence becomes the block’s label. Write one that says what the code does; the language is already shown on the right.

```powershell Write a release marker into the repository
Write-Host "Hello, World!"
```

Write-Host "Hello, World!"

Without a label, the header carries the language and the copy button alone.

Write-Host "Hello, World!"

Several languages

Wrap one fence per language in <details> elements sharing a data-group. Each <summary> names its language, and the header offers them in a menu.

<details data-group="components-code-block">
<summary>PowerShell</summary>

```powershell Rename a deployment target
$machine = $repository.Machines.Get("machines-1");
```

</details>
<details data-group="components-code-block">
<summary>C#</summary>

```csharp Rename a deployment target
var machine = repository.Machines.Get("machines-1");
```

</details>

PowerShell

$machine = $repository.Machines.Get("machines-1");
$machine.Name = "Test Server 1";
$repository.Machines.Modify($machine);

var machine = repository.Machines.Get("machines-1");
machine.Name = "Test Server 1";
repository.Machines.Modify(machine);

A group whose panels hold anything besides a single code block stays a tab list.

Long blocks

A block over 500px tall collapses, fading out at the cut. Clicking the code expands it, and clicking away collapses it again.

steps:
  - name: Approve the release
    action: manual-intervention
    instructions: Check the release notes before approving.
  - name: Deploy to the cluster
    action: kubernetes-deploy-raw-yaml
    package: octopus/hello-world
    namespace: production
  - name: Smoke test
    action: run-a-script
    script: |
      $response = Invoke-WebRequest -Uri "https://example.com/health"
      if ($response.StatusCode -ne 200) { throw "Unhealthy" }
  - name: Notify the team
    action: send-email
    to: releases@example.com
    subject: Deployed #{Octopus.Release.Number}
  - name: Tag the release
    action: run-a-script
    script: |
      git tag "release/#{Octopus.Release.Number}"
      git push origin --tags
  - name: Update the changelog
    action: run-a-script
    script: |
      Add-Content CHANGELOG.md "#{Octopus.Release.Number}"
  - name: Close the change request
    action: run-a-script
    script: |
      Invoke-RestMethod -Method Post -Uri "https://example.com/changes/close"

Layout

Grid

2 columns

<div class="docs-home simple-grid">
  <Card
    imgAlt="Example Alt Text"
    imgSrc="/docs/img/octopus-deploy-logo.png"
    link="https://www.youtube.com/watch?v=example"
    title="Watch Our Tutorial"
    variant="related-topics"
  />
  <Card
    imgAlt="Example Alt Text"
    imgSrc="/docs/img/octopus-deploy-logo.png"
    link="https://www.youtube.com/watch?v=example"
    title="Watch Our Tutorial"
    variant="related-topics"
  />
</div>

3 columns

Deployments

Learn more about deploying

Deployments

Learn more about deploying

Deployments

Learn more about deploying

<div class="docs-home simple-grid-3">
  <IconTile
    description="Learn more about deploying applications with Kubernetes using Octopus Deploy."
    iconSrc="/docs/img/octopus.svg"
    iconAlt="Example Alt Text"
    link="/docs/deployments/kubernetes"
    title="Kubernetes Deployment"
  />
  <IconTile
    description="Learn more about deploying applications with Kubernetes using Octopus Deploy."
    iconSrc="/docs/img/octopus.svg"
    iconAlt="Example Alt Text"
    link="/docs/deployments/kubernetes"
    title="Kubernetes Deployment"
  />
  <IconTile
    description="Learn more about deploying applications with Kubernetes using Octopus Deploy."
    iconSrc="/docs/img/octopus.svg"
    iconAlt="Example Alt Text"
    link="/docs/deployments/kubernetes"
    title="Kubernetes Deployment"
  />
</div>