Skip to content

minor docs styling & content updates #48

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
skarim wants to merge 4 commits into from
Open

minor docs styling & content updates #48

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
b663662
udpate meta tags for docs site
skarim Apr 14, 2026
5ee094e
stack diagram styling fixes
skarim Apr 15, 2026
ba2ca25
update favicon
skarim Apr 17, 2026
a7c37cd
recommend gh skill to install skills file
skarim Apr 17, 2026
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
2 changes: 1 addition & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ Requires the [GitHub CLI](https://cli.github.com/) (`gh`) v2.0+.
Install the gh-stack skill so your AI coding agent knows how to work with stacked PRs and the `gh stack` CLI:

```sh
npx skills add github/gh-stack
gh skill install github/gh-stack
```

## Quick start
Expand Down
12 changes: 10 additions & 2 deletions docs/astro.config.mjs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,14 +13,22 @@ export default defineConfig({
integrations: [
starlight({
title: 'GitHub Stacked PRs',
description: 'Manage stacked branches and pull requests with the gh stack CLI extension.',
description: 'Break large changes into small, reviewable pull requests that build on each other — with native GitHub support and the gh stack CLI.',
favicon: '/favicon.svg',
logo: {
src: './src/assets/github-invertocat.svg',
alt: 'GitHub',
},
head: [
Comment thread
skarim marked this conversation as resolved.
{ tag: 'meta', attrs: { name: 'robots', content: 'noindex, nofollow' } },
{ tag: 'meta', attrs: { property: 'og:type', content: 'website' } },
{ tag: 'meta', attrs: { property: 'og:site_name', content: 'GitHub Stacked PRs' } },
{ tag: 'meta', attrs: { property: 'og:image', content: 'https://github.github.com/gh-stack/github-social-card.jpg' } },
{ tag: 'meta', attrs: { property: 'og:image:alt', content: 'GitHub Stacked PRs — Break large changes into small, reviewable pull requests' } },
{ tag: 'meta', attrs: { property: 'og:image:width', content: '1200' } },
{ tag: 'meta', attrs: { property: 'og:image:height', content: '630' } },
{ tag: 'meta', attrs: { name: 'twitter:card', content: 'summary_large_image' } },
{ tag: 'meta', attrs: { name: 'twitter:site', content: '@github' } },
{ tag: 'meta', attrs: { name: 'twitter:image', content: 'https://github.github.com/gh-stack/github-social-card.jpg' } },
Comment thread
skarim marked this conversation as resolved.
],
components: {
SocialIcons: './src/components/CustomHeader.astro',
Expand Down
5 changes: 2 additions & 3 deletions docs/public/favicon.svg
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/public/github-social-card.jpg
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
48 changes: 0 additions & 48 deletions docs/src/assets/stack-diagram.svg
View file
Open in desktop

This file was deleted.

62 changes: 62 additions & 0 deletions docs/src/components/StackDiagram.astro
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
---
/**
* Inline SVG stack diagram — uses currentColor to inherit text color from the
* parent element, which is styled via external CSS. This avoids Safari bugs
* where @media (prefers-color-scheme) doesn't work inside SVG elements.
*/
---
<div class="stack-diagram-wrapper" style="max-width: 520px; margin: 1.5rem auto;">
<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">
<style>
text { font-family: 'Mona Sans', -apple-system, "system-ui", "Segoe UI", sans-serif; }
.trunk-box { fill: rgba(128,128,128,0.1); stroke: rgba(128,128,128,0.4); stroke-width: 1; }
.trunk-text { fill: currentColor; font-size: 14px; font-weight: 600; }
.branch-box { fill: rgba(9,105,218,0.12); stroke: #0969da; stroke-width: 1; }
.branch-text { fill: currentColor; font-size: 14px; font-weight: 600; }
.arrow-line { stroke: currentColor; stroke-width: 1.5; opacity: 0.4; }
.arrow-marker { stroke: currentColor; stroke-opacity: 0.9; }
.annotation { fill: currentColor; font-size: 14px; font-style: italic; opacity: 0.6; font-weight: 600; }
</style>
<defs>
<marker id="arrow" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
<path d="M2 1L8 5L2 9" fill="none" class="arrow-marker" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
</marker>
Comment thread
skarim marked this conversation as resolved.
</defs>

<g>
<rect x="80" y="262" width="220" height="44" rx="8" class="trunk-box"/>
<text x="190" y="284" text-anchor="middle" dominant-baseline="central" class="trunk-text">main</text>
</g>

<g>
<rect x="80" y="188" width="220" height="44" rx="8" class="branch-box"/>
<text x="190" y="210" text-anchor="middle" dominant-baseline="central" class="branch-text">PR #1 · auth-layer</text>
</g>

<g>
<rect x="80" y="114" width="220" height="44" rx="8" class="branch-box"/>
<text x="190" y="136" text-anchor="middle" dominant-baseline="central" class="branch-text">PR #2 · api-endpoints</text>
</g>

<g>
<rect x="80" y="40" width="220" height="44" rx="8" class="branch-box"/>
<text x="190" y="62" text-anchor="middle" dominant-baseline="central" class="branch-text">PR #3 · frontend</text>
</g>

<line x1="190" y1="262" x2="190" y2="232" marker-end="url(#arrow)" class="arrow-line"/>
<line x1="190" y1="188" x2="190" y2="158" marker-end="url(#arrow)" class="arrow-line"/>
<line x1="190" y1="114" x2="190" y2="84" marker-end="url(#arrow)" class="arrow-line"/>

<text x="320" y="210" dominant-baseline="central" class="annotation">← bottom</text>
<text x="320" y="62" dominant-baseline="central" class="annotation">← top</text>
</svg>
</div>

<style>
.stack-diagram-wrapper {
color: #1f1f1f;
}
:root[data-theme='dark'] .stack-diagram-wrapper {
color: #ffffff;
}
</style>
6 changes: 6 additions & 0 deletions docs/src/content/docs/getting-started/quick-start.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,12 @@ gh extension install github/gh-stack

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

```sh
gh skill install github/gh-stack
```

Or if you prefer to use `npx skills`:

```sh
npx skills add github/gh-stack
```
Expand Down
6 changes: 6 additions & 0 deletions docs/src/content/docs/guides/workflows.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -191,6 +191,12 @@ The `unstack` command deletes the stack on GitHub first, then removes local trac

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:

```sh
gh skill install github/gh-stack
```

Or if you prefer to use `npx skills`:

```sh
npx skills add github/gh-stack
```
Expand Down
8 changes: 3 additions & 5 deletions docs/src/content/docs/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ hero:

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

<CardGrid>
Expand All @@ -31,7 +31,7 @@ import stackNavigator from '../../assets/screenshots/stack-navigator.png';
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.
</Card>
<Card title="AI Agent Integration" icon="puzzle">
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.
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.
</Card>
</CardGrid>

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

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.

<div style="max-width: 420px; margin: 1.5rem auto;">
<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" />
</div>
<StackDiagram />

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.

Expand Down