Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions src/assets/icons/arrow-down-left.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
3 changes: 3 additions & 0 deletions src/assets/icons/arrow-up-right.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
3 changes: 3 additions & 0 deletions src/assets/icons/pen-line.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
3 changes: 3 additions & 0 deletions src/assets/icons/xmark.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
54 changes: 54 additions & 0 deletions src/pages/components.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -250,6 +250,60 @@ Two of them sit side by side below, each with its own menu, so it is clear that
</div>
</div>

### API method badge

A badge marks a piece of documentation with the HTTP method it describes. Each
method carries its own icon and colour, in both light and dark themes.

There is no component to import. The styles live in `src/styles/api.css`, which
every page loads, so this works in `.md` as well as `.mdx`.

One class does the work: `api-get`, `api-post`, `api-delete` or `api-put`. It
carries the colours and draws the icon from a `::before`, so the only thing to
write is the label.

<div class="docs-home simple-grid">
<div class="btn-row">
<span class="api-get">Get</span>
<span class="api-post">Post</span>
<span class="api-delete">Delete</span>
<span class="api-put">Put</span>
</div>
<div>
```html
<span class="api-get">Get</span>
<span class="api-post">Post</span>
<span class="api-delete">Delete</span>
<span class="api-put">Put</span>
```
</div>
</div>

#### Icon only

Add `api-icon-only` for the icon on its own. There is no text left to read, so
name it with `role="img"` and an `aria-label`.

<div class="docs-home simple-grid">
<div class="btn-row">
<span class="api-get api-icon-only" role="img" aria-label="Get"></span>
<span class="api-post api-icon-only" role="img" aria-label="Post"></span>
<span class="api-delete api-icon-only" role="img" aria-label="Delete"></span>
<span class="api-put api-icon-only" role="img" aria-label="Put"></span>
</div>
<div>
```html
<span class="api-get api-icon-only" role="img" aria-label="Get"></span>
<span class="api-post api-icon-only" role="img" aria-label="Post"></span>
<span class="api-delete api-icon-only" role="img" aria-label="Delete"></span>
<span class="api-put api-icon-only" role="img" aria-label="Put"></span>
```
</div>
</div>

The badge is `inline-flex`, so it sits inside a heading or a paragraph as well
as it does on its own.

### TopNav

Temporary showcase for the new, work-in-progress TopNav component.
Expand Down
82 changes: 82 additions & 0 deletions src/styles/api.css
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
:is(.api-get, .api-post, .api-delete, .api-put) {

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suspect that the API layout will have more "non-astro" components that will need styling, so I opted to have a new file separate from main.

@borland borland Aug 13, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice. I was thinking it'd be cool if we could have a very-mini "api docs" site within the OctopusDeploy repo to optionally help developers see what the docs MD changes will look like when rendered. Probably we won't do it, but keeping API css separate would make it easier if we did

box-sizing: border-box;
display: inline-flex;
align-items: center;
justify-content: center;
gap: var(--space4);
padding-block: calc(var(--space2) - var(--borderWidth1));
padding-inline: calc(var(--space2) - var(--borderWidth1))
calc(var(--space4) - var(--borderWidth1));
border: var(--borderWidth1) solid;
border-radius: var(--borderRadiusSmall);
max-width: fit-content;
font-family: var(--fontFamilySystem-ui-monospace);
font-size: var(--fontSizeXSmall);
font-weight: 400;
line-height: var(--lineHeightXSmall);
letter-spacing: var(--letterSpacingNone);
vertical-align: middle;
white-space: nowrap;
}

:is(.api-get, .api-post, .api-delete, .api-put)::before {
content: '';
flex-shrink: 0;
width: 1rem;
height: 1rem;
background-color: currentColor;
mask-position: center;
mask-repeat: no-repeat;
}

.api-icon-only {
padding-inline-end: calc(var(--space2) - var(--borderWidth1));
}

.api-get {
border-color: var(--colorApiBadgeBorderGet);
background: var(--colorApiBadgeBackgroundGet);
color: var(--colorApiBadgeTextGet);
}

.api-get::before {
background-color: var(--colorApiBadgeIconGet);
mask-image: url('../assets/icons/arrow-down-left.svg');
mask-size: 60%;
}

.api-post {
border-color: var(--colorApiBadgeBorderPost);
background: var(--colorApiBadgeBackgroundPost);
color: var(--colorApiBadgeTextPost);
}

