docs: revamp landing page with four-pillar card layout#2531
Merged
Conversation
Rewrite docs/index.md from a philosophy essay into a landing page organized around four pillars: Spec-driven by default, Use any coding agent, Make it your own, and Integrate into your organization. - Add hero section with GitHub Spec Kit branding and CTA buttons - Add 2x2 pillar card grid with GitHub Primer color accents - Add community stats section (96K stars, 200+ contributors, etc.) - Add navigation cards and footer install CTA - Move SDD philosophy content to docs/concepts/sdd.md - Add custom DocFX template overlay with card CSS and dark mode - Set landing layout for index.md via fileMetadata - Update toc.yml and docfx.json for new concepts section
Contributor
There was a problem hiding this comment.
Pull request overview
This PR revamps the DocFX documentation landing page by replacing the essay-style docs/index.md with a four-pillar, card-based landing layout, and moves the SDD philosophy content into a dedicated Concepts page.
Changes:
- Rewrites
docs/index.mdinto a landing page with hero CTAs, pillar cards, community stats, nav cards, and a footer install CTA. - Adds a new Concepts page (
docs/concepts/sdd.md) and links it from the TOC. - Introduces a DocFX template overlay CSS file and updates DocFX config to include the template and Concepts content.
Show a summary per file
| File | Description |
|---|---|
| docs/index.md | Replaced homepage content with a landing-page layout using HTML wrappers and Bootstrap classes |
| docs/concepts/sdd.md | New Concepts page containing the moved SDD philosophy content |
| docs/template/public/main.css | Adds landing page styling (Primer palette, cards, grids, dark mode variants) |
| docs/docfx.json | Includes Concepts glob, enables custom template, sets index.md to landing layout |
| docs/toc.yml | Adds “Concepts” section with link to the SDD page |
Copilot's findings
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comments suppressed due to low confidence (2)
docs/index.md:24
- The pillar card sections wrap Markdown headings (
### ...) and lists inside<div class="pillar-card">HTML blocks. In Markdig/DocFX, Markdown inside HTML blocks is commonly not rendered, which would break the card titles/content formatting. Use HTML headings/paragraphs within the card<div>s, or restructure so the Markdown is outside the HTML blocks.
<div class="pillar-grid">
<div class="pillar-card">
### Spec-driven by default
The core SDD process ships ready to use: **Spec → Plan → Tasks → Implement**.
Define what to build before building it. Rich templates, quality checklists, and cross-artifact analysis come out of the box. Each phase produces a Markdown artifact that feeds the next — giving your AI coding agent structured context instead of ad-hoc prompts.
docs/index.md:148
- The fenced code block is inside
<div class="footer-cta">. With Markdig, fenced blocks inside an HTML block often won’t be parsed, so the install snippet may render as raw backticks. Prefer<pre><code>here, or move the code fence outside the surrounding HTML block.
<div class="footer-cta">
```bash
uvx --from git+https://github.com/github/spec-kit.git
specify init my-project --integration copilot
</details>
- **Files reviewed:** 5/5 changed files
- **Comments generated:** 2
Comment on lines
+1
to
+7
| <div class="landing-hero"> | ||
|
|
||
| *Build high-quality software faster.* | ||
| # GitHub Spec Kit | ||
|
|
||
| **An effort to allow organizations to focus on product scenarios rather than writing undifferentiated code with the help of Spec-Driven Development.** | ||
| **Define what to build before building it — with any AI coding agent.** | ||
|
|
||
| ## What is Spec-Driven Development? | ||
| Spec Kit is a toolkit for [Spec-Driven Development](concepts/sdd.md) (SDD), a methodology that puts specifications at the center of AI-assisted software development. Instead of jumping straight to code, you describe *what* to build, refine it through structured phases, and let your AI coding agent implement it. |
Comment on lines
+109
to
+118
| /* Each pillar gets a distinct GitHub color accent */ | ||
| .pillar-card:nth-child(1) { border-top-color: var(--gh-green); } | ||
| .pillar-card:nth-child(2) { border-top-color: var(--gh-blue); } | ||
| .pillar-card:nth-child(3) { border-top-color: var(--gh-purple); } | ||
| .pillar-card:nth-child(4) { border-top-color: var(--gh-coral); } | ||
|
|
||
| .pillar-card:nth-child(1):hover { box-shadow: 0 4px 16px rgba(26, 127, 55, 0.12); } | ||
| .pillar-card:nth-child(2):hover { box-shadow: 0 4px 16px rgba(9, 105, 218, 0.12); } | ||
| .pillar-card:nth-child(3):hover { box-shadow: 0 4px 16px rgba(130, 80, 223, 0.12); } | ||
| .pillar-card:nth-child(4):hover { box-shadow: 0 4px 16px rgba(207, 34, 46, 0.12); } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Rewrites
docs/index.mdfrom a philosophy essay into a landing page organized around Spec Kit's four pillars.Changes
New files
docs/concepts/sdd.md— SDD philosophy content moved from the old index pagedocs/template/public/main.css— Custom DocFX template overlay with card CSS, GitHub Primer colors, and dark mode supportModified files
docs/index.md— Rewritten as a landing page with:uvxinstall commanddocs/docfx.json— Added custom template,concepts/*.mdcontent glob, and_layout: landingfileMetadata for index.mddocs/toc.yml— Added Concepts section with link to SDD pageDesign decisions
_layout: landingfor full-width rendering (no sidebar TOC)How to preview
Follow-ups (out of scope)