Skip to content

Commit 8aba980

Browse files
skarimskarim
committed
minor docs styling & content updates (#48)
* udpate meta tags for docs site * stack diagram styling fixes * update favicon * recommend gh skill to install skills file
1 parent f706944 commit 8aba980

9 files changed

Lines changed: 90 additions & 59 deletions

File tree

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ Requires the [GitHub CLI](https://cli.github.com/) (`gh`) v2.0+.
2121
Install the gh-stack skill so your AI coding agent knows how to work with stacked PRs and the `gh stack` CLI:
2222

2323
```sh
24-
npx skills add github/gh-stack
24+
gh skill install github/gh-stack
2525
```
2626

2727
## Quick start

‎docs/astro.config.mjs‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,14 +13,22 @@ export default defineConfig({
1313
integrations: [
1414
starlight({
1515
title: 'GitHub Stacked PRs',
16-
description: 'Manage stacked branches and pull requests with the gh stack CLI extension.',
16+
description: 'Break large changes into small, reviewable pull requests that build on each other — with native GitHub support and the gh stack CLI.',
1717
favicon: '/favicon.svg',
1818
logo: {
1919
src: './src/assets/github-invertocat.svg',
2020
alt: 'GitHub',
2121
},
2222
head: [
23-
{ tag: 'meta', attrs: { name: 'robots', content: 'noindex, nofollow' } },
23+
{ tag: 'meta', attrs: { property: 'og:type', content: 'website' } },
24+
{ tag: 'meta', attrs: { property: 'og:site_name', content: 'GitHub Stacked PRs' } },
25+
{ tag: 'meta', attrs: { property: 'og:image', content: 'https://github.github.com/gh-stack/github-social-card.jpg' } },
26+
{ tag: 'meta', attrs: { property: 'og:image:alt', content: 'GitHub Stacked PRs — Break large changes into small, reviewable pull requests' } },
27+
{ tag: 'meta', attrs: { property: 'og:image:width', content: '1200' } },
28+
{ tag: 'meta', attrs: { property: 'og:image:height', content: '630' } },
29+
{ tag: 'meta', attrs: { name: 'twitter:card', content: 'summary_large_image' } },
30+
{ tag: 'meta', attrs: { name: 'twitter:site', content: '@github' } },
31+
{ tag: 'meta', attrs: { name: 'twitter:image', content: 'https://github.github.com/gh-stack/github-social-card.jpg' } },
2432
],
2533
components: {
2634
SocialIcons: './src/components/CustomHeader.astro',

‎docs/public/favicon.svg‎

Lines changed: 2 additions & 3 deletions
Loading

‎docs/public/github-social-card.jpg‎

18.9 KB
Loading

‎docs/src/assets/stack-diagram.svg‎

Lines changed: 0 additions & 48 deletions
This file was deleted.

‎docs/src/components/StackDiagram.astro‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
---
2+
/**
3+
* Inline SVG stack diagram — uses currentColor to inherit text color from the
4+
* parent element, which is styled via external CSS. This avoids Safari bugs
5+
* where @media (prefers-color-scheme) doesn't work inside SVG elements.
6+
*/
7+
---
8+
<div class="stack-diagram-wrapper" style="max-width: 520px; margin: 1.5rem auto;">
9+
<svg width="100%" viewBox="-100 0 580 340" xmlns="http://www.w3.org/2000/svg" role="img" aria-label="A stack of pull requests: main at the bottom, with auth-layer (PR #1), api-endpoints (PR #2), and frontend (PR #3) stacked on top">
10+
<style>
11+
text { font-family: 'Mona Sans', -apple-system, "system-ui", "Segoe UI", sans-serif; }
12+
.trunk-box { fill: rgba(128,128,128,0.1); stroke: rgba(128,128,128,0.4); stroke-width: 1; }
13+
.trunk-text { fill: currentColor; font-size: 14px; font-weight: 600; }
14+
.branch-box { fill: rgba(9,105,218,0.12); stroke: #0969da; stroke-width: 1; }
15+
.branch-text { fill: currentColor; font-size: 14px; font-weight: 600; }
16+
.arrow-line { stroke: currentColor; stroke-width: 1.5; opacity: 0.4; }
17+
.arrow-marker { stroke: currentColor; stroke-opacity: 0.9; }
18+
.annotation { fill: currentColor; font-size: 14px; font-style: italic; opacity: 0.6; font-weight: 600; }
19+
</style>
20+
<defs>
21+
<marker id="arrow" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
22+
<path d="M2 1L8 5L2 9" fill="none" class="arrow-marker" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
23+
</marker>
24+
</defs>
25+
26+
<g>
27+
<rect x="80" y="262" width="220" height="44" rx="8" class="trunk-box"/>
28+
<text x="190" y="284" text-anchor="middle" dominant-baseline="central" class="trunk-text">main</text>
29+
</g>
30+
31+
<g>
32+
<rect x="80" y="188" width="220" height="44" rx="8" class="branch-box"/>
33+
<text x="190" y="210" text-anchor="middle" dominant-baseline="central" class="branch-text">PR #1 · auth-layer</text>
34+
</g>
35+
36+
<g>
37+
<rect x="80" y="114" width="220" height="44" rx="8" class="branch-box"/>
38+
<text x="190" y="136" text-anchor="middle" dominant-baseline="central" class="branch-text">PR #2 · api-endpoints</text>
39+
</g>
40+
41+
<g>
42+
<rect x="80" y="40" width="220" height="44" rx="8" class="branch-box"/>
43+
<text x="190" y="62" text-anchor="middle" dominant-baseline="central" class="branch-text">PR #3 · frontend</text>
44+
</g>
45+
46+
<line x1="190" y1="262" x2="190" y2="232" marker-end="url(#arrow)" class="arrow-line"/>
47+
<line x1="190" y1="188" x2="190" y2="158" marker-end="url(#arrow)" class="arrow-line"/>
48+
<line x1="190" y1="114" x2="190" y2="84" marker-end="url(#arrow)" class="arrow-line"/>
49+
50+
<text x="320" y="210" dominant-baseline="central" class="annotation">← bottom</text>
51+
<text x="320" y="62" dominant-baseline="central" class="annotation">← top</text>
52+
</svg>
53+
</div>
54+
55+
<style>
56+
.stack-diagram-wrapper {
57+
color: #1f1f1f;
58+
}
59+
:root[data-theme='dark'] .stack-diagram-wrapper {
60+
color: #ffffff;
61+
}
62+
</style>

‎docs/src/content/docs/getting-started/quick-start.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,12 @@ gh extension install github/gh-stack
2323

2424
If you use AI coding agents (like GitHub Copilot), install the gh-stack skill so they know how to work with Stacked PRs:
2525

26+
```sh
27+
gh skill install github/gh-stack
28+
```
29+
30+
Or if you prefer to use `npx skills`:
31+
2632
```sh
2733
npx skills add github/gh-stack
2834
```

‎docs/src/content/docs/guides/workflows.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -191,6 +191,12 @@ The `unstack` command deletes the stack on GitHub first, then removes local trac
191191

192192
AI coding agents (like GitHub Copilot) can create and manage Stacked PRs on your behalf. Install the gh-stack skill to give them the context they need:
193193

194+
```sh
195+
gh skill install github/gh-stack
196+
```
197+
198+
Or if you prefer to use `npx skills`:
199+
194200
```sh
195201
npx skills add github/gh-stack
196202
```

‎docs/src/content/docs/index.mdx‎

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ hero:
1717

1818
import { Card, CardGrid, Aside } from '@astrojs/starlight/components';
1919
import { Image } from 'astro:assets';
20-
import stackDiagram from '../../assets/stack-diagram.svg';
20+
import StackDiagram from '../../components/StackDiagram.astro';
2121
import stackNavigator from '../../assets/screenshots/stack-navigator.png';
2222

2323
<CardGrid>
@@ -31,7 +31,7 @@ import stackNavigator from '../../assets/screenshots/stack-navigator.png';
3131
The `gh stack` CLI makes it easy to create stacks, perform cascading rebases, push branches and create PRs, and navigate between layers — all from your terminal.
3232
</Card>
3333
<Card title="AI Agent Integration" icon="puzzle">
34-
Run `npx skills add github/gh-stack` to teach your AI coding agents how to work with stacks. Break up a large diff into a stack or develop with stacks from the start.
34+
Run `gh skill install github/gh-stack` to teach your AI coding agents how to work with stacks. Break up a large diff into a stack or develop with stacks from the start.
3535
</Card>
3636
</CardGrid>
3737

@@ -43,9 +43,7 @@ Large pull requests are hard to review, slow to merge, and prone to conflicts. R
4343

4444
A **stack** is a series of pull requests in the same repository where each PR targets the branch of the PR below it, forming an ordered chain that ultimately lands on your main branch.
4545

46-
<div style="max-width: 420px; margin: 1.5rem auto;">
47-
<Image src={stackDiagram} alt="A stack of pull requests: main at the bottom, with auth-layer (PR #1), api-endpoints (PR #2), and frontend (PR #3) stacked on top" />
48-
</div>
46+
<StackDiagram />
4947

5048
GitHub understands stacks end-to-end: the pull request UI shows a **stack map** so reviewers can navigate between layers, branch protection rules are enforced against the **final target branch** (not just the direct base), and CI runs for every PR in the stack as if they were targeting the final branch.
5149

0 commit comments

Comments
 (0)