refactor(skills): move site-architecture catalogs to references
Keep the decision steps in SKILL.md and move catalogs, examples, and checklists verbatim to references/ to reduce the context cost of loading the skill. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Julian lechnerandClaude Opus 5.5 committed
1 parent
c8b00584d9
commit
c14101e60d
6 files changed
+234
-239
No files matched your search
@@ -56,258 +56,26 @@ Gather this context (ask if not provided):
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Page Hierarchy Design
|
## References
|
||||||
|
|
||||||
### The 3-Click Rule
|
- [references/page-hierarchy.md](references/page-hierarchy.md): Read when designing hierarchy depth, levels, or the ASCII tree
|
||||||
|
- [references/navigation-design.md](references/navigation-design.md): Read when designing header, footer, sidebar, or breadcrumb navigation
|
||||||
Users should reach any important page within 3 clicks from the homepage. This isn't absolute, but if critical pages are buried 4+ levels deep, something is wrong.
|
- [references/url-structure.md](references/url-structure.md): Read when designing URL patterns and redirects
|
||||||
|
- [references/visual-sitemaps.md](references/visual-sitemaps.md): Read when producing the Mermaid visual sitemap
|
||||||
### Flat vs Deep
|
- [references/internal-linking.md](references/internal-linking.md): Read when planning internal links or a link audit
|
||||||
|
|
||||||
| Approach | Best For | Tradeoff |
|
|
||||||
|----------|----------|----------|
|
|
||||||
| Flat (2 levels) | Small sites, portfolios | Simple but doesn't scale |
|
|
||||||
| Moderate (3 levels) | Most SaaS, content sites | Good balance of depth and findability |
|
|
||||||
| Deep (4+ levels) | E-commerce, large docs | Scales but risks burying content |
|
|
||||||
|
|
||||||
**Rule of thumb**: Go as flat as possible while keeping navigation clean. If a nav dropdown has 20+ items, add a level of hierarchy.
|
|
||||||
|
|
||||||
### Hierarchy Levels
|
|
||||||
|
|
||||||
| Level | What It Is | Example |
|
|
||||||
|-------|-----------|---------|
|
|
||||||
| L0 | Homepage | `/` |
|
|
||||||
| L1 | Primary sections | `/features`, `/blog`, `/pricing` |
|
|
||||||
| L2 | Section pages | `/features/analytics`, `/blog/seo-guide` |
|
|
||||||
| L3+ | Detail pages | `/docs/api/authentication` |
|
|
||||||
|
|
||||||
### ASCII Tree Format
|
|
||||||
|
|
||||||
Use this format for page hierarchies:
|
|
||||||
|
|
||||||
```
|
|
||||||
Homepage (/)
|
|
||||||
├── Features (/features)
|
|
||||||
│ ├── Analytics (/features/analytics)
|
|
||||||
│ ├── Automation (/features/automation)
|
|
||||||
│ └── Integrations (/features/integrations)
|
|
||||||
├── Pricing (/pricing)
|
|
||||||
├── Blog (/blog)
|
|
||||||
│ ├── [Category: SEO] (/blog/category/seo)
|
|
||||||
│ └── [Category: CRO] (/blog/category/cro)
|
|
||||||
├── Resources (/resources)
|
|
||||||
│ ├── Case Studies (/resources/case-studies)
|
|
||||||
│ └── Templates (/resources/templates)
|
|
||||||
├── Docs (/docs)
|
|
||||||
│ ├── Getting Started (/docs/getting-started)
|
|
||||||
│ └── API Reference (/docs/api)
|
|
||||||
├── About (/about)
|
|
||||||
│ └── Careers (/about/careers)
|
|
||||||
└── Contact (/contact)
|
|
||||||
```
|
|
||||||
|
|
||||||
**When to use ASCII vs Mermaid**:
|
|
||||||
- ASCII: quick hierarchy drafts, text-only contexts, simple structures
|
|
||||||
- Mermaid: visual presentations, complex relationships, showing nav zones or linking patterns
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Navigation Design
|
|
||||||
|
|
||||||
### Navigation Types
|
|
||||||
|
|
||||||
| Nav Type | Purpose | Placement |
|
|
||||||
|----------|---------|-----------|
|
|
||||||
| Header nav | Primary navigation, always visible | Top of every page |
|
|
||||||
| Dropdown menus | Organize sub-pages under parent | Expands from header items |
|
|
||||||
| Footer nav | Secondary links, legal, sitemap | Bottom of every page |
|
|
||||||
| Sidebar nav | Section navigation (docs, blog) | Left side within a section |
|
|
||||||
| Breadcrumbs | Show current location in hierarchy | Below header, above content |
|
|
||||||
| Contextual links | Related content, next steps | Within page content |
|
|
||||||
|
|
||||||
### Header Navigation Rules
|
|
||||||
|
|
||||||
- **4-7 items max** in the primary nav (more causes decision paralysis)
|
|
||||||
- **CTA button** goes rightmost (e.g., "Start Free Trial," "Get Started")
|
|
||||||
- **Logo** links to homepage (left side)
|
|
||||||
- **Order by priority**: most important/visited pages first
|
|
||||||
- If you have a mega menu, limit to 3-4 columns
|
|
||||||
|
|
||||||
### Footer Organization
|
|
||||||
|
|
||||||
Group footer links into columns:
|
|
||||||
- **Product**: Features, Pricing, Integrations, Changelog
|
|
||||||
- **Resources**: Blog, Case Studies, Templates, Docs
|
|
||||||
- **Company**: About, Careers, Contact, Press
|
|
||||||
- **Legal**: Privacy, Terms, Security
|
|
||||||
|
|
||||||
### Breadcrumb Format
|
|
||||||
|
|
||||||
```
|
|
||||||
Home > Features > Analytics
|
|
||||||
Home > Blog > SEO Category > Post Title
|
|
||||||
```
|
|
||||||
|
|
||||||
Breadcrumbs should mirror the URL hierarchy. Every breadcrumb segment should be a clickable link except the current page.
|
|
||||||
|
|
||||||
**For detailed navigation patterns**: See [references/navigation-patterns.md](references/navigation-patterns.md)
|
**For detailed navigation patterns**: See [references/navigation-patterns.md](references/navigation-patterns.md)
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## URL Structure
|
|
||||||
|
|
||||||
### Design Principles
|
|
||||||
|
|
||||||
1. **Readable by humans** — `/features/analytics` not `/f/a123`
|
|
||||||
2. **Hyphens, not underscores** — `/blog/seo-guide` not `/blog/seo_guide`
|
|
||||||
3. **Reflect the hierarchy** — URL path should match site structure
|
|
||||||
4. **Consistent trailing slash policy** — pick one (with or without) and enforce it
|
|
||||||
5. **Lowercase always** — `/About` should redirect to `/about`
|
|
||||||
6. **Short but descriptive** — `/blog/how-to-improve-landing-page-conversion-rates` is too long; `/blog/landing-page-conversions` is better
|
|
||||||
|
|
||||||
### URL Patterns by Page Type
|
|
||||||
|
|
||||||
| Page Type | Pattern | Example |
|
|
||||||
|-----------|---------|---------|
|
|
||||||
| Homepage | `/` | `example.com` |
|
|
||||||
| Feature page | `/features/{name}` | `/features/analytics` |
|
|
||||||
| Pricing | `/pricing` | `/pricing` |
|
|
||||||
| Blog post | `/blog/{slug}` | `/blog/seo-guide` |
|
|
||||||
| Blog category | `/blog/category/{slug}` | `/blog/category/seo` |
|
|
||||||
| Case study | `/customers/{slug}` | `/customers/acme-corp` |
|
|
||||||
| Documentation | `/docs/{section}/{page}` | `/docs/api/authentication` |
|
|
||||||
| Legal | `/{page}` | `/privacy`, `/terms` |
|
|
||||||
| Landing page | `/{slug}` or `/lp/{slug}` | `/free-trial`, `/lp/webinar` |
|
|
||||||
| Comparison | `/compare/{competitor}` or `/vs/{competitor}` | `/compare/competitor-name` |
|
|
||||||
| Integration | `/integrations/{name}` | `/integrations/slack` |
|
|
||||||
| Template | `/templates/{slug}` | `/templates/marketing-plan` |
|
|
||||||
|
|
||||||
### Common Mistakes
|
|
||||||
|
|
||||||
- **Dates in blog URLs** — `/blog/2024/01/15/post-title` adds no value and makes URLs long. Use `/blog/post-title`.
|
|
||||||
- **Over-nesting** — `/products/category/subcategory/item/detail` is too deep. Flatten where possible.
|
|
||||||
- **Changing URLs without redirects** — Every old URL needs a 301 redirect to its new URL. Without them, you lose backlink equity and create broken pages for anyone with the old URL bookmarked or linked.
|
|
||||||
- **IDs in URLs** — `/product/12345` is not human-readable. Use slugs.
|
|
||||||
- **Query parameters for content** — `/blog?id=123` should be `/blog/post-title`.
|
|
||||||
- **Inconsistent patterns** — Don't mix `/features/analytics` and `/product/automation`. Pick one parent.
|
|
||||||
|
|
||||||
### Breadcrumb-URL Alignment
|
|
||||||
|
|
||||||
The breadcrumb trail should mirror the URL path:
|
|
||||||
|
|
||||||
| URL | Breadcrumb |
|
|
||||||
|-----|-----------|
|
|
||||||
| `/features/analytics` | Home > Features > Analytics |
|
|
||||||
| `/blog/seo-guide` | Home > Blog > SEO Guide |
|
|
||||||
| `/docs/api/auth` | Home > Docs > API > Authentication |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Visual Sitemap Output (Mermaid)
|
|
||||||
|
|
||||||
Use Mermaid `graph TD` for visual sitemaps. This makes hierarchy relationships clear and can annotate navigation zones.
|
|
||||||
|
|
||||||
### Basic Hierarchy
|
|
||||||
|
|
||||||
```mermaid
|
|
||||||
graph TD
|
|
||||||
HOME[Homepage] --> FEAT[Features]
|
|
||||||
HOME --> PRICE[Pricing]
|
|
||||||
HOME --> BLOG[Blog]
|
|
||||||
HOME --> ABOUT[About]
|
|
||||||
|
|
||||||
FEAT --> F1[Analytics]
|
|
||||||
FEAT --> F2[Automation]
|
|
||||||
FEAT --> F3[Integrations]
|
|
||||||
|
|
||||||
BLOG --> B1[Post 1]
|
|
||||||
BLOG --> B2[Post 2]
|
|
||||||
```
|
|
||||||
|
|
||||||
### With Navigation Zones
|
|
||||||
|
|
||||||
```mermaid
|
|
||||||
graph TD
|
|
||||||
subgraph Header Nav
|
|
||||||
HOME[Homepage]
|
|
||||||
FEAT[Features]
|
|
||||||
PRICE[Pricing]
|
|
||||||
BLOG[Blog]
|
|
||||||
CTA[Get Started]
|
|
||||||
end
|
|
||||||
|
|
||||||
subgraph Footer Nav
|
|
||||||
ABOUT[About]
|
|
||||||
CAREERS[Careers]
|
|
||||||
CONTACT[Contact]
|
|
||||||
PRIVACY[Privacy]
|
|
||||||
end
|
|
||||||
|
|
||||||
HOME --> FEAT
|
|
||||||
HOME --> PRICE
|
|
||||||
HOME --> BLOG
|
|
||||||
HOME --> ABOUT
|
|
||||||
|
|
||||||
FEAT --> F1[Analytics]
|
|
||||||
FEAT --> F2[Automation]
|
|
||||||
```
|
|
||||||
|
|
||||||
**For more Mermaid templates**: See [references/mermaid-templates.md](references/mermaid-templates.md)
|
**For more Mermaid templates**: See [references/mermaid-templates.md](references/mermaid-templates.md)
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Internal Linking Strategy
|
|
||||||
|
|
||||||
### Link Types
|
|
||||||
|
|
||||||
| Type | Purpose | Example |
|
|
||||||
|------|---------|---------|
|
|
||||||
| Navigational | Move between sections | Header, footer, sidebar links |
|
|
||||||
| Contextual | Related content within text | "Learn more about [analytics](/features/analytics)" |
|
|
||||||
| Hub-and-spoke | Connect cluster content to hub | Blog posts linking to pillar page |
|
|
||||||
| Cross-section | Connect related pages across sections | Feature page linking to related case study |
|
|
||||||
|
|
||||||
### Internal Linking Rules
|
|
||||||
|
|
||||||
1. **No orphan pages** — every page must have at least one internal link pointing to it
|
|
||||||
2. **Descriptive anchor text** — "our analytics features" not "click here"
|
|
||||||
3. **5-10 internal links per 1000 words** of content (approximate guideline)
|
|
||||||
4. **Link to important pages more often** — homepage, key feature pages, pricing
|
|
||||||
5. **Use breadcrumbs** — free internal links on every page
|
|
||||||
6. **Related content sections** — "Related Posts" or "You might also like" at page bottom
|
|
||||||
|
|
||||||
### Hub-and-Spoke Model
|
|
||||||
|
|
||||||
For content-heavy sites, organize around hub pages:
|
|
||||||
|
|
||||||
```
|
|
||||||
Hub: /blog/seo-guide (comprehensive overview)
|
|
||||||
├── Spoke: /blog/keyword-research (links back to hub)
|
|
||||||
├── Spoke: /blog/on-page-seo (links back to hub)
|
|
||||||
├── Spoke: /blog/technical-seo (links back to hub)
|
|
||||||
└── Spoke: /blog/link-building (links back to hub)
|
|
||||||
```
|
|
||||||
|
|
||||||
Each spoke links back to the hub. The hub links to all spokes. Spokes link to each other where relevant.
|
|
||||||
|
|
||||||
### Link Audit Checklist
|
|
||||||
|
|
||||||
- [ ] Every page has at least one inbound internal link
|
|
||||||
- [ ] No broken internal links (404s)
|
|
||||||
- [ ] Anchor text is descriptive (not "click here" or "read more")
|
|
||||||
- [ ] Important pages have the most inbound internal links
|
|
||||||
- [ ] Breadcrumbs are implemented on all pages
|
|
||||||
- [ ] Related content links exist on blog posts
|
|
||||||
- [ ] Cross-section links connect features to case studies, blog to product pages
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Output Format
|
## Output Format
|
||||||
|
|
||||||
When creating a site architecture plan, provide these deliverables:
|
When creating a site architecture plan, provide these deliverables:
|
||||||
|
|
||||||
### 1. Page Hierarchy (ASCII Tree)
|
### 1. Page Hierarchy (ASCII Tree)
|
||||||
Full site structure with URLs at each node. Use the ASCII tree format from the Page Hierarchy Design section.
|
Full site structure with URLs at each node. Use the ASCII tree format from [references/page-hierarchy.md](references/page-hierarchy.md).
|
||||||
|
|
||||||
### 2. Visual Sitemap (Mermaid)
|
### 2. Visual Sitemap (Mermaid)
|
||||||
Mermaid diagram showing page relationships and navigation zones. Use `graph TD` with subgraphs for nav zones where helpful.
|
Mermaid diagram showing page relationships and navigation zones. Use `graph TD` with subgraphs for nav zones where helpful.
|
||||||
|
|||||||
@@ -0,0 +1,43 @@
|
|||||||
|
# Internal Linking Strategy
|
||||||
|
|
||||||
|
## Link Types
|
||||||
|
|
||||||
|
| Type | Purpose | Example |
|
||||||
|
|------|---------|---------|
|
||||||
|
| Navigational | Move between sections | Header, footer, sidebar links |
|
||||||
|
| Contextual | Related content within text | "Learn more about [analytics](/features/analytics)" |
|
||||||
|
| Hub-and-spoke | Connect cluster content to hub | Blog posts linking to pillar page |
|
||||||
|
| Cross-section | Connect related pages across sections | Feature page linking to related case study |
|
||||||
|
|
||||||
|
## Internal Linking Rules
|
||||||
|
|
||||||
|
1. **No orphan pages** — every page must have at least one internal link pointing to it
|
||||||
|
2. **Descriptive anchor text** — "our analytics features" not "click here"
|
||||||
|
3. **5-10 internal links per 1000 words** of content (approximate guideline)
|
||||||
|
4. **Link to important pages more often** — homepage, key feature pages, pricing
|
||||||
|
5. **Use breadcrumbs** — free internal links on every page
|
||||||
|
6. **Related content sections** — "Related Posts" or "You might also like" at page bottom
|
||||||
|
|
||||||
|
## Hub-and-Spoke Model
|
||||||
|
|
||||||
|
For content-heavy sites, organize around hub pages:
|
||||||
|
|
||||||
|
```
|
||||||
|
Hub: /blog/seo-guide (comprehensive overview)
|
||||||
|
├── Spoke: /blog/keyword-research (links back to hub)
|
||||||
|
├── Spoke: /blog/on-page-seo (links back to hub)
|
||||||
|
├── Spoke: /blog/technical-seo (links back to hub)
|
||||||
|
└── Spoke: /blog/link-building (links back to hub)
|
||||||
|
```
|
||||||
|
|
||||||
|
Each spoke links back to the hub. The hub links to all spokes. Spokes link to each other where relevant.
|
||||||
|
|
||||||
|
## Link Audit Checklist
|
||||||
|
|
||||||
|
- [ ] Every page has at least one inbound internal link
|
||||||
|
- [ ] No broken internal links (404s)
|
||||||
|
- [ ] Anchor text is descriptive (not "click here" or "read more")
|
||||||
|
- [ ] Important pages have the most inbound internal links
|
||||||
|
- [ ] Breadcrumbs are implemented on all pages
|
||||||
|
- [ ] Related content links exist on blog posts
|
||||||
|
- [ ] Cross-section links connect features to case studies, blog to product pages
|
||||||
@@ -0,0 +1,37 @@
|
|||||||
|
# Navigation Design
|
||||||
|
|
||||||
|
## Navigation Types
|
||||||
|
|
||||||
|
| Nav Type | Purpose | Placement |
|
||||||
|
|----------|---------|-----------|
|
||||||
|
| Header nav | Primary navigation, always visible | Top of every page |
|
||||||
|
| Dropdown menus | Organize sub-pages under parent | Expands from header items |
|
||||||
|
| Footer nav | Secondary links, legal, sitemap | Bottom of every page |
|
||||||
|
| Sidebar nav | Section navigation (docs, blog) | Left side within a section |
|
||||||
|
| Breadcrumbs | Show current location in hierarchy | Below header, above content |
|
||||||
|
| Contextual links | Related content, next steps | Within page content |
|
||||||
|
|
||||||
|
## Header Navigation Rules
|
||||||
|
|
||||||
|
- **4-7 items max** in the primary nav (more causes decision paralysis)
|
||||||
|
- **CTA button** goes rightmost (e.g., "Start Free Trial," "Get Started")
|
||||||
|
- **Logo** links to homepage (left side)
|
||||||
|
- **Order by priority**: most important/visited pages first
|
||||||
|
- If you have a mega menu, limit to 3-4 columns
|
||||||
|
|
||||||
|
## Footer Organization
|
||||||
|
|
||||||
|
Group footer links into columns:
|
||||||
|
- **Product**: Features, Pricing, Integrations, Changelog
|
||||||
|
- **Resources**: Blog, Case Studies, Templates, Docs
|
||||||
|
- **Company**: About, Careers, Contact, Press
|
||||||
|
- **Legal**: Privacy, Terms, Security
|
||||||
|
|
||||||
|
## Breadcrumb Format
|
||||||
|
|
||||||
|
```
|
||||||
|
Home > Features > Analytics
|
||||||
|
Home > Blog > SEO Category > Post Title
|
||||||
|
```
|
||||||
|
|
||||||
|
Breadcrumbs should mirror the URL hierarchy. Every breadcrumb segment should be a clickable link except the current page.
|
||||||
@@ -0,0 +1,53 @@
|
|||||||
|
# Page Hierarchy Design
|
||||||
|
|
||||||
|
## The 3-Click Rule
|
||||||
|
|
||||||
|
Users should reach any important page within 3 clicks from the homepage. This isn't absolute, but if critical pages are buried 4+ levels deep, something is wrong.
|
||||||
|
|
||||||
|
## Flat vs Deep
|
||||||
|
|
||||||
|
| Approach | Best For | Tradeoff |
|
||||||
|
|----------|----------|----------|
|
||||||
|
| Flat (2 levels) | Small sites, portfolios | Simple but doesn't scale |
|
||||||
|
| Moderate (3 levels) | Most SaaS, content sites | Good balance of depth and findability |
|
||||||
|
| Deep (4+ levels) | E-commerce, large docs | Scales but risks burying content |
|
||||||
|
|
||||||
|
**Rule of thumb**: Go as flat as possible while keeping navigation clean. If a nav dropdown has 20+ items, add a level of hierarchy.
|
||||||
|
|
||||||
|
## Hierarchy Levels
|
||||||
|
|
||||||
|
| Level | What It Is | Example |
|
||||||
|
|-------|-----------|---------|
|
||||||
|
| L0 | Homepage | `/` |
|
||||||
|
| L1 | Primary sections | `/features`, `/blog`, `/pricing` |
|
||||||
|
| L2 | Section pages | `/features/analytics`, `/blog/seo-guide` |
|
||||||
|
| L3+ | Detail pages | `/docs/api/authentication` |
|
||||||
|
|
||||||
|
## ASCII Tree Format
|
||||||
|
|
||||||
|
Use this format for page hierarchies:
|
||||||
|
|
||||||
|
```
|
||||||
|
Homepage (/)
|
||||||
|
├── Features (/features)
|
||||||
|
│ ├── Analytics (/features/analytics)
|
||||||
|
│ ├── Automation (/features/automation)
|
||||||
|
│ └── Integrations (/features/integrations)
|
||||||
|
├── Pricing (/pricing)
|
||||||
|
├── Blog (/blog)
|
||||||
|
│ ├── [Category: SEO] (/blog/category/seo)
|
||||||
|
│ └── [Category: CRO] (/blog/category/cro)
|
||||||
|
├── Resources (/resources)
|
||||||
|
│ ├── Case Studies (/resources/case-studies)
|
||||||
|
│ └── Templates (/resources/templates)
|
||||||
|
├── Docs (/docs)
|
||||||
|
│ ├── Getting Started (/docs/getting-started)
|
||||||
|
│ └── API Reference (/docs/api)
|
||||||
|
├── About (/about)
|
||||||
|
│ └── Careers (/about/careers)
|
||||||
|
└── Contact (/contact)
|
||||||
|
```
|
||||||
|
|
||||||
|
**When to use ASCII vs Mermaid**:
|
||||||
|
- ASCII: quick hierarchy drafts, text-only contexts, simple structures
|
||||||
|
- Mermaid: visual presentations, complex relationships, showing nav zones or linking patterns
|
||||||
@@ -0,0 +1,46 @@
|
|||||||
|
# URL Structure
|
||||||
|
|
||||||
|
## Design Principles
|
||||||
|
|
||||||
|
1. **Readable by humans** — `/features/analytics` not `/f/a123`
|
||||||
|
2. **Hyphens, not underscores** — `/blog/seo-guide` not `/blog/seo_guide`
|
||||||
|
3. **Reflect the hierarchy** — URL path should match site structure
|
||||||
|
4. **Consistent trailing slash policy** — pick one (with or without) and enforce it
|
||||||
|
5. **Lowercase always** — `/About` should redirect to `/about`
|
||||||
|
6. **Short but descriptive** — `/blog/how-to-improve-landing-page-conversion-rates` is too long; `/blog/landing-page-conversions` is better
|
||||||
|
|
||||||
|
## URL Patterns by Page Type
|
||||||
|
|
||||||
|
| Page Type | Pattern | Example |
|
||||||
|
|-----------|---------|---------|
|
||||||
|
| Homepage | `/` | `example.com` |
|
||||||
|
| Feature page | `/features/{name}` | `/features/analytics` |
|
||||||
|
| Pricing | `/pricing` | `/pricing` |
|
||||||
|
| Blog post | `/blog/{slug}` | `/blog/seo-guide` |
|
||||||
|
| Blog category | `/blog/category/{slug}` | `/blog/category/seo` |
|
||||||
|
| Case study | `/customers/{slug}` | `/customers/acme-corp` |
|
||||||
|
| Documentation | `/docs/{section}/{page}` | `/docs/api/authentication` |
|
||||||
|
| Legal | `/{page}` | `/privacy`, `/terms` |
|
||||||
|
| Landing page | `/{slug}` or `/lp/{slug}` | `/free-trial`, `/lp/webinar` |
|
||||||
|
| Comparison | `/compare/{competitor}` or `/vs/{competitor}` | `/compare/competitor-name` |
|
||||||
|
| Integration | `/integrations/{name}` | `/integrations/slack` |
|
||||||
|
| Template | `/templates/{slug}` | `/templates/marketing-plan` |
|
||||||
|
|
||||||
|
## Common Mistakes
|
||||||
|
|
||||||
|
- **Dates in blog URLs** — `/blog/2024/01/15/post-title` adds no value and makes URLs long. Use `/blog/post-title`.
|
||||||
|
- **Over-nesting** — `/products/category/subcategory/item/detail` is too deep. Flatten where possible.
|
||||||
|
- **Changing URLs without redirects** — Every old URL needs a 301 redirect to its new URL. Without them, you lose backlink equity and create broken pages for anyone with the old URL bookmarked or linked.
|
||||||
|
- **IDs in URLs** — `/product/12345` is not human-readable. Use slugs.
|
||||||
|
- **Query parameters for content** — `/blog?id=123` should be `/blog/post-title`.
|
||||||
|
- **Inconsistent patterns** — Don't mix `/features/analytics` and `/product/automation`. Pick one parent.
|
||||||
|
|
||||||
|
## Breadcrumb-URL Alignment
|
||||||
|
|
||||||
|
The breadcrumb trail should mirror the URL path:
|
||||||
|
|
||||||
|
| URL | Breadcrumb |
|
||||||
|
|-----|-----------|
|
||||||
|
| `/features/analytics` | Home > Features > Analytics |
|
||||||
|
| `/blog/seo-guide` | Home > Blog > SEO Guide |
|
||||||
|
| `/docs/api/auth` | Home > Docs > API > Authentication |
|
||||||
@@ -0,0 +1,48 @@
|
|||||||
|
# Visual Sitemap Output (Mermaid)
|
||||||
|
|
||||||
|
Use Mermaid `graph TD` for visual sitemaps. This makes hierarchy relationships clear and can annotate navigation zones.
|
||||||
|
|
||||||
|
## Basic Hierarchy
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
graph TD
|
||||||
|
HOME[Homepage] --> FEAT[Features]
|
||||||
|
HOME --> PRICE[Pricing]
|
||||||
|
HOME --> BLOG[Blog]
|
||||||
|
HOME --> ABOUT[About]
|
||||||
|
|
||||||
|
FEAT --> F1[Analytics]
|
||||||
|
FEAT --> F2[Automation]
|
||||||
|
FEAT --> F3[Integrations]
|
||||||
|
|
||||||
|
BLOG --> B1[Post 1]
|
||||||
|
BLOG --> B2[Post 2]
|
||||||
|
```
|
||||||
|
|
||||||
|
## With Navigation Zones
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
graph TD
|
||||||
|
subgraph Header Nav
|
||||||
|
HOME[Homepage]
|
||||||
|
FEAT[Features]
|
||||||
|
PRICE[Pricing]
|
||||||
|
BLOG[Blog]
|
||||||
|
CTA[Get Started]
|
||||||
|
end
|
||||||
|
|
||||||
|
subgraph Footer Nav
|
||||||
|
ABOUT[About]
|
||||||
|
CAREERS[Careers]
|
||||||
|
CONTACT[Contact]
|
||||||
|
PRIVACY[Privacy]
|
||||||
|
end
|
||||||
|
|
||||||
|
HOME --> FEAT
|
||||||
|
HOME --> PRICE
|
||||||
|
HOME --> BLOG
|
||||||
|
HOME --> ABOUT
|
||||||
|
|
||||||
|
FEAT --> F1[Analytics]
|
||||||
|
FEAT --> F2[Automation]
|
||||||
|
```
|
||||||
Reference in new issue
Block a user