.api-post::before {
background-color: var(--colorApiBadgeIconPost);
mask-image: url('../assets/icons/arrow-up-right.svg');
mask-size: 60%;
}

.api-delete {
border-color: var(--colorApiBadgeBorderDelete);
background: var(--colorApiBadgeBackgroundDelete);
color: var(--colorApiBadgeTextDelete);
}

.api-delete::before {
background-color: var(--colorApiBadgeIconDelete);
mask-image: url('../assets/icons/xmark.svg');
mask-size: 50%;
}

.api-put {
border-color: var(--colorApiBadgeBorderPut);
background: var(--colorApiBadgeBackgroundPut);
color: var(--colorApiBadgeTextPut);
}

.api-put::before {
background-color: var(--colorApiBadgeIconPut);
mask-image: url('../assets/icons/pen-line.svg');
mask-size: 90% 80%;
}
42 changes: 40 additions & 2 deletions src/styles/vars.css
Original file line number Diff line number Diff line change
Expand Up @@ -228,10 +228,29 @@

--standard-radius: 0.5rem;

/* TODO: drop these once color.nav.background.* are available in design-system-tokens */
--colorNavBackgroundRest: rgb(from var(--colorScalesBlue500) r g b / 0);
--colorNavBackgroundHover: var(--colorScalesSlate100);
--colorNavBackgroundActive: rgb(from var(--colorScalesBlue500) r g b / 0.06);

--colorApiBadgeBackgroundGet: var(--colorScalesGreen100);
--colorApiBadgeBorderGet: var(--colorScalesGreen200);
--colorApiBadgeIconGet: var(--colorScalesGreen600);
--colorApiBadgeTextGet: var(--colorScalesGreen600);

--colorApiBadgeBackgroundPost: var(--colorScalesBlue100);
--colorApiBadgeBorderPost: var(--colorScalesBlue200);
--colorApiBadgeIconPost: var(--colorScalesBlue600);
--colorApiBadgeTextPost: var(--colorScalesBlue600);

--colorApiBadgeBackgroundDelete: var(--colorScalesRed100);
--colorApiBadgeBorderDelete: var(--colorScalesRed200);
--colorApiBadgeIconDelete: var(--colorScalesRed600);
--colorApiBadgeTextDelete: var(--colorScalesRed600);

--colorApiBadgeBackgroundPut: var(--colorScalesYellow100);
--colorApiBadgeBorderPut: var(--colorScalesYellow200);
--colorApiBadgeIconPut: var(--colorScalesYellow600);
--colorApiBadgeTextPut: var(--colorScalesYellow600);
}

:root[data-theme-transition] {
Expand Down Expand Up @@ -274,6 +293,25 @@ html[data-theme='dark'] {
/* Tiles sit one step above the page so hover has somewhere lighter to go */
--icon-tile-background-hover: var(--colorBackgroundTertiary);

/* TODO: drop once color.nav.background.* are available in design-system-tokens */
--colorNavBackgroundHover: var(--colorScalesNavy800);

--colorApiBadgeBackgroundGet: var(--colorScalesGreen900);
--colorApiBadgeBorderGet: var(--colorScalesGreen700);
--colorApiBadgeIconGet: var(--colorScalesGreen300);
--colorApiBadgeTextGet: var(--colorScalesGreen300);

--colorApiBadgeBackgroundPost: var(--colorScalesBlue900);
--colorApiBadgeBorderPost: var(--colorScalesBlue700);
--colorApiBadgeIconPost: var(--colorScalesBlue300);
--colorApiBadgeTextPost: var(--colorScalesBlue300);

--colorApiBadgeBackgroundDelete: var(--colorScalesRed900);
--colorApiBadgeBorderDelete: var(--colorScalesRed700);
--colorApiBadgeIconDelete: var(--colorScalesRed300);
--colorApiBadgeTextDelete: var(--colorScalesRed300);

--colorApiBadgeBackgroundPut: var(--colorScalesYellow900);
--colorApiBadgeBorderPut: var(--colorScalesYellow700);
--colorApiBadgeIconPut: var(--colorScalesYellow300);
--colorApiBadgeTextPut: var(--colorScalesYellow300);
}
1 change: 1 addition & 0 deletions src/themes/octopus/components/HtmlHead.astro
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@ import '@octopusdeploy/design-system-tokens/css/darkTheme.css';
// cached across deploys.
import '../../../styles/vars.css';
import '../../../styles/main.css';
import '../../../styles/api.css';

const stats = new accelerator.statistics('octopus/components/HtmlHead.astro');
stats.start();
Expand Down