Converti chill-theme en dossier classique
This commit is contained in:
Boris Waaub
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,989 @@
|
||||
# Content Creation Guide
|
||||
|
||||
Complete guide to creating and managing content in the Hugo Saasify Theme. Learn how to create different types of pages, blog posts, documentation, and optimize for SEO.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Content Structure](#content-structure)
|
||||
- [Front Matter Reference](#front-matter-reference)
|
||||
- [Page Types](#page-types)
|
||||
- [Blog Posts](#blog-posts)
|
||||
- [Documentation Pages](#documentation-pages)
|
||||
- [Creating Pages](#creating-pages)
|
||||
- [Taxonomies](#taxonomies)
|
||||
- [Media Management](#media-management)
|
||||
- [SEO Optimization](#seo-optimization)
|
||||
|
||||
## Content Structure
|
||||
|
||||
Hugo content is organized in the `content/` directory with a hierarchical structure.
|
||||
|
||||
### Directory Layout
|
||||
|
||||
```
|
||||
content/
|
||||
├── _index.md # Homepage
|
||||
├── blog/
|
||||
│ ├── _index.md # Blog listing page
|
||||
│ ├── my-first-post.md # Blog post
|
||||
│ └── another-post.md # Blog post
|
||||
├── docs/
|
||||
│ ├── _index.md # Docs home
|
||||
│ ├── getting-started/
|
||||
│ │ ├── _index.md
|
||||
│ │ └── installation.md
|
||||
│ └── guides/
|
||||
│ ├── _index.md
|
||||
│ └── advanced.md
|
||||
├── features/
|
||||
│ ├── _index.md
|
||||
│ ├── performance.md
|
||||
│ └── security.md
|
||||
├── pricing.md
|
||||
├── about.md
|
||||
└── contact.md
|
||||
```
|
||||
|
||||
### Content Types
|
||||
|
||||
- **Single Pages**: Individual pages (About, Contact, Pricing)
|
||||
- **List Pages**: Section indexes (`_index.md`)
|
||||
- **Blog Posts**: Content in `blog/` directory
|
||||
- **Documentation**: Content in `docs/` directory
|
||||
- **Custom Types**: Any custom content sections
|
||||
|
||||
## Front Matter Reference
|
||||
|
||||
Front matter is metadata at the top of your markdown files.
|
||||
|
||||
### Common Front Matter
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: "Page Title"
|
||||
date: 2025-10-06
|
||||
lastmod: 2025-10-06
|
||||
draft: false
|
||||
description: "Page description for SEO and social sharing"
|
||||
slug: "custom-url-slug"
|
||||
aliases:
|
||||
- /old-url/
|
||||
- /another-old-url/
|
||||
---
|
||||
```
|
||||
|
||||
### Complete Front Matter Options
|
||||
|
||||
```yaml
|
||||
---
|
||||
# Basic Info
|
||||
title: "Complete Page Title"
|
||||
date: 2025-10-06T10:00:00-07:00
|
||||
lastmod: 2025-10-06T15:30:00-07:00
|
||||
draft: false
|
||||
publishDate: 2025-10-06T10:00:00-07:00
|
||||
expiryDate: 2026-10-06T10:00:00-07:00
|
||||
|
||||
# Content
|
||||
description: "Detailed description for meta tags and previews"
|
||||
summary: "Short summary for listing pages"
|
||||
keywords: ["keyword1", "keyword2", "keyword3"]
|
||||
|
||||
# Layout
|
||||
layout: "single" # or: simple, pricing, company, career, feature
|
||||
type: "blog" # Content type
|
||||
|
||||
# URL
|
||||
slug: "custom-url-slug"
|
||||
url: "/custom/path/"
|
||||
aliases:
|
||||
- /old-path/
|
||||
- /another-old-path/
|
||||
|
||||
# Taxonomies
|
||||
categories: ["Technology", "Web Development"]
|
||||
tags: ["Hugo", "SaaS", "Tutorial"]
|
||||
series: ["Getting Started"]
|
||||
|
||||
# Author
|
||||
author: "John Doe"
|
||||
authors: ["John Doe", "Jane Smith"]
|
||||
|
||||
# Media
|
||||
images:
|
||||
- /images/featured-image.jpg
|
||||
- /images/social-share.jpg
|
||||
|
||||
# SEO
|
||||
robots: "index, follow"
|
||||
canonical: "https://example.com/canonical-url/"
|
||||
|
||||
# Features
|
||||
toc: true # Show table of contents
|
||||
comments: true # Enable comments
|
||||
share: true # Show share buttons
|
||||
featured: true # Mark as featured
|
||||
weight: 10 # Sort order (lower = earlier)
|
||||
|
||||
# Custom Parameters
|
||||
custom_field: "value"
|
||||
---
|
||||
```
|
||||
|
||||
### Field Descriptions
|
||||
|
||||
**Basic Info**:
|
||||
- `title`: Page title (required)
|
||||
- `date`: Publication date
|
||||
- `draft`: If true, page won't be published
|
||||
- `publishDate`: Schedule future publication
|
||||
- `expiryDate`: Auto-expire content
|
||||
|
||||
**Content**:
|
||||
- `description`: Meta description (150-160 chars recommended)
|
||||
- `summary`: Short summary for cards/listings
|
||||
- `keywords`: SEO keywords (optional, less important today)
|
||||
|
||||
**Layout**:
|
||||
- `layout`: Template to use
|
||||
- `type`: Content type for organization
|
||||
|
||||
**URL**:
|
||||
- `slug`: Custom URL slug (defaults to filename)
|
||||
- `url`: Full custom URL path
|
||||
- `aliases`: Redirects from old URLs
|
||||
|
||||
**Taxonomies**:
|
||||
- `categories`: Broad categories
|
||||
- `tags`: Specific tags
|
||||
- `series`: Part of a series
|
||||
|
||||
## Page Types
|
||||
|
||||
### Homepage
|
||||
|
||||
**File**: `content/_index.md`
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: "Home"
|
||||
description: "Build your SaaS faster with our modern Hugo theme"
|
||||
---
|
||||
|
||||
{{< hero
|
||||
headline="Build Your SaaS <span class='text-primary-600'>Faster</span>"
|
||||
sub_headline="A modern, responsive Hugo theme for SaaS companies"
|
||||
primary_button_text="Get Started"
|
||||
primary_button_url="/signup"
|
||||
hero_image="/images/hero.png"
|
||||
>}}
|
||||
|
||||
{{< features-section title="Why Choose Us" >}}
|
||||
{{< feature icon="zap" title="Fast" description="Lightning fast performance" >}}
|
||||
{{< feature icon="lock" title="Secure" description="Enterprise security" >}}
|
||||
{{< /features-section >}}
|
||||
```
|
||||
|
||||
### Simple Page
|
||||
|
||||
For clean, focused content pages.
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: "Privacy Policy"
|
||||
layout: simple
|
||||
description: "Our privacy policy and data handling practices"
|
||||
---
|
||||
|
||||
# Privacy Policy
|
||||
|
||||
Last updated: October 6, 2025
|
||||
|
||||
## Introduction
|
||||
|
||||
Your privacy is important to us...
|
||||
|
||||
## Data Collection
|
||||
|
||||
We collect the following information...
|
||||
```
|
||||
|
||||
**Use Cases**:
|
||||
- Privacy Policy
|
||||
- Terms of Service
|
||||
- Legal pages
|
||||
- Documentation
|
||||
|
||||
### Feature Page
|
||||
|
||||
Showcase a specific feature or product.
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: "Performance Features"
|
||||
layout: feature
|
||||
description: "Lightning-fast performance for your SaaS application"
|
||||
featured_image: "/images/feature-performance.jpg"
|
||||
---
|
||||
|
||||
{{< hero
|
||||
headline="Unmatched Performance"
|
||||
sub_headline="Built for speed from the ground up"
|
||||
hero_image="/images/performance.png"
|
||||
>}}
|
||||
|
||||
## Lightning Fast
|
||||
|
||||
Our platform is optimized for speed...
|
||||
|
||||
{{< stat value="<50ms" label="Response Time" >}}
|
||||
{{< stat value="99.9%" label="Uptime" >}}
|
||||
```
|
||||
|
||||
### Pricing Page
|
||||
|
||||
Display your pricing plans.
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: "Pricing"
|
||||
layout: pricing
|
||||
description: "Choose the perfect plan for your needs"
|
||||
---
|
||||
|
||||
{{< pricing-table-1 >}}
|
||||
{
|
||||
"title": "Simple, Transparent Pricing",
|
||||
"plans": [...]
|
||||
}
|
||||
{{< /pricing-table-1 >}}
|
||||
|
||||
{{< faq >}}
|
||||
{
|
||||
"title": "Pricing FAQ",
|
||||
"questions": [...]
|
||||
}
|
||||
{{< /faq >}}
|
||||
```
|
||||
|
||||
### Company/About Page
|
||||
|
||||
For company information and team pages.
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: "About Us"
|
||||
layout: company
|
||||
description: "Learn about our mission, vision, and team"
|
||||
---
|
||||
|
||||
{{< hero headline="Our Story" sub_headline="Building the future of SaaS" >}}
|
||||
|
||||
## Our Mission
|
||||
|
||||
We're on a mission to...
|
||||
|
||||
{{< stat value="100+" label="Customers" >}}
|
||||
{{< stat value="50+" label="Team Members" >}}
|
||||
{{< stat value="10+" label="Countries" >}}
|
||||
|
||||
## Our Team
|
||||
|
||||
{{< team-member
|
||||
name="Jane Doe"
|
||||
title="CEO & Founder"
|
||||
image="/images/team/jane.jpg"
|
||||
bio="Jane has 15 years of experience..."
|
||||
linkedin="https://linkedin.com/in/janedoe"
|
||||
>}}
|
||||
```
|
||||
|
||||
### Career Page
|
||||
|
||||
Job listings and career information.
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: "Careers"
|
||||
layout: career
|
||||
description: "Join our team and build the future"
|
||||
---
|
||||
|
||||
## Why Work With Us
|
||||
|
||||
Great benefits, amazing culture...
|
||||
|
||||
## Open Positions
|
||||
|
||||
Our job listings are below...
|
||||
```
|
||||
|
||||
### Job Single
|
||||
|
||||
Individual job postings.
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: "Senior Software Engineer"
|
||||
layout: job-single
|
||||
date: 2025-10-06
|
||||
department: "Engineering"
|
||||
location: "Remote"
|
||||
type: "Full-time"
|
||||
salary_range: "$120k - $180k"
|
||||
---
|
||||
|
||||
## About the Role
|
||||
|
||||
We're looking for a senior software engineer...
|
||||
|
||||
## Requirements
|
||||
|
||||
- 5+ years of experience
|
||||
- Strong knowledge of Go/Python
|
||||
- Experience with distributed systems
|
||||
|
||||
## Benefits
|
||||
|
||||
- Competitive salary
|
||||
- Health insurance
|
||||
- Remote work
|
||||
- Unlimited PTO
|
||||
```
|
||||
|
||||
## Blog Posts
|
||||
|
||||
Creating and managing blog content.
|
||||
|
||||
### Creating a Blog Post
|
||||
|
||||
```bash
|
||||
# Create new post
|
||||
hugo new blog/my-awesome-post.md
|
||||
```
|
||||
|
||||
### Blog Post Front Matter
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: "How to Build a SaaS Application"
|
||||
date: 2025-10-06
|
||||
lastmod: 2025-10-06
|
||||
author: "John Doe"
|
||||
description: "Complete guide to building your first SaaS application"
|
||||
categories: ["Tutorials"]
|
||||
tags: ["SaaS", "Web Development", "Tutorial"]
|
||||
featured_image: "/images/blog/saas-guide.jpg"
|
||||
draft: false
|
||||
toc: true
|
||||
---
|
||||
|
||||
Your blog post content here...
|
||||
```
|
||||
|
||||
### Blog Post Structure
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: "Complete Blog Post Example"
|
||||
date: 2025-10-06
|
||||
author: "John Doe"
|
||||
categories: ["Technology"]
|
||||
tags: ["Hugo", "Web Development"]
|
||||
featured_image: "/images/blog/featured.jpg"
|
||||
description: "Learn how to write great blog posts"
|
||||
---
|
||||
|
||||
## Introduction
|
||||
|
||||
Start with a hook that grabs attention...
|
||||
|
||||
## Main Content
|
||||
|
||||
### Subsection 1
|
||||
|
||||
Detailed content with examples...
|
||||
|
||||
```javascript
|
||||
// Code example
|
||||
function example() {
|
||||
return "Hello, World!";
|
||||
}
|
||||
```
|
||||
|
||||
### Subsection 2
|
||||
|
||||
More content...
|
||||
|
||||
## Conclusion
|
||||
|
||||
Wrap up with key takeaways...
|
||||
|
||||
## Further Reading
|
||||
|
||||
- [Related Article 1](#)
|
||||
- [Related Article 2](#)
|
||||
```
|
||||
|
||||
### Blog Features
|
||||
|
||||
**Table of Contents**:
|
||||
```yaml
|
||||
---
|
||||
toc: true
|
||||
---
|
||||
```
|
||||
|
||||
**Featured Image**:
|
||||
```yaml
|
||||
---
|
||||
featured_image: "/images/blog/my-post.jpg"
|
||||
---
|
||||
```
|
||||
|
||||
**Author Info**:
|
||||
```yaml
|
||||
---
|
||||
author: "John Doe"
|
||||
# or multiple authors
|
||||
authors: ["John Doe", "Jane Smith"]
|
||||
---
|
||||
```
|
||||
|
||||
**Categories & Tags**:
|
||||
```yaml
|
||||
---
|
||||
categories: ["Technology", "Business"]
|
||||
tags: ["Hugo", "SaaS", "Web", "Tutorial"]
|
||||
---
|
||||
```
|
||||
|
||||
## Documentation Pages
|
||||
|
||||
Create structured documentation with sidebar navigation.
|
||||
|
||||
### Documentation Structure
|
||||
|
||||
```
|
||||
content/docs/
|
||||
├── _index.md # Docs home
|
||||
├── getting-started/
|
||||
│ ├── _index.md # Section index
|
||||
│ ├── installation.md # weight: 1
|
||||
│ ├── configuration.md # weight: 2
|
||||
│ └── first-steps.md # weight: 3
|
||||
├── guides/
|
||||
│ ├── _index.md
|
||||
│ ├── customization.md
|
||||
│ └── deployment.md
|
||||
└── reference/
|
||||
├── _index.md
|
||||
├── api.md
|
||||
└── configuration.md
|
||||
```
|
||||
|
||||
### Documentation Front Matter
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: "Installation Guide"
|
||||
description: "How to install the theme"
|
||||
weight: 1 # Sort order in sidebar
|
||||
draft: false
|
||||
toc: true # Show table of contents
|
||||
---
|
||||
|
||||
# Installation Guide
|
||||
|
||||
Complete installation instructions...
|
||||
```
|
||||
|
||||
### Documentation Index Pages
|
||||
|
||||
**Section Index** (`_index.md`):
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: "Getting Started"
|
||||
description: "Start here to learn the basics"
|
||||
weight: 1
|
||||
---
|
||||
|
||||
# Getting Started
|
||||
|
||||
Welcome to our documentation!
|
||||
|
||||
## In This Section
|
||||
|
||||
- [Installation](installation/)
|
||||
- [Configuration](configuration/)
|
||||
- [First Steps](first-steps/)
|
||||
```
|
||||
|
||||
### Sidebar Navigation
|
||||
|
||||
The sidebar automatically generates from:
|
||||
1. Directory structure
|
||||
2. `weight` parameter (lower = earlier)
|
||||
3. Front matter titles
|
||||
|
||||
**Example Sidebar Order**:
|
||||
|
||||
```yaml
|
||||
# content/docs/getting-started/_index.md
|
||||
---
|
||||
title: "Getting Started"
|
||||
weight: 1
|
||||
---
|
||||
|
||||
# content/docs/getting-started/installation.md
|
||||
---
|
||||
title: "Installation"
|
||||
weight: 1
|
||||
---
|
||||
|
||||
# content/docs/getting-started/configuration.md
|
||||
---
|
||||
title: "Configuration"
|
||||
weight: 2
|
||||
---
|
||||
|
||||
# content/docs/guides/_index.md
|
||||
---
|
||||
title: "Guides"
|
||||
weight: 2
|
||||
---
|
||||
```
|
||||
|
||||
### Documentation Best Practices
|
||||
|
||||
1. **Hierarchical Structure**: Organize content logically
|
||||
2. **Clear Titles**: Use descriptive, searchable titles
|
||||
3. **Weight Ordering**: Use weights for custom ordering
|
||||
4. **Cross-Linking**: Link related documentation
|
||||
5. **Examples**: Include code examples and screenshots
|
||||
6. **Table of Contents**: Enable TOC for long pages
|
||||
7. **Keep Updated**: Review and update regularly
|
||||
|
||||
### Documentation Features
|
||||
|
||||
**Table of Contents**:
|
||||
```markdown
|
||||
---
|
||||
toc: true
|
||||
---
|
||||
|
||||
{{< toc >}}
|
||||
|
||||
# Your Content
|
||||
```
|
||||
|
||||
**Code Examples**:
|
||||
```markdown
|
||||
{{< code lang="bash" title="Installation" >}}
|
||||
hugo new site mysite
|
||||
{{< /code >}}
|
||||
```
|
||||
|
||||
**Callouts/Alerts**:
|
||||
```markdown
|
||||
> **Note**: Important information here
|
||||
|
||||
> **Warning**: Caution about this action
|
||||
```
|
||||
|
||||
**Cross-References**:
|
||||
```markdown
|
||||
See [Installation Guide](../getting-started/installation/) for details.
|
||||
```
|
||||
|
||||
## Creating Pages
|
||||
|
||||
### Using Hugo CLI
|
||||
|
||||
```bash
|
||||
# Create a blog post
|
||||
hugo new blog/my-post.md
|
||||
|
||||
# Create a documentation page
|
||||
hugo new docs/guides/my-guide.md
|
||||
|
||||
# Create a custom page
|
||||
hugo new features/new-feature.md
|
||||
```
|
||||
|
||||
### Manual Creation
|
||||
|
||||
Create file directly in `content/` directory:
|
||||
|
||||
```bash
|
||||
touch content/about.md
|
||||
```
|
||||
|
||||
Add front matter and content:
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: "About Us"
|
||||
description: "Learn about our company"
|
||||
layout: simple
|
||||
---
|
||||
|
||||
# About Us
|
||||
|
||||
Our story begins...
|
||||
```
|
||||
|
||||
### Content Organization
|
||||
|
||||
**Flat Structure** (simple sites):
|
||||
```
|
||||
content/
|
||||
├── _index.md
|
||||
├── about.md
|
||||
├── pricing.md
|
||||
└── contact.md
|
||||
```
|
||||
|
||||
**Hierarchical Structure** (complex sites):
|
||||
```
|
||||
content/
|
||||
├── _index.md
|
||||
├── blog/
|
||||
│ └── posts...
|
||||
├── docs/
|
||||
│ └── documentation...
|
||||
├── features/
|
||||
│ └── feature pages...
|
||||
└── company/
|
||||
├── about.md
|
||||
├── team.md
|
||||
└── careers/
|
||||
└── jobs...
|
||||
```
|
||||
|
||||
## Taxonomies
|
||||
|
||||
Organize content with categories, tags, and custom taxonomies.
|
||||
|
||||
### Using Categories
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: "My Post"
|
||||
categories: ["Technology", "Web Development"]
|
||||
---
|
||||
```
|
||||
|
||||
**Category Page**: Automatically created at `/categories/technology/`
|
||||
|
||||
### Using Tags
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: "My Post"
|
||||
tags: ["Hugo", "SaaS", "Tutorial", "Beginner"]
|
||||
---
|
||||
```
|
||||
|
||||
**Tag Page**: Automatically created at `/tags/hugo/`
|
||||
|
||||
### Custom Taxonomies
|
||||
|
||||
1. **Define in `hugo.toml`**:
|
||||
```toml
|
||||
[taxonomies]
|
||||
category = 'categories'
|
||||
tag = 'tags'
|
||||
series = 'series'
|
||||
author = 'authors'
|
||||
```
|
||||
|
||||
2. **Use in Content**:
|
||||
```yaml
|
||||
---
|
||||
title: "My Post"
|
||||
series: ["Getting Started Guide"]
|
||||
authors: ["John Doe"]
|
||||
---
|
||||
```
|
||||
|
||||
3. **Access**: `/series/getting-started-guide/`, `/authors/john-doe/`
|
||||
|
||||
### Taxonomy Best Practices
|
||||
|
||||
- **Categories**: Broad topics (5-10 total)
|
||||
- **Tags**: Specific keywords (unlimited)
|
||||
- **Consistent Naming**: Use consistent case and format
|
||||
- **Don't Over-Tag**: 3-7 tags per post is ideal
|
||||
|
||||
## Media Management
|
||||
|
||||
### Images
|
||||
|
||||
**Storage Location**: `static/images/`
|
||||
|
||||
```
|
||||
static/
|
||||
└── images/
|
||||
├── logo.svg
|
||||
├── hero.png
|
||||
├── blog/
|
||||
│ ├── post-1.jpg
|
||||
│ └── post-2.jpg
|
||||
└── team/
|
||||
├── john.jpg
|
||||
└── jane.jpg
|
||||
```
|
||||
|
||||
**Using in Content**:
|
||||
|
||||
```markdown
|
||||
|
||||
```
|
||||
|
||||
**Using with Shortcode**:
|
||||
|
||||
```markdown
|
||||
{{< figure
|
||||
src="/images/diagram.png"
|
||||
alt="System Architecture"
|
||||
caption="Our microservices architecture"
|
||||
>}}
|
||||
```
|
||||
|
||||
### Image Optimization
|
||||
|
||||
**Best Practices**:
|
||||
- Compress images before uploading
|
||||
- Use appropriate formats (WebP, JPEG, PNG)
|
||||
- Use responsive images
|
||||
- Include alt text for accessibility
|
||||
|
||||
**Tools**:
|
||||
- [TinyPNG](https://tinypng.com/) - Compression
|
||||
- [Squoosh](https://squoosh.app/) - Format conversion
|
||||
- ImageOptim (Mac)
|
||||
- ImageMagick (CLI)
|
||||
|
||||
### Featured Images
|
||||
|
||||
**Blog Posts**:
|
||||
```yaml
|
||||
---
|
||||
featured_image: "/images/blog/post-featured.jpg"
|
||||
---
|
||||
```
|
||||
|
||||
**Social Sharing**:
|
||||
```yaml
|
||||
---
|
||||
images:
|
||||
- /images/social-share.jpg
|
||||
---
|
||||
```
|
||||
|
||||
### Videos
|
||||
|
||||
**YouTube Embed**:
|
||||
```markdown
|
||||
{{< youtube VIDEO_ID >}}
|
||||
```
|
||||
|
||||
**Vimeo Embed**:
|
||||
```markdown
|
||||
{{< vimeo VIDEO_ID >}}
|
||||
```
|
||||
|
||||
**Self-Hosted**:
|
||||
```html
|
||||
<video controls>
|
||||
<source src="/videos/demo.mp4" type="video/mp4">
|
||||
Your browser doesn't support video.
|
||||
</video>
|
||||
```
|
||||
|
||||
### Files & Downloads
|
||||
|
||||
**PDFs and Documents**:
|
||||
|
||||
Store in `static/files/`:
|
||||
|
||||
```markdown
|
||||
[Download PDF](/files/whitepaper.pdf)
|
||||
```
|
||||
|
||||
## SEO Optimization
|
||||
|
||||
### Essential SEO Elements
|
||||
|
||||
**Title & Description**:
|
||||
```yaml
|
||||
---
|
||||
title: "How to Build a SaaS Application in 2025"
|
||||
description: "Complete guide to building, launching, and scaling your SaaS application with modern tools and best practices."
|
||||
---
|
||||
```
|
||||
|
||||
**URL Structure**:
|
||||
```yaml
|
||||
---
|
||||
slug: "build-saas-application-2025"
|
||||
---
|
||||
```
|
||||
|
||||
**Canonical URL**:
|
||||
```yaml
|
||||
---
|
||||
canonical: "https://example.com/blog/original-post/"
|
||||
---
|
||||
```
|
||||
|
||||
### Open Graph Tags
|
||||
|
||||
Automatically generated from:
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: "Page Title"
|
||||
description: "Page description"
|
||||
images:
|
||||
- /images/social-share.jpg
|
||||
---
|
||||
```
|
||||
|
||||
### Twitter Cards
|
||||
|
||||
Same as Open Graph:
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: "Twitter-friendly Title"
|
||||
description: "Compelling description under 200 characters"
|
||||
images:
|
||||
- /images/twitter-card.jpg
|
||||
---
|
||||
```
|
||||
|
||||
### Structured Data
|
||||
|
||||
Add JSON-LD structured data for rich results:
|
||||
|
||||
```html
|
||||
<script type="application/ld+json">
|
||||
{
|
||||
"@context": "https://schema.org",
|
||||
"@type": "BlogPosting",
|
||||
"headline": "{{ .Title }}",
|
||||
"description": "{{ .Description }}",
|
||||
"datePublished": "{{ .Date.Format "2006-01-02" }}"
|
||||
}
|
||||
</script>
|
||||
```
|
||||
|
||||
### SEO Best Practices
|
||||
|
||||
1. **Descriptive Titles**: 50-60 characters
|
||||
2. **Meta Descriptions**: 150-160 characters
|
||||
3. **Headings Hierarchy**: Use h1, h2, h3 properly
|
||||
4. **Image Alt Text**: Describe images accurately
|
||||
5. **Internal Linking**: Link related content
|
||||
6. **Fast Loading**: Optimize performance
|
||||
7. **Mobile Friendly**: Ensure responsive design
|
||||
8. **HTTPS**: Use secure connections
|
||||
9. **Sitemap**: Auto-generated by Hugo
|
||||
10. **robots.txt**: Control crawler access
|
||||
|
||||
### Keywords
|
||||
|
||||
```yaml
|
||||
---
|
||||
keywords: ["SaaS", "web development", "Hugo", "tutorial"]
|
||||
---
|
||||
```
|
||||
|
||||
**Note**: Less important for SEO today, but can help with organization.
|
||||
|
||||
## Content Best Practices
|
||||
|
||||
### Writing Guidelines
|
||||
|
||||
1. **Clear Headlines**: Descriptive, engaging titles
|
||||
2. **Short Paragraphs**: 2-3 sentences max
|
||||
3. **Bullet Points**: Break up long lists
|
||||
4. **Visual Elements**: Images, diagrams, videos
|
||||
5. **Code Examples**: Syntax highlighted, tested
|
||||
6. **Internal Links**: Guide readers to related content
|
||||
7. **CTAs**: Clear next steps
|
||||
8. **Proofreading**: Check spelling and grammar
|
||||
|
||||
### Content Workflow
|
||||
|
||||
1. **Plan**: Outline structure and key points
|
||||
2. **Draft**: Write content in markdown
|
||||
3. **Review**: Check for accuracy and clarity
|
||||
4. **Optimize**: Add SEO elements, images
|
||||
5. **Preview**: Test with `hugo server -D`
|
||||
6. **Publish**: Remove `draft: true`
|
||||
7. **Promote**: Share on social media
|
||||
8. **Update**: Review and refresh periodically
|
||||
|
||||
### Markdown Tips
|
||||
|
||||
**Bold & Italic**:
|
||||
```markdown
|
||||
**bold text**
|
||||
*italic text*
|
||||
***bold and italic***
|
||||
```
|
||||
|
||||
**Lists**:
|
||||
```markdown
|
||||
- Unordered item
|
||||
- Another item
|
||||
|
||||
1. Ordered item
|
||||
2. Another ordered item
|
||||
```
|
||||
|
||||
**Links**:
|
||||
```markdown
|
||||
[Link text](https://example.com)
|
||||
[Internal link](/about/)
|
||||
```
|
||||
|
||||
**Code**:
|
||||
```markdown
|
||||
Inline `code` with backticks
|
||||
|
||||
```language
|
||||
code block
|
||||
```
|
||||
```
|
||||
|
||||
**Blockquotes**:
|
||||
```markdown
|
||||
> This is a quote
|
||||
> Second line
|
||||
```
|
||||
|
||||
**Tables**:
|
||||
```markdown
|
||||
| Column 1 | Column 2 |
|
||||
|----------|----------|
|
||||
| Data 1 | Data 2 |
|
||||
```
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [SHORTCODES.md](SHORTCODES.md) - Available shortcodes
|
||||
- [LAYOUTS.md](LAYOUTS.md) - Layout templates
|
||||
- [CONFIGURATION.md](CONFIGURATION.md) - Site configuration
|
||||
- [STYLING.md](STYLING.md) - Styling customization
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [Hugo Content Management](https://gohugo.io/content-management/)
|
||||
- [Markdown Guide](https://www.markdownguide.org/)
|
||||
- [SEO Best Practices](https://developers.google.com/search/docs)
|
||||
- [Schema.org Documentation](https://schema.org/)
|
||||
@@ -0,0 +1,811 @@
|
||||
# Deployment Guide
|
||||
|
||||
Complete guide to deploying your Hugo Saasify Theme site to production. Learn how to deploy to popular platforms and optimize for performance.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Building for Production](#building-for-production)
|
||||
- [Platform Deployment Guides](#platform-deployment-guides)
|
||||
- [Netlify](#netlify)
|
||||
- [Vercel](#vercel)
|
||||
- [GitHub Pages](#github-pages)
|
||||
- [Cloudflare Pages](#cloudflare-pages)
|
||||
- [AWS S3 + CloudFront](#aws-s3--cloudfront)
|
||||
- [Custom Server Deployment](#custom-server-deployment)
|
||||
- [Environment Variables](#environment-variables)
|
||||
- [Performance Optimization](#performance-optimization)
|
||||
- [CI/CD Setup](#cicd-setup)
|
||||
- [Post-Deployment](#post-deployment)
|
||||
|
||||
## Building for Production
|
||||
|
||||
Before deploying, build your site for production.
|
||||
|
||||
### Build Command
|
||||
|
||||
```bash
|
||||
# Basic build
|
||||
hugo
|
||||
|
||||
# Build with minification
|
||||
hugo --minify
|
||||
|
||||
# Build with specific environment
|
||||
hugo --environment production
|
||||
```
|
||||
|
||||
### Build Output
|
||||
|
||||
The build creates a `public/` directory containing:
|
||||
```
|
||||
public/
|
||||
├── index.html
|
||||
├── css/
|
||||
│ └── main.min.[hash].css
|
||||
├── js/
|
||||
│ └── main.min.[hash].js
|
||||
├── images/
|
||||
├── blog/
|
||||
├── docs/
|
||||
└── ...
|
||||
```
|
||||
|
||||
### Pre-Deployment Checklist
|
||||
|
||||
- [ ] Update `baseURL` in `hugo.toml` to production URL
|
||||
- [ ] Remove draft posts (`draft: false` or remove drafts)
|
||||
- [ ] Test build locally: `hugo && hugo server -s public`
|
||||
- [ ] Verify all links work
|
||||
- [ ] Check image paths and assets
|
||||
- [ ] Test responsive design
|
||||
- [ ] Validate HTML/CSS
|
||||
- [ ] Check analytics integration
|
||||
- [ ] Review SEO meta tags
|
||||
- [ ] Test performance with Lighthouse
|
||||
|
||||
### Environment Configuration
|
||||
|
||||
**Development**:
|
||||
```toml
|
||||
# hugo.toml
|
||||
baseURL = "http://localhost:1313/"
|
||||
```
|
||||
|
||||
**Production** (update before deploying):
|
||||
```toml
|
||||
# hugo.toml
|
||||
baseURL = "https://yourdomain.com/"
|
||||
```
|
||||
|
||||
## Platform Deployment Guides
|
||||
|
||||
### Netlify
|
||||
|
||||
Netlify offers automatic deployments from Git with continuous deployment.
|
||||
|
||||
#### Quick Deploy
|
||||
|
||||
1. **Push to Git**:
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "Ready for deployment"
|
||||
git push origin main
|
||||
```
|
||||
|
||||
2. **Connect to Netlify**:
|
||||
- Visit [netlify.com](https://netlify.com)
|
||||
- Click "Add new site" → "Import an existing project"
|
||||
- Choose Git provider (GitHub, GitLab, Bitbucket)
|
||||
- Select your repository
|
||||
|
||||
3. **Configure Build Settings**:
|
||||
- **Build command**: `hugo --minify`
|
||||
- **Publish directory**: `public`
|
||||
- **Production branch**: `main`
|
||||
|
||||
4. **Environment Variables** (click "Show advanced"):
|
||||
```
|
||||
HUGO_VERSION = 0.120.0
|
||||
HUGO_ENV = production
|
||||
```
|
||||
|
||||
5. **Deploy**: Click "Deploy site"
|
||||
|
||||
#### Netlify Configuration File
|
||||
|
||||
Create `netlify.toml` in project root:
|
||||
|
||||
```toml
|
||||
[build]
|
||||
publish = "public"
|
||||
command = "hugo --minify"
|
||||
|
||||
[build.environment]
|
||||
HUGO_VERSION = "0.120.0"
|
||||
HUGO_ENV = "production"
|
||||
HUGO_ENABLEGITINFO = "true"
|
||||
|
||||
[context.production.environment]
|
||||
HUGO_ENV = "production"
|
||||
|
||||
[context.deploy-preview]
|
||||
command = "hugo --minify --buildFuture -b $DEPLOY_PRIME_URL"
|
||||
|
||||
[context.branch-deploy]
|
||||
command = "hugo --minify -b $DEPLOY_PRIME_URL"
|
||||
|
||||
[[redirects]]
|
||||
from = "/old-page"
|
||||
to = "/new-page"
|
||||
status = 301
|
||||
|
||||
[[headers]]
|
||||
for = "/*"
|
||||
[headers.values]
|
||||
X-Frame-Options = "DENY"
|
||||
X-XSS-Protection = "1; mode=block"
|
||||
X-Content-Type-Options = "nosniff"
|
||||
```
|
||||
|
||||
#### Custom Domain
|
||||
|
||||
1. Go to **Site settings** → **Domain management**
|
||||
2. Click "Add custom domain"
|
||||
3. Enter your domain: `yourdomain.com`
|
||||
4. Configure DNS:
|
||||
- **A Record**: Point to Netlify's load balancer IP
|
||||
- **CNAME**: Point `www` to `[your-site].netlify.app`
|
||||
5. Enable HTTPS (automatic with Let's Encrypt)
|
||||
|
||||
### Vercel
|
||||
|
||||
Vercel provides zero-configuration deployments with global CDN.
|
||||
|
||||
#### Deploy to Vercel
|
||||
|
||||
1. **Install Vercel CLI** (optional):
|
||||
```bash
|
||||
npm install -g vercel
|
||||
```
|
||||
|
||||
2. **Deploy via CLI**:
|
||||
```bash
|
||||
vercel
|
||||
```
|
||||
|
||||
Or deploy via web interface:
|
||||
|
||||
3. **Connect Repository**:
|
||||
- Visit [vercel.com](https://vercel.com)
|
||||
- Click "Add New" → "Project"
|
||||
- Import your Git repository
|
||||
|
||||
4. **Configure Project**:
|
||||
- **Framework Preset**: Hugo
|
||||
- **Build Command**: `hugo --minify`
|
||||
- **Output Directory**: `public`
|
||||
- **Install Command**: Leave empty
|
||||
|
||||
5. **Environment Variables**:
|
||||
```
|
||||
HUGO_VERSION=0.120.0
|
||||
```
|
||||
|
||||
6. **Deploy**: Click "Deploy"
|
||||
|
||||
#### Vercel Configuration
|
||||
|
||||
Create `vercel.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"build": {
|
||||
"env": {
|
||||
"HUGO_VERSION": "0.120.0"
|
||||
}
|
||||
},
|
||||
"redirects": [
|
||||
{
|
||||
"source": "/old-page",
|
||||
"destination": "/new-page",
|
||||
"permanent": true
|
||||
}
|
||||
],
|
||||
"headers": [
|
||||
{
|
||||
"source": "/(.*)",
|
||||
"headers": [
|
||||
{
|
||||
"key": "X-Frame-Options",
|
||||
"value": "DENY"
|
||||
},
|
||||
{
|
||||
"key": "X-Content-Type-Options",
|
||||
"value": "nosniff"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### GitHub Pages
|
||||
|
||||
Free hosting directly from your GitHub repository.
|
||||
|
||||
#### Setup GitHub Pages
|
||||
|
||||
1. **Create Repository**:
|
||||
- Name: `username.github.io` (user site)
|
||||
- Or: `repository-name` (project site)
|
||||
|
||||
2. **Update Base URL**:
|
||||
```toml
|
||||
# hugo.toml
|
||||
baseURL = "https://username.github.io/"
|
||||
# or for project site:
|
||||
baseURL = "https://username.github.io/repository-name/"
|
||||
```
|
||||
|
||||
3. **Create GitHub Action**:
|
||||
|
||||
`.github/workflows/hugo.yml`:
|
||||
|
||||
```yaml
|
||||
name: Deploy Hugo site to Pages
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: ["main"]
|
||||
workflow_dispatch:
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
pages: write
|
||||
id-token: write
|
||||
|
||||
concurrency:
|
||||
group: "pages"
|
||||
cancel-in-progress: false
|
||||
|
||||
defaults:
|
||||
run:
|
||||
shell: bash
|
||||
|
||||
jobs:
|
||||
build:
|
||||
runs-on: ubuntu-latest
|
||||
env:
|
||||
HUGO_VERSION: 0.120.0
|
||||
steps:
|
||||
- name: Install Hugo CLI
|
||||
run: |
|
||||
wget -O ${{ runner.temp }}/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb \
|
||||
&& sudo dpkg -i ${{ runner.temp }}/hugo.deb
|
||||
|
||||
- name: Checkout
|
||||
uses: actions/checkout@v4
|
||||
with:
|
||||
submodules: recursive
|
||||
|
||||
- name: Setup Pages
|
||||
id: pages
|
||||
uses: actions/configure-pages@v4
|
||||
|
||||
- name: Install Node.js dependencies
|
||||
run: |
|
||||
cp themes/chill-theme/package.json .
|
||||
cp themes/chill-theme/postcss.config.js .
|
||||
cp themes/chill-theme/tailwind.config.copy.js ./tailwind.config.js
|
||||
npm install
|
||||
|
||||
- name: Build with Hugo
|
||||
env:
|
||||
HUGO_ENVIRONMENT: production
|
||||
HUGO_ENV: production
|
||||
run: |
|
||||
hugo \
|
||||
--minify \
|
||||
--baseURL "${{ steps.pages.outputs.base_url }}/"
|
||||
|
||||
- name: Upload artifact
|
||||
uses: actions/upload-pages-artifact@v2
|
||||
with:
|
||||
path: ./public
|
||||
|
||||
deploy:
|
||||
environment:
|
||||
name: github-pages
|
||||
url: ${{ steps.deployment.outputs.page_url }}
|
||||
runs-on: ubuntu-latest
|
||||
needs: build
|
||||
steps:
|
||||
- name: Deploy to GitHub Pages
|
||||
id: deployment
|
||||
uses: actions/deploy-pages@v3
|
||||
```
|
||||
|
||||
4. **Enable GitHub Pages**:
|
||||
- Go to repository **Settings** → **Pages**
|
||||
- **Source**: GitHub Actions
|
||||
- Save
|
||||
|
||||
5. **Push and Deploy**:
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "Deploy to GitHub Pages"
|
||||
git push origin main
|
||||
```
|
||||
|
||||
### Cloudflare Pages
|
||||
|
||||
Fast, global CDN with automatic deployments.
|
||||
|
||||
#### Deploy to Cloudflare Pages
|
||||
|
||||
1. **Connect Repository**:
|
||||
- Visit [pages.cloudflare.com](https://pages.cloudflare.com)
|
||||
- Click "Create a project"
|
||||
- Connect your Git account
|
||||
- Select repository
|
||||
|
||||
2. **Configure Build**:
|
||||
- **Framework preset**: Hugo
|
||||
- **Build command**: `hugo --minify`
|
||||
- **Build output directory**: `public`
|
||||
- **Root directory**: Leave blank
|
||||
|
||||
3. **Environment Variables**:
|
||||
```
|
||||
HUGO_VERSION=0.120.0
|
||||
```
|
||||
|
||||
4. **Deploy**: Click "Save and Deploy"
|
||||
|
||||
#### Custom Domain
|
||||
|
||||
1. Go to project → **Custom domains**
|
||||
2. Add your domain
|
||||
3. Configure DNS (Cloudflare handles this automatically)
|
||||
4. SSL/TLS is automatic
|
||||
|
||||
### AWS S3 + CloudFront
|
||||
|
||||
Enterprise-grade hosting with AWS infrastructure.
|
||||
|
||||
#### S3 Setup
|
||||
|
||||
1. **Create S3 Bucket**:
|
||||
```bash
|
||||
aws s3 mb s3://your-bucket-name --region us-east-1
|
||||
```
|
||||
|
||||
2. **Enable Static Website Hosting**:
|
||||
```bash
|
||||
aws s3 website s3://your-bucket-name \
|
||||
--index-document index.html \
|
||||
--error-document 404.html
|
||||
```
|
||||
|
||||
3. **Set Bucket Policy**:
|
||||
|
||||
Create `bucket-policy.json`:
|
||||
```json
|
||||
{
|
||||
"Version": "2012-10-17",
|
||||
"Statement": [
|
||||
{
|
||||
"Sid": "PublicReadGetObject",
|
||||
"Effect": "Allow",
|
||||
"Principal": "*",
|
||||
"Action": "s3:GetObject",
|
||||
"Resource": "arn:aws:s3:::your-bucket-name/*"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Apply:
|
||||
```bash
|
||||
aws s3api put-bucket-policy \
|
||||
--bucket your-bucket-name \
|
||||
--policy file://bucket-policy.json
|
||||
```
|
||||
|
||||
4. **Deploy Site**:
|
||||
```bash
|
||||
hugo --minify
|
||||
aws s3 sync public/ s3://your-bucket-name --delete
|
||||
```
|
||||
|
||||
#### CloudFront Setup
|
||||
|
||||
1. **Create Distribution**:
|
||||
- Origin: Your S3 bucket
|
||||
- Viewer protocol: Redirect HTTP to HTTPS
|
||||
- Price class: Choose based on needs
|
||||
- Alternate domain names: your-domain.com
|
||||
- SSL certificate: Request from ACM
|
||||
|
||||
2. **Configure DNS**:
|
||||
- Add CNAME record pointing to CloudFront distribution
|
||||
|
||||
3. **Invalidate Cache After Deployment**:
|
||||
```bash
|
||||
aws cloudfront create-invalidation \
|
||||
--distribution-id YOUR_DISTRIBUTION_ID \
|
||||
--paths "/*"
|
||||
```
|
||||
|
||||
#### Deployment Script
|
||||
|
||||
Create `deploy.sh`:
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
|
||||
# Build site
|
||||
echo "Building site..."
|
||||
hugo --minify
|
||||
|
||||
# Sync to S3
|
||||
echo "Uploading to S3..."
|
||||
aws s3 sync public/ s3://your-bucket-name \
|
||||
--delete \
|
||||
--cache-control "max-age=3600"
|
||||
|
||||
# Invalidate CloudFront cache
|
||||
echo "Invalidating CloudFront cache..."
|
||||
aws cloudfront create-invalidation \
|
||||
--distribution-id YOUR_DISTRIBUTION_ID \
|
||||
--paths "/*"
|
||||
|
||||
echo "Deployment complete!"
|
||||
```
|
||||
|
||||
Make executable:
|
||||
```bash
|
||||
chmod +x deploy.sh
|
||||
./deploy.sh
|
||||
```
|
||||
|
||||
## Custom Server Deployment
|
||||
|
||||
### Nginx
|
||||
|
||||
1. **Build Site**:
|
||||
```bash
|
||||
hugo --minify
|
||||
```
|
||||
|
||||
2. **Upload to Server**:
|
||||
```bash
|
||||
rsync -avz --delete public/ user@server:/var/www/html/
|
||||
```
|
||||
|
||||
3. **Nginx Configuration**:
|
||||
|
||||
`/etc/nginx/sites-available/yoursite`:
|
||||
|
||||
```nginx
|
||||
server {
|
||||
listen 80;
|
||||
listen [::]:80;
|
||||
server_name yourdomain.com www.yourdomain.com;
|
||||
return 301 https://$server_name$request_uri;
|
||||
}
|
||||
|
||||
server {
|
||||
listen 443 ssl http2;
|
||||
listen [::]:443 ssl http2;
|
||||
server_name yourdomain.com www.yourdomain.com;
|
||||
|
||||
ssl_certificate /path/to/cert.pem;
|
||||
ssl_certificate_key /path/to/key.pem;
|
||||
|
||||
root /var/www/html;
|
||||
index index.html;
|
||||
|
||||
location / {
|
||||
try_files $uri $uri/ =404;
|
||||
}
|
||||
|
||||
# Cache static assets
|
||||
location ~* \.(jpg|jpeg|png|gif|ico|css|js|svg|woff|woff2)$ {
|
||||
expires 1y;
|
||||
add_header Cache-Control "public, immutable";
|
||||
}
|
||||
|
||||
# Security headers
|
||||
add_header X-Frame-Options "DENY" always;
|
||||
add_header X-Content-Type-Options "nosniff" always;
|
||||
add_header X-XSS-Protection "1; mode=block" always;
|
||||
|
||||
# Gzip compression
|
||||
gzip on;
|
||||
gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;
|
||||
}
|
||||
```
|
||||
|
||||
4. **Enable Site**:
|
||||
```bash
|
||||
sudo ln -s /etc/nginx/sites-available/yoursite /etc/nginx/sites-enabled/
|
||||
sudo nginx -t
|
||||
sudo systemctl reload nginx
|
||||
```
|
||||
|
||||
### Apache
|
||||
|
||||
**Apache Configuration**:
|
||||
|
||||
`/etc/apache2/sites-available/yoursite.conf`:
|
||||
|
||||
```apache
|
||||
<VirtualHost *:80>
|
||||
ServerName yourdomain.com
|
||||
ServerAlias www.yourdomain.com
|
||||
Redirect permanent / https://yourdomain.com/
|
||||
</VirtualHost>
|
||||
|
||||
<VirtualHost *:443>
|
||||
ServerName yourdomain.com
|
||||
ServerAlias www.yourdomain.com
|
||||
|
||||
DocumentRoot /var/www/html
|
||||
|
||||
SSLEngine on
|
||||
SSLCertificateFile /path/to/cert.pem
|
||||
SSLCertificateKeyFile /path/to/key.pem
|
||||
|
||||
<Directory /var/www/html>
|
||||
Options -Indexes +FollowSymLinks
|
||||
AllowOverride All
|
||||
Require all granted
|
||||
</Directory>
|
||||
|
||||
# Cache static files
|
||||
<FilesMatch "\.(jpg|jpeg|png|gif|ico|css|js|svg|woff|woff2)$">
|
||||
Header set Cache-Control "max-age=31536000, public, immutable"
|
||||
</FilesMatch>
|
||||
|
||||
# Compression
|
||||
<IfModule mod_deflate.c>
|
||||
AddOutputFilterByType DEFLATE text/html text/plain text/xml text/css application/javascript
|
||||
</IfModule>
|
||||
</VirtualHost>
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
|
||||
### Common Variables
|
||||
|
||||
```bash
|
||||
# Hugo version
|
||||
HUGO_VERSION=0.120.0
|
||||
|
||||
# Environment
|
||||
HUGO_ENV=production
|
||||
|
||||
# Enable Git info
|
||||
HUGO_ENABLEGITINFO=true
|
||||
|
||||
# Google Analytics
|
||||
HUGO_GOOGLE_ANALYTICS=G-XXXXXXXXXX
|
||||
|
||||
# Google Tag Manager
|
||||
HUGO_GOOGLE_TAG_MANAGER=GTM-XXXXXXX
|
||||
```
|
||||
|
||||
### Platform-Specific
|
||||
|
||||
**Netlify** - Set in UI or `netlify.toml`
|
||||
**Vercel** - Set in UI or `vercel.json`
|
||||
**GitHub Actions** - Use secrets
|
||||
**AWS** - Use Parameter Store or Secrets Manager
|
||||
|
||||
## Performance Optimization
|
||||
|
||||
### Build Optimization
|
||||
|
||||
1. **Minify Output**:
|
||||
```bash
|
||||
hugo --minify
|
||||
```
|
||||
|
||||
2. **Enable Caching**:
|
||||
```toml
|
||||
[caches]
|
||||
[caches.images]
|
||||
dir = ":resourceDir/_gen"
|
||||
maxAge = "1440h"
|
||||
```
|
||||
|
||||
3. **Optimize Images**:
|
||||
- Compress before uploading
|
||||
- Use WebP format
|
||||
- Implement lazy loading
|
||||
|
||||
### CDN Configuration
|
||||
|
||||
**Cache Headers**:
|
||||
```nginx
|
||||
# Static assets - 1 year
|
||||
location ~* \.(jpg|png|css|js|woff2)$ {
|
||||
expires 1y;
|
||||
add_header Cache-Control "public, immutable";
|
||||
}
|
||||
|
||||
# HTML - short cache
|
||||
location ~* \.html$ {
|
||||
expires 1h;
|
||||
add_header Cache-Control "public, must-revalidate";
|
||||
}
|
||||
```
|
||||
|
||||
### Compression
|
||||
|
||||
Enable gzip/brotli compression on server or CDN.
|
||||
|
||||
**Nginx**:
|
||||
```nginx
|
||||
gzip on;
|
||||
gzip_types text/plain text/css application/json application/javascript;
|
||||
gzip_min_length 1000;
|
||||
```
|
||||
|
||||
### Performance Checklist
|
||||
|
||||
- [ ] Enable minification
|
||||
- [ ] Optimize images (compress, WebP)
|
||||
- [ ] Use CDN for static assets
|
||||
- [ ] Enable HTTP/2
|
||||
- [ ] Configure caching headers
|
||||
- [ ] Enable gzip/brotli compression
|
||||
- [ ] Lazy load images
|
||||
- [ ] Minimize CSS/JS
|
||||
- [ ] Use resource hints (preload, prefetch)
|
||||
- [ ] Test with Lighthouse/PageSpeed
|
||||
|
||||
## CI/CD Setup
|
||||
|
||||
### GitHub Actions
|
||||
|
||||
Already covered in [GitHub Pages](#github-pages) section.
|
||||
|
||||
### GitLab CI/CD
|
||||
|
||||
`.gitlab-ci.yml`:
|
||||
|
||||
```yaml
|
||||
image: registry.gitlab.com/pages/hugo/hugo_extended:latest
|
||||
|
||||
variables:
|
||||
GIT_SUBMODULE_STRATEGY: recursive
|
||||
|
||||
pages:
|
||||
script:
|
||||
- cp themes/chill-theme/package.json .
|
||||
- cp themes/chill-theme/postcss.config.js .
|
||||
- cp themes/chill-theme/tailwind.config.copy.js ./tailwind.config.js
|
||||
- npm install
|
||||
- hugo --minify
|
||||
artifacts:
|
||||
paths:
|
||||
- public
|
||||
only:
|
||||
- main
|
||||
```
|
||||
|
||||
### CircleCI
|
||||
|
||||
`.circleci/config.yml`:
|
||||
|
||||
```yaml
|
||||
version: 2.1
|
||||
|
||||
jobs:
|
||||
build:
|
||||
docker:
|
||||
- image: cibuilds/hugo:latest
|
||||
steps:
|
||||
- checkout
|
||||
- run:
|
||||
name: Install theme dependencies
|
||||
command: |
|
||||
cp themes/chill-theme/package.json .
|
||||
cp themes/chill-theme/postcss.config.js .
|
||||
cp themes/chill-theme/tailwind.config.copy.js ./tailwind.config.js
|
||||
npm install
|
||||
- run:
|
||||
name: Build site
|
||||
command: hugo --minify
|
||||
- run:
|
||||
name: Deploy
|
||||
command: |
|
||||
# Your deployment command
|
||||
```
|
||||
|
||||
## Post-Deployment
|
||||
|
||||
### Verification
|
||||
|
||||
1. **Check Site Loads**: Visit your domain
|
||||
2. **Test Navigation**: Click through all pages
|
||||
3. **Verify Assets**: Images, CSS, JS loading
|
||||
4. **Check Forms**: Test contact/signup forms
|
||||
5. **Test Mobile**: Responsive design working
|
||||
6. **Check Analytics**: Tracking installed correctly
|
||||
7. **SSL Certificate**: HTTPS working
|
||||
8. **Performance**: Run Lighthouse audit
|
||||
|
||||
### Monitoring
|
||||
|
||||
- **Uptime Monitoring**: UptimeRobot, Pingdom
|
||||
- **Analytics**: Google Analytics, Plausible
|
||||
- **Error Tracking**: Sentry, Rollbar
|
||||
- **Performance**: Lighthouse CI, SpeedCurve
|
||||
|
||||
### Maintenance
|
||||
|
||||
1. **Regular Updates**: Keep Hugo and dependencies updated
|
||||
2. **Content Review**: Update outdated content
|
||||
3. **Backup**: Regular backups of content and config
|
||||
4. **Security**: Monitor for vulnerabilities
|
||||
5. **Performance**: Regular performance audits
|
||||
|
||||
## Troubleshooting Deployment
|
||||
|
||||
### Build Fails
|
||||
|
||||
**Problem**: Build fails with errors
|
||||
|
||||
**Solutions**:
|
||||
- Check Hugo version matches local
|
||||
- Verify all dependencies installed
|
||||
- Check for syntax errors in config
|
||||
- Review build logs for specific errors
|
||||
|
||||
### Assets Not Loading
|
||||
|
||||
**Problem**: CSS/JS/Images not loading
|
||||
|
||||
**Solutions**:
|
||||
- Verify `baseURL` is correct
|
||||
- Check asset paths are absolute (`/images/...`)
|
||||
- Clear browser cache
|
||||
- Check CDN/server configuration
|
||||
|
||||
### 404 Errors
|
||||
|
||||
**Problem**: Pages return 404
|
||||
|
||||
**Solutions**:
|
||||
- Verify content files exist
|
||||
- Check front matter is correct
|
||||
- Ensure `draft: false`
|
||||
- Check URL structure
|
||||
|
||||
### Slow Build Times
|
||||
|
||||
**Problem**: Builds taking too long
|
||||
|
||||
**Solutions**:
|
||||
- Enable caching
|
||||
- Optimize images before build
|
||||
- Remove unused content
|
||||
- Check for infinite loops in templates
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [INSTALLATION.md](INSTALLATION.md) - Installation guide
|
||||
- [CONFIGURATION.md](CONFIGURATION.md) - Configuration options
|
||||
- [TROUBLESHOOTING.md](TROUBLESHOOTING.md) - Common issues
|
||||
- [Performance Optimization](https://gohugo.io/troubleshooting/build-performance/)
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [Netlify Docs](https://docs.netlify.com/)
|
||||
- [Vercel Docs](https://vercel.com/docs)
|
||||
- [GitHub Pages Docs](https://docs.github.com/en/pages)
|
||||
- [Cloudflare Pages Docs](https://developers.cloudflare.com/pages)
|
||||
- [AWS S3 Static Hosting](https://docs.aws.amazon.com/AmazonS3/latest/userguide/WebsiteHosting.html)
|
||||
@@ -0,0 +1,644 @@
|
||||
# Installation Guide
|
||||
|
||||
Complete guide to installing and setting up the Hugo Saasify Theme for your SaaS website.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Prerequisites](#prerequisites)
|
||||
- [Installation Methods](#installation-methods)
|
||||
- [Method 1: New Site](#method-1-new-site)
|
||||
- [Method 2: Existing Site](#method-2-existing-site)
|
||||
- [Method 3: Manual Installation](#method-3-manual-installation)
|
||||
- [Initial Configuration](#initial-configuration)
|
||||
- [Verifying Installation](#verifying-installation)
|
||||
- [Next Steps](#next-steps)
|
||||
- [Updating the Theme](#updating-the-theme)
|
||||
- [Troubleshooting](#troubleshooting)
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before installing the Hugo Saasify Theme, ensure you have the following installed on your system:
|
||||
|
||||
### Required Software
|
||||
|
||||
1. **Hugo Extended** (v0.80.0 or later)
|
||||
- The theme requires Hugo Extended edition for Tailwind CSS processing
|
||||
- Download from [Hugo Releases](https://github.com/gohugoio/hugo/releases)
|
||||
- Verify installation: `hugo version`
|
||||
- Expected output should include "extended"
|
||||
|
||||
2. **Git** (latest version recommended)
|
||||
- Required for theme installation and updates
|
||||
- Download from [git-scm.com](https://git-scm.com/)
|
||||
- Verify installation: `git --version`
|
||||
|
||||
3. **Node.js and npm** (v14.0.0 or later)
|
||||
- Required for Tailwind CSS compilation
|
||||
- Download from [nodejs.org](https://nodejs.org/)
|
||||
- Verify installation: `node --version` and `npm --version`
|
||||
|
||||
### System Requirements
|
||||
|
||||
- Operating System: Windows, macOS, or Linux
|
||||
- Disk Space: At least 100MB free
|
||||
- Internet Connection: Required for initial setup and dependencies
|
||||
|
||||
### Recommended Tools
|
||||
|
||||
- Code editor (VS Code, Sublime Text, or similar)
|
||||
- Terminal/Command line familiarity
|
||||
- Basic understanding of Hugo and Markdown
|
||||
|
||||
## Installation Methods
|
||||
|
||||
Choose the installation method that best fits your use case.
|
||||
|
||||
### Method 1: New Site
|
||||
|
||||
This is the recommended method if you're starting a new project from scratch.
|
||||
|
||||
#### Step 1: Create a New Hugo Site
|
||||
|
||||
```bash
|
||||
# Create a new Hugo site
|
||||
hugo new site my-saas-website
|
||||
|
||||
# Navigate into the new site directory
|
||||
cd my-saas-website
|
||||
```
|
||||
|
||||
#### Step 2: Initialize Git Repository
|
||||
|
||||
```bash
|
||||
# Initialize git repository
|
||||
git init
|
||||
|
||||
# Create initial commit
|
||||
git add .
|
||||
git commit -m "Initial commit"
|
||||
```
|
||||
|
||||
#### Step 3: Add the Theme as a Git Submodule
|
||||
|
||||
```bash
|
||||
# Add theme as submodule
|
||||
git submodule add https://github.com/chaoming/chill-theme.git themes/chill-theme
|
||||
|
||||
# Update submodule
|
||||
git submodule update --init --recursive
|
||||
```
|
||||
|
||||
#### Step 4: Example Site (Optional)
|
||||
|
||||
The theme comes with a fully functional example site that demonstrates its features and capabilities. You can use this as a reference when building your own site.
|
||||
|
||||
##### Using the Example Site
|
||||
|
||||
The example site provides a great starting point to understand how to:
|
||||
|
||||
- Structure your content
|
||||
- Use different page layouts
|
||||
- Configure navigation menus
|
||||
- Set up site parameters
|
||||
- Implement common SaaS website features
|
||||
|
||||
1. Copy the example site content:
|
||||
|
||||
```bash
|
||||
cp -r themes/chill-theme/exampleSite/* .
|
||||
```
|
||||
|
||||
The example site includes:
|
||||
|
||||
- Complete content structure with sample pages
|
||||
- Blog posts with various layouts
|
||||
- Feature pages
|
||||
- Career/Jobs section
|
||||
- Pricing page
|
||||
- Company information page
|
||||
- Properly configured hugo.toml
|
||||
|
||||
#### Step 5: Install Dependencies
|
||||
|
||||
```bash
|
||||
# Copy package.json and other config files to your site root
|
||||
cp themes/chill-theme/package.json .
|
||||
cp themes/chill-theme/postcss.config.js .
|
||||
cp themes/chill-theme/tailwind.config.copy.js ./tailwind.config.js
|
||||
```
|
||||
|
||||
```bash
|
||||
# Install dependencies
|
||||
npm install
|
||||
```
|
||||
|
||||
#### Step 6: Set the theme in hugo.toml
|
||||
|
||||
Open your `hugo.toml` and check that the theme is correctly set:
|
||||
|
||||
```toml
|
||||
# Theme Configuration
|
||||
theme = "chill-theme"
|
||||
```
|
||||
|
||||
#### Step 7: Start Development Server
|
||||
|
||||
```bash
|
||||
# Start development server (builds TailwindCSS and runs Hugo server)
|
||||
npm run start
|
||||
|
||||
# Your site will be available at http://localhost:1313
|
||||
```
|
||||
|
||||
### Method 2: Existing Site
|
||||
|
||||
If you already have a Hugo site and want to add the Saasify theme.
|
||||
|
||||
#### Step 1: Add Theme as Submodule
|
||||
|
||||
```bash
|
||||
# From your site root directory
|
||||
git submodule add https://github.com/chaoming/chill-theme.git themes/chill-theme
|
||||
|
||||
# Update submodule
|
||||
git submodule update --init --recursive
|
||||
```
|
||||
|
||||
#### Step 2: Update Configuration
|
||||
|
||||
Add or update the following in your `hugo.toml`:
|
||||
|
||||
```toml
|
||||
theme = "chill-theme"
|
||||
|
||||
# Required Features
|
||||
pygmentsCodeFences = true
|
||||
pygmentsUseClasses = true
|
||||
enableEmoji = true
|
||||
enableGitInfo = true
|
||||
|
||||
# Required Module Configuration
|
||||
[module]
|
||||
[module.hugoVersion]
|
||||
extended = true
|
||||
min = "0.80.0"
|
||||
|
||||
# Required Build Configuration
|
||||
[build]
|
||||
writeStats = true
|
||||
|
||||
# Required Markup Configuration
|
||||
[markup]
|
||||
[markup.highlight]
|
||||
noClasses = false
|
||||
lineNos = true
|
||||
codeFences = true
|
||||
[markup.goldmark.renderer]
|
||||
unsafe = true
|
||||
[markup.tableOfContents]
|
||||
endLevel = 3
|
||||
ordered = false
|
||||
startLevel = 2
|
||||
```
|
||||
|
||||
#### Step 3: Install Theme Dependencies
|
||||
|
||||
```bash
|
||||
# Copy package.json and other config files to your site root
|
||||
cp themes/chill-theme/package.json .
|
||||
cp themes/chill-theme/postcss.config.js .
|
||||
cp themes/chill-theme/tailwind.config.copy.js ./tailwind.config.js
|
||||
|
||||
# Install dependencies
|
||||
npm install
|
||||
```
|
||||
|
||||
#### Step 4: Configure Theme Settings
|
||||
|
||||
Copy relevant configuration from the example site:
|
||||
|
||||
```bash
|
||||
# View example configuration for reference
|
||||
cat themes/chill-theme/exampleSite/hugo.toml
|
||||
```
|
||||
|
||||
Merge the configuration settings into your existing `hugo.toml`. See [CONFIGURATION.md](CONFIGURATION.md) for detailed options.
|
||||
|
||||
#### Step 5: Test the Theme
|
||||
|
||||
```bash
|
||||
# Start development server
|
||||
npm run start
|
||||
```
|
||||
|
||||
### Method 3: Manual Installation
|
||||
|
||||
For users who prefer not to use Git submodules or need more control over the installation.
|
||||
|
||||
#### Step 1: Download Theme
|
||||
|
||||
```bash
|
||||
# Download and extract theme
|
||||
curl -L https://github.com/chaoming/chill-theme/archive/refs/heads/main.zip -o theme.zip
|
||||
unzip theme.zip
|
||||
mv chill-theme-main themes/chill-theme
|
||||
rm theme.zip
|
||||
```
|
||||
|
||||
Alternatively, download the ZIP file from GitHub and extract it manually to `themes/chill-theme`.
|
||||
|
||||
#### Step 2: Install Dependencies
|
||||
|
||||
```bash
|
||||
# Copy package.json and other config files to your site root
|
||||
cp themes/chill-theme/package.json .
|
||||
cp themes/chill-theme/postcss.config.js .
|
||||
cp themes/chill-theme/tailwind.config.copy.js ./tailwind.config.js
|
||||
|
||||
# Install dependencies
|
||||
npm install
|
||||
```
|
||||
|
||||
#### Step 3: Configure Hugo
|
||||
|
||||
Update your `hugo.toml` to reference the theme:
|
||||
|
||||
```toml
|
||||
theme = "chill-theme"
|
||||
```
|
||||
|
||||
Add all required configuration settings from the example site.
|
||||
|
||||
#### Step 4: Verify Installation
|
||||
|
||||
```bash
|
||||
# Check theme is recognized
|
||||
hugo config
|
||||
|
||||
# Start development server
|
||||
npm run start
|
||||
```
|
||||
|
||||
## Initial Configuration
|
||||
|
||||
After installing the theme, configure the essential settings.
|
||||
|
||||
### Basic Configuration
|
||||
|
||||
Edit your `hugo.toml` file:
|
||||
|
||||
```toml
|
||||
# Basic Configuration
|
||||
baseURL = "/"
|
||||
languageCode = "en-us"
|
||||
title = "Your Site Title"
|
||||
theme = "chill-theme"
|
||||
|
||||
# Required Features
|
||||
pygmentsCodeFences = true # Enable syntax highlighting
|
||||
pygmentsUseClasses = true
|
||||
enableEmoji = true # Enable emoji support
|
||||
enableGitInfo = true # Enable Git info for lastmod
|
||||
|
||||
# Required Module Configuration
|
||||
[module]
|
||||
[module.hugoVersion]
|
||||
extended = true
|
||||
min = "0.80.0"
|
||||
|
||||
# Required Build Configuration
|
||||
[build]
|
||||
writeStats = true # Required for TailwindCSS
|
||||
|
||||
# Required Markup Configuration
|
||||
[markup]
|
||||
[markup.highlight]
|
||||
noClasses = false
|
||||
lineNos = true
|
||||
codeFences = true
|
||||
[markup.goldmark.renderer]
|
||||
unsafe = true # Allow HTML in markdown
|
||||
[markup.tableOfContents]
|
||||
endLevel = 3
|
||||
ordered = false
|
||||
startLevel = 2
|
||||
|
||||
# Theme Parameters
|
||||
[params]
|
||||
description = "Your site description"
|
||||
author = "Your Name"
|
||||
logo = "/images/logo.svg"
|
||||
```
|
||||
|
||||
### Tailwind CSS Setup
|
||||
|
||||
The theme uses Tailwind CSS for styling. The build process is integrated into Hugo.
|
||||
|
||||
During installation, you should have copied the Tailwind configuration file:
|
||||
|
||||
- `tailwind.config.js` - Copied from `themes/chill-theme/tailwind.config.copy.js` to your site root
|
||||
- `postcss.config.js` - PostCSS configuration in your site root
|
||||
- Dependencies installed via `npm install`
|
||||
|
||||
The `npm run start` command automatically watches and compiles Tailwind CSS during development.
|
||||
|
||||
### Menu Configuration
|
||||
|
||||
Add your navigation menu to `hugo.toml`:
|
||||
|
||||
```toml
|
||||
[menu]
|
||||
[[menu.main]]
|
||||
name = "Features"
|
||||
weight = 1
|
||||
[menu.main.params]
|
||||
has_submenu = true
|
||||
submenu = [
|
||||
{ name = "Feature 1", url = "/features/feature-1/" },
|
||||
{ name = "Feature 2", url = "/features/feature-2/" }
|
||||
]
|
||||
|
||||
[[menu.main]]
|
||||
name = "Pricing"
|
||||
url = "/pricing"
|
||||
weight = 2
|
||||
|
||||
[[menu.main]]
|
||||
name = "Blog"
|
||||
url = "/blog"
|
||||
weight = 3
|
||||
```
|
||||
|
||||
See [CONFIGURATION.md](CONFIGURATION.md) for complete menu options.
|
||||
|
||||
## Verifying Installation
|
||||
|
||||
### Check Hugo Version
|
||||
|
||||
```bash
|
||||
hugo version
|
||||
```
|
||||
|
||||
Expected output should include "extended" and version 0.80.0 or higher.
|
||||
|
||||
### Check Theme Files
|
||||
|
||||
```bash
|
||||
# Verify theme directory structure
|
||||
ls -la themes/chill-theme/
|
||||
|
||||
# Should show:
|
||||
# - layouts/
|
||||
# - assets/
|
||||
# - static/
|
||||
# - exampleSite/
|
||||
# - package.json
|
||||
# - tailwind.config.js
|
||||
```
|
||||
|
||||
### Test Development Server
|
||||
|
||||
```bash
|
||||
# Start server
|
||||
npm run start
|
||||
|
||||
# Check for errors in terminal
|
||||
# Visit http://localhost:1313 in browser
|
||||
```
|
||||
|
||||
### Verify Build Output
|
||||
|
||||
```bash
|
||||
# Build site
|
||||
hugo
|
||||
|
||||
# Check public directory was created
|
||||
ls public/
|
||||
|
||||
# Should contain:
|
||||
# - index.html
|
||||
# - css/
|
||||
# - js/
|
||||
# - images/
|
||||
```
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Starting the Development Server
|
||||
|
||||
To start the development server with live reload and TailwindCSS compilation:
|
||||
|
||||
```bash
|
||||
npm run start
|
||||
```
|
||||
|
||||
This will:
|
||||
|
||||
- Watch for changes in your TailwindCSS styles
|
||||
- Run the Hugo development server
|
||||
- Automatically rebuild when changes are detected
|
||||
- Serve your site at <http://localhost:1313>
|
||||
|
||||
### Building for Production
|
||||
|
||||
To build your site for production:
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
```
|
||||
|
||||
This will:
|
||||
|
||||
- Build and minify your TailwindCSS styles
|
||||
- Generate minified Hugo site in the `public` directory
|
||||
|
||||
## Next Steps
|
||||
|
||||
After successful installation:
|
||||
|
||||
1. **Customize Configuration**: Review [CONFIGURATION.md](CONFIGURATION.md) for all available options
|
||||
2. **Create Content**: Learn about content creation in [CONTENT-CREATION.md](CONTENT-CREATION.md)
|
||||
3. **Customize Styling**: See [STYLING.md](STYLING.md) for theme customization
|
||||
4. **Add Pages**: Use available layouts documented in [LAYOUTS.md](LAYOUTS.md)
|
||||
5. **Use Shortcodes**: Explore components in [SHORTCODES.md](SHORTCODES.md)
|
||||
6. **Deploy**: Follow deployment guides in [DEPLOYMENT.md](DEPLOYMENT.md)
|
||||
|
||||
## Updating the Theme
|
||||
|
||||
### For Git Submodule Installations
|
||||
|
||||
```bash
|
||||
# Update to latest version
|
||||
git submodule update --remote themes/chill-theme
|
||||
|
||||
# If there are npm dependency updates, copy the updated files
|
||||
cp themes/chill-theme/package.json .
|
||||
cp themes/chill-theme/postcss.config.js .
|
||||
cp themes/chill-theme/tailwind.config.copy.js ./tailwind.config.js
|
||||
npm install
|
||||
|
||||
# Commit the update
|
||||
git add themes/chill-theme
|
||||
git commit -m "Update chill-theme"
|
||||
```
|
||||
|
||||
### For Manual Installations
|
||||
|
||||
```bash
|
||||
# Backup your current theme (if you made custom changes)
|
||||
cp -r themes/chill-theme themes/chill-theme-backup
|
||||
|
||||
# Download latest version
|
||||
curl -L https://github.com/chaoming/chill-theme/archive/refs/heads/main.zip -o theme.zip
|
||||
unzip theme.zip
|
||||
rm -rf themes/chill-theme
|
||||
mv chill-theme-main themes/chill-theme
|
||||
rm theme.zip
|
||||
|
||||
# Copy updated config files and install dependencies
|
||||
cp themes/chill-theme/package.json .
|
||||
cp themes/chill-theme/postcss.config.js .
|
||||
cp themes/chill-theme/tailwind.config.copy.js ./tailwind.config.js
|
||||
npm install
|
||||
```
|
||||
|
||||
### Update Best Practices
|
||||
|
||||
1. **Always backup** before updating
|
||||
2. **Review changelog** for breaking changes
|
||||
3. **Test locally** before deploying updates
|
||||
4. **Check configuration** for new options
|
||||
5. **Update dependencies** after theme updates
|
||||
|
||||
### Version Pinning
|
||||
|
||||
To pin to a specific version using Git submodule:
|
||||
|
||||
```bash
|
||||
cd themes/chill-theme
|
||||
git checkout v1.0.0 # Replace with desired version tag
|
||||
cd ../..
|
||||
git add themes/chill-theme
|
||||
git commit -m "Pin theme to v1.0.0"
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Theme Not Found
|
||||
|
||||
**Problem**: Hugo can't find the theme
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
# Check theme directory exists
|
||||
ls themes/
|
||||
|
||||
# Verify theme name in hugo.toml matches directory name
|
||||
grep "^theme" hugo.toml
|
||||
|
||||
# Should output: theme = "chill-theme"
|
||||
```
|
||||
|
||||
### Extended Version Error
|
||||
|
||||
**Problem**: Error about Hugo Extended being required
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
# Check Hugo version includes "extended"
|
||||
hugo version
|
||||
|
||||
# If not extended, download extended version from:
|
||||
# https://github.com/gohugoio/hugo/releases
|
||||
```
|
||||
|
||||
### CSS Not Loading
|
||||
|
||||
**Problem**: Site loads without styling
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
# Ensure build stats are enabled in hugo.toml
|
||||
[build]
|
||||
writeStats = true
|
||||
|
||||
# Ensure theme dependencies are installed in site root
|
||||
cp themes/chill-theme/package.json .
|
||||
cp themes/chill-theme/postcss.config.js .
|
||||
cp themes/chill-theme/tailwind.config.copy.js ./tailwind.config.js
|
||||
npm install
|
||||
|
||||
# Clear Hugo cache
|
||||
hugo --gc
|
||||
|
||||
# Rebuild and start server
|
||||
npm run start
|
||||
```
|
||||
|
||||
### Submodule Empty
|
||||
|
||||
**Problem**: Theme directory exists but is empty
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
# Initialize and update submodules
|
||||
git submodule init
|
||||
git submodule update --recursive
|
||||
|
||||
# If still empty, remove and re-add
|
||||
git submodule deinit -f themes/chill-theme
|
||||
rm -rf .git/modules/themes/chill-theme
|
||||
git rm -f themes/chill-theme
|
||||
git submodule add https://github.com/chaoming/chill-theme.git themes/chill-theme
|
||||
```
|
||||
|
||||
### npm Dependencies Error
|
||||
|
||||
**Problem**: npm install fails
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
# Clear npm cache
|
||||
npm cache clean --force
|
||||
|
||||
# Delete node_modules and reinstall in site root
|
||||
rm -rf node_modules package-lock.json
|
||||
npm install
|
||||
```
|
||||
|
||||
### Port Already in Use
|
||||
|
||||
**Problem**: Hugo server won't start due to port conflict
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
# Use different port (modify package.json start script to add --port flag)
|
||||
# Or find and kill process using port 1313
|
||||
lsof -ti:1313 | xargs kill -9 # macOS/Linux
|
||||
# For Windows, use: netstat -ano | findstr :1313
|
||||
|
||||
# Then restart
|
||||
npm run start
|
||||
```
|
||||
|
||||
For more troubleshooting help, see [TROUBLESHOOTING.md](TROUBLESHOOTING.md) or visit the [GitHub Issues](https://github.com/chaoming/chill-theme/issues) page.
|
||||
|
||||
## Getting Help
|
||||
|
||||
If you encounter issues not covered in this guide:
|
||||
|
||||
1. Check [TROUBLESHOOTING.md](TROUBLESHOOTING.md)
|
||||
2. Review [example site configuration](../exampleSite/)
|
||||
3. Search [GitHub Issues](https://github.com/chaoming/chill-theme/issues)
|
||||
4. Create a new issue with:
|
||||
- Hugo version (`hugo version`)
|
||||
- Operating system
|
||||
- Error messages
|
||||
- Steps to reproduce
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [Hugo Documentation](https://gohugo.io/documentation/)
|
||||
- [Tailwind CSS Documentation](https://tailwindcss.com/docs)
|
||||
- [Theme Repository](https://github.com/chaoming/chill-theme)
|
||||
- [Demo Site](https://saasify-demo.chaoming.li)
|
||||
@@ -0,0 +1,737 @@
|
||||
# Internationalization (i18n) Guide
|
||||
|
||||
Complete guide for implementing multilingual support in Hugo Saasify Theme.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Overview](#overview)
|
||||
- [Quick Start](#quick-start)
|
||||
- [Configuration](#configuration)
|
||||
- [Language Preference Persistence](#language-preference-persistence)
|
||||
- [Translation Keys](#translation-keys)
|
||||
- [Content Organization](#content-organization)
|
||||
- [Date Formatting](#date-formatting)
|
||||
- [Common Issues](#common-issues)
|
||||
- [Adding a New Language](#adding-a-new-language)
|
||||
|
||||
## Overview
|
||||
|
||||
Hugo Saasify Theme provides full multilingual support with:
|
||||
- Automatic language switcher in the header
|
||||
- Persistent language preference (remembers user's choice)
|
||||
- 40+ translation keys for UI elements
|
||||
- Language-specific content directories
|
||||
- Language-specific menus and parameters
|
||||
- Date format localization
|
||||
- Translated blog sidebar, post navigation, and more
|
||||
|
||||
## Quick Start
|
||||
|
||||
The theme comes with **three fully implemented language examples** in the demo site:
|
||||
- **English** (`en`) - Default language
|
||||
- **Chinese** (`zh-cn`) - Complete translation
|
||||
- **German** (`de`) - Complete translation
|
||||
|
||||
You can use these as references when adding your own languages.
|
||||
|
||||
### Basic Setup
|
||||
|
||||
1. **Configure languages in `hugo.toml`:**
|
||||
|
||||
```toml
|
||||
defaultContentLanguage = "en"
|
||||
|
||||
[languages]
|
||||
[languages.en]
|
||||
languageCode = "en-us"
|
||||
languageName = "English"
|
||||
title = "Your Site"
|
||||
weight = 1
|
||||
contentDir = "content"
|
||||
|
||||
[languages.zh-cn]
|
||||
languageCode = "zh-cn"
|
||||
languageName = "简体中文"
|
||||
title = "Your Site"
|
||||
weight = 2
|
||||
contentDir = "content/zh-cn"
|
||||
```
|
||||
|
||||
**Tip:** Check the demo site's `hugo.toml` for complete English, Chinese, and German configurations you can copy and adapt.
|
||||
|
||||
2. **Copy translation files:**
|
||||
|
||||
```bash
|
||||
# Copy English translations (already included in theme)
|
||||
cp themes/chill-theme/i18n/en.toml i18n/en.toml
|
||||
|
||||
# Copy Chinese example and rename
|
||||
cp themes/chill-theme/docs/zh-cn.toml.example i18n/zh-cn.toml
|
||||
```
|
||||
|
||||
3. **Create language-specific content:**
|
||||
|
||||
```
|
||||
content/
|
||||
├── _index.md # English homepage
|
||||
├── blog/
|
||||
│ └── my-post.md # English blog post
|
||||
└── zh-cn/
|
||||
├── _index.md # Chinese homepage
|
||||
└── blog/
|
||||
└── my-post.md # Chinese blog post
|
||||
```
|
||||
|
||||
4. **Configure language-specific menus:**
|
||||
|
||||
```toml
|
||||
# English menu
|
||||
[[languages.en.menu.main]]
|
||||
name = "Blog"
|
||||
url = "/blog"
|
||||
weight = 1
|
||||
|
||||
# Chinese menu
|
||||
[[languages.zh-cn.menu.main]]
|
||||
name = "博客"
|
||||
url = "/zh-cn/blog"
|
||||
weight = 1
|
||||
```
|
||||
|
||||
The language switcher will automatically appear in the header!
|
||||
|
||||
## Configuration
|
||||
|
||||
### Language Preference Persistence
|
||||
|
||||
**New Feature:** The theme now automatically remembers the user's language preference using browser localStorage. This provides a seamless multilingual experience.
|
||||
|
||||
#### How It Works
|
||||
|
||||
1. **First Visit**: User sees the default language (no redirect)
|
||||
2. **User Selects Language**: When clicking a language in the switcher:
|
||||
- Their preference is saved to localStorage
|
||||
- They navigate to the selected language
|
||||
3. **Return Visits**: On subsequent page loads:
|
||||
- The system checks for a saved preference
|
||||
- If found, automatically redirects to their preferred language
|
||||
- This happens once per session to avoid interfering with manual navigation
|
||||
|
||||
#### User Experience Examples
|
||||
|
||||
**Scenario 1: New User**
|
||||
```
|
||||
1. User lands on https://example.com/ (English, default)
|
||||
2. Clicks "简体中文" in language switcher
|
||||
3. Navigates to https://example.com/zh-cn/
|
||||
4. Preference saved: zh-cn
|
||||
5. Next visit: automatically redirects to Chinese version
|
||||
```
|
||||
|
||||
**Scenario 2: Deep Links**
|
||||
```
|
||||
1. User has preference: zh-cn
|
||||
2. Clicks link to https://example.com/blog/my-post
|
||||
3. Auto-redirects to https://example.com/zh-cn/blog/my-post
|
||||
4. Original path preserved, just language changed
|
||||
```
|
||||
|
||||
**Scenario 3: Manual Navigation**
|
||||
```
|
||||
1. User has preference: zh-cn (currently on Chinese site)
|
||||
2. Types https://example.com/en/contact directly in address bar
|
||||
3. Sees English contact page (no forced redirect)
|
||||
4. Can still use language switcher to change languages
|
||||
```
|
||||
|
||||
#### Technical Details
|
||||
|
||||
- **Storage**: Uses browser `localStorage` with key `hugo_preferred_language`
|
||||
- **Fallback**: Works gracefully without JavaScript (standard links still function)
|
||||
- **Privacy**: Stored locally in user's browser only
|
||||
- **Session Safety**: Uses `sessionStorage` flag to prevent redirect loops
|
||||
- **Progressive Enhancement**: Site works perfectly with JavaScript disabled
|
||||
|
||||
#### Disabling the Feature
|
||||
|
||||
If you want to disable language preference persistence:
|
||||
|
||||
1. Remove the script include from `layouts/_default/baseof.html`:
|
||||
```html
|
||||
<!-- Remove or comment out these lines: -->
|
||||
{{ if .Site.IsMultiLingual }}
|
||||
<script src="{{ "js/language-preference.js" | relURL }}"></script>
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
2. Or delete the file: `static/js/language-preference.js`
|
||||
|
||||
The language switcher will still work; it just won't remember the user's choice.
|
||||
|
||||
#### Automatic Language Detection with VisitorAPI
|
||||
|
||||
**New Feature:** The theme supports automatic language detection using [VisitorAPI](https://visitorapi.com/) to detect the visitor's language based on their location.
|
||||
|
||||
##### How It Works
|
||||
|
||||
1. **Every Page Load (No Stored Preference)**: If the user has no stored language preference:
|
||||
- The system calls VisitorAPI on every page load to detect the visitor's language
|
||||
- If a matching language is available, the user is automatically redirected
|
||||
- The detected language is stored as their preference for future visits
|
||||
2. **After Preference is Stored**: Once a language preference is saved (either from auto-detection or manual selection):
|
||||
- Uses the stored preference (no API call)
|
||||
- Fast redirect based on localStorage
|
||||
3. **Manual Selection**: User can always override by selecting a different language
|
||||
|
||||
##### Setup Instructions
|
||||
|
||||
1. **Sign up for VisitorAPI**:
|
||||
- Visit [visitorapi.com](https://visitorapi.com/) and create a free account
|
||||
- Create a new project to get your Project ID
|
||||
|
||||
2. **Add the Project ID to your configuration**:
|
||||
|
||||
```toml
|
||||
[params]
|
||||
# VisitorAPI Project ID for automatic language detection
|
||||
# Set this to enable auto-detection of visitor's language
|
||||
# If not set, language detection will be disabled
|
||||
visitorapi_pid = "YOUR_PROJECT_ID_HERE"
|
||||
```
|
||||
|
||||
3. **That's it!** The feature is automatically enabled when the Project ID is configured.
|
||||
|
||||
##### How Language Matching Works
|
||||
|
||||
The system uses **dynamic language matching** based on the first two characters of language codes. This means it automatically works for any language you add to Hugo without requiring any code changes.
|
||||
|
||||
**Matching Logic:**
|
||||
|
||||
- VisitorAPI returns language codes like `"en"`, `"zh"`, `"de"`, `"fr"`, `"es"`, `"pt"`, etc.
|
||||
- The system extracts the first 2 characters from the VisitorAPI response
|
||||
- It compares these with the first 2 characters of your Hugo language codes
|
||||
- When they match, the user is redirected to that language
|
||||
|
||||
**Examples:**
|
||||
|
||||
- VisitorAPI returns `"en"` → Matches Hugo language `"en"` ✓
|
||||
- VisitorAPI returns `"zh"` or `"zho"` → Matches Hugo language `"zh-cn"` ✓ (both start with "zh")
|
||||
- VisitorAPI returns `"de"` or `"deu"` → Matches Hugo language `"de"` ✓
|
||||
- VisitorAPI returns `"pt"` or `"por"` → Matches Hugo language `"pt"` or `"pt-br"` ✓
|
||||
- VisitorAPI returns `"es"` or `"spa"` → Matches Hugo language `"es"` ✓
|
||||
- VisitorAPI returns `"fr"` or `"fra"` → Matches Hugo language `"fr"` or `"fr-ca"` ✓
|
||||
|
||||
**Adding a New Language:**
|
||||
|
||||
When you add a new language to your Hugo site, VisitorAPI auto-detection will automatically work for it:
|
||||
|
||||
1. Add the language to your `hugo.toml`:
|
||||
|
||||
```toml
|
||||
[languages.ja]
|
||||
languageCode = "ja-jp"
|
||||
languageName = "日本語"
|
||||
# ... rest of config
|
||||
```
|
||||
|
||||
2. That's it! The system will automatically detect visitors from Japan and redirect them to `/ja/` because:
|
||||
- VisitorAPI will return `"ja"` or `"jpn"` for Japanese visitors
|
||||
- The first 2 characters (`"ja"`) match your Hugo language code `"ja"`
|
||||
- No code changes needed
|
||||
|
||||
**Technical Details:**
|
||||
|
||||
The matching happens in `language-preference.js`:
|
||||
|
||||
```javascript
|
||||
// Extract first 2 characters from VisitorAPI response (e.g., "zh" from "zh" or "zho")
|
||||
var langPrefix = visitorLang.substring(0, 2);
|
||||
|
||||
// Get all available Hugo languages from the language switcher
|
||||
var languageLinks = document.querySelectorAll('.language-switch-link');
|
||||
|
||||
// Compare first 2 characters with each Hugo language
|
||||
for (var j = 0; j < languageLinks.length; j++) {
|
||||
var hugoLang = languageLinks[j].getAttribute('data-lang');
|
||||
var hugoPrefix = hugoLang.substring(0, 2);
|
||||
|
||||
if (langPrefix === hugoPrefix) {
|
||||
// Match found! Redirect to this language
|
||||
detectedLang = hugoLang;
|
||||
break;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
This approach ensures:
|
||||
- No hardcoded language mappings to maintain
|
||||
- Automatic support for any language you add
|
||||
- Works with both 2-character codes (`"en"`) and extended codes (`"zh-cn"`)
|
||||
- Handles VisitorAPI's various language code formats (ISO 639-1 and ISO 639-2)
|
||||
|
||||
##### Privacy & Performance
|
||||
|
||||
- **API Call**: Called on every page load when no language preference is stored
|
||||
- **Caching**: Once a language is detected and stored, no more API calls are made
|
||||
- **Efficient**: After first detection, uses localStorage for instant redirects
|
||||
- **Fallback**: Works gracefully if API is unavailable
|
||||
- **No Tracking**: VisitorAPI detects language, doesn't track user behavior
|
||||
- **User Control**: Users can clear localStorage to reset and re-detect
|
||||
|
||||
##### Disabling Auto-Detection
|
||||
|
||||
To disable automatic language detection while keeping manual preference persistence:
|
||||
|
||||
1. Simply remove or comment out the `visitorapi_pid` parameter from your `hugo.toml`
|
||||
2. Or set it to an empty string: `visitorapi_pid = ""`
|
||||
|
||||
The language preference system will continue to work; it just won't auto-detect on first visit.
|
||||
|
||||
### Basic Setup
|
||||
|
||||
```toml
|
||||
# Set the default language
|
||||
defaultContentLanguage = "en"
|
||||
|
||||
# Whether to include default language in URL path
|
||||
# false: English at / (example.com/)
|
||||
# true: English at /en/ (example.com/en/)
|
||||
defaultContentLanguageInSubdir = false
|
||||
```
|
||||
|
||||
### Language-Specific Parameters
|
||||
|
||||
Each language can have its own configuration for CTAs, headers, etc:
|
||||
|
||||
```toml
|
||||
[languages.en.params.cta]
|
||||
enable = true
|
||||
title = "Ready to Get Started?"
|
||||
description = "Join companies using our platform"
|
||||
[languages.en.params.cta.primary_button]
|
||||
text = "Get Started Free"
|
||||
url = "/get-started"
|
||||
|
||||
[languages.zh-cn.params.cta]
|
||||
enable = true
|
||||
title = "准备好开始了吗？"
|
||||
description = "加入使用我们平台的公司"
|
||||
[languages.zh-cn.params.cta.primary_button]
|
||||
text = "免费开始"
|
||||
url = "/zh-cn/get-started"
|
||||
```
|
||||
|
||||
### Sidebar Configuration
|
||||
|
||||
**Important:** Do NOT set title/description/text in global sidebar config, as this overrides i18n translations:
|
||||
|
||||
```toml
|
||||
# ❌ DON'T: This prevents translation
|
||||
[params.blog.sidebar.recent]
|
||||
enable = true
|
||||
title = "Recent Articles" # This overrides i18n
|
||||
|
||||
# ✅ DO: Let i18n handle the translations
|
||||
[params.blog.sidebar.recent]
|
||||
enable = true
|
||||
count = 5 # Only set non-text configuration
|
||||
```
|
||||
|
||||
## Translation Keys
|
||||
|
||||
### Complete List
|
||||
|
||||
The theme includes 40+ translation keys. Here are the most important ones:
|
||||
|
||||
#### Blog & Content
|
||||
- `readMore` - "Read More" link text
|
||||
- `readTime` - Reading time suffix
|
||||
- `categories` - Categories heading
|
||||
- `tags` - Tags heading
|
||||
|
||||
#### Blog Post
|
||||
- `tableOfContents` - TOC heading
|
||||
- `minRead` - Reading time text
|
||||
- `previousPost` - Previous navigation
|
||||
- `nextPost` - Next navigation
|
||||
- `dateFormat` - Date format string
|
||||
|
||||
#### Blog Sidebar
|
||||
- `recentArticles` - Recent articles heading
|
||||
- `popularTags` - Popular tags heading
|
||||
- `subscribeNewsletter` - Newsletter heading
|
||||
- `subscribeDescription` - Newsletter description
|
||||
- `emailPlaceholder` - Email input placeholder
|
||||
- `subscribe` - Subscribe button
|
||||
|
||||
#### Navigation
|
||||
- `previous` - Previous page
|
||||
- `next` - Next page
|
||||
- `documentation` - Documentation heading
|
||||
- `language` - Language label
|
||||
|
||||
#### Features & Pricing
|
||||
- `seeItInAction` - Feature demo heading
|
||||
- `popular` - Popular badge
|
||||
- `mostPopular` - Most popular badge
|
||||
- `perMonth` - Pricing suffix
|
||||
|
||||
#### Homepage
|
||||
- `trustedByCompanies` - Company logos heading
|
||||
- `lovedByTeams` - Testimonials heading
|
||||
|
||||
For the complete list with default values, see `themes/chill-theme/i18n/en.toml`
|
||||
|
||||
### Example Translation File
|
||||
|
||||
**i18n/en.toml:**
|
||||
```toml
|
||||
[readMore]
|
||||
other = "Read More"
|
||||
|
||||
[minRead]
|
||||
other = "min read"
|
||||
|
||||
[previousPost]
|
||||
other = "Previous Post"
|
||||
|
||||
[nextPost]
|
||||
other = "Next Post"
|
||||
|
||||
[dateFormat]
|
||||
other = "January 2, 2006"
|
||||
```
|
||||
|
||||
**i18n/zh-cn.toml:**
|
||||
```toml
|
||||
[readMore]
|
||||
other = "阅读更多"
|
||||
|
||||
[minRead]
|
||||
other = "分钟阅读"
|
||||
|
||||
[previousPost]
|
||||
other = "上一篇"
|
||||
|
||||
[nextPost]
|
||||
other = "下一篇"
|
||||
|
||||
[dateFormat]
|
||||
other = "2006年1月2日"
|
||||
```
|
||||
|
||||
## Content Organization
|
||||
|
||||
### Directory Structure
|
||||
|
||||
```
|
||||
content/
|
||||
├── _index.md # English homepage
|
||||
├── blog/
|
||||
│ ├── post-1.md # English blog posts
|
||||
│ └── post-2.md
|
||||
├── features/
|
||||
│ └── performance.md # English feature page
|
||||
└── zh-cn/ # Chinese content
|
||||
├── _index.md # Chinese homepage
|
||||
├── blog/
|
||||
│ ├── post-1.md # Chinese blog posts
|
||||
│ └── post-2.md
|
||||
└── features/
|
||||
└── performance.md # Chinese feature page
|
||||
```
|
||||
|
||||
### Creating Translated Content
|
||||
|
||||
1. **Duplicate the structure** from your default language
|
||||
2. **Translate the content** including front matter
|
||||
3. **Keep the same file names** for better URL consistency
|
||||
|
||||
**Example - English post:**
|
||||
```yaml
|
||||
---
|
||||
title: "Getting Started with Hugo"
|
||||
date: 2024-01-15
|
||||
categories: ["Tutorial"]
|
||||
tags: ["hugo", "web development"]
|
||||
---
|
||||
Content in English...
|
||||
```
|
||||
|
||||
**Example - Chinese post:**
|
||||
```yaml
|
||||
---
|
||||
title: "Hugo入门指南"
|
||||
date: 2024-01-15
|
||||
categories: ["教程"]
|
||||
tags: ["hugo", "网站开发"]
|
||||
---
|
||||
中文内容...
|
||||
```
|
||||
|
||||
## Date Formatting
|
||||
|
||||
The theme uses the `dateFormat` i18n key for locale-specific date formatting:
|
||||
|
||||
```toml
|
||||
# English format
|
||||
[dateFormat]
|
||||
other = "January 2, 2006" # Output: July 20, 2023
|
||||
|
||||
# Chinese format
|
||||
[dateFormat]
|
||||
other = "2006年1月2日" # Output: 2023年7月20日
|
||||
|
||||
# French format example
|
||||
[dateFormat]
|
||||
other = "2 January 2006" # Output: 20 juillet 2023
|
||||
```
|
||||
|
||||
Hugo's date format reference:
|
||||
- `2006` - Year (4 digits)
|
||||
- `06` - Year (2 digits)
|
||||
- `January` - Month (full name)
|
||||
- `Jan` - Month (abbreviated)
|
||||
- `01` - Month (2 digits)
|
||||
- `1` - Month (1-2 digits)
|
||||
- `02` - Day (2 digits)
|
||||
- `2` - Day (1-2 digits)
|
||||
- `Monday` - Weekday (full name)
|
||||
- `Mon` - Weekday (abbreviated)
|
||||
|
||||
## Common Issues
|
||||
|
||||
### Issue: Sidebar Still Showing English
|
||||
|
||||
**Problem:** Blog sidebar shows English text even in Chinese version.
|
||||
|
||||
**Solution:** Remove hardcoded titles from global `[params.blog.sidebar]` configuration. The theme's i18n will handle the translations automatically.
|
||||
|
||||
```toml
|
||||
# Remove these from global config:
|
||||
[params.blog.sidebar.recent]
|
||||
enable = true
|
||||
# title = "Recent Articles" ← Remove this
|
||||
count = 5
|
||||
```
|
||||
|
||||
### Issue: Language Switcher Not Appearing
|
||||
|
||||
**Problem:** Language switcher doesn't show in header.
|
||||
|
||||
**Solution:** Ensure you have defined multiple languages in your `hugo.toml`:
|
||||
|
||||
```toml
|
||||
[languages]
|
||||
[languages.en]
|
||||
# ...
|
||||
[languages.zh-cn]
|
||||
# ...
|
||||
```
|
||||
|
||||
The language switcher automatically appears when 2+ languages are configured.
|
||||
|
||||
### Issue: Wrong Language on Home Link
|
||||
|
||||
**Problem:** Logo/home link goes to wrong language homepage.
|
||||
|
||||
**Solution:** This is already fixed in the theme. The header uses `{{ "/" | relLangURL }}` which automatically links to the correct language homepage.
|
||||
|
||||
## Adding a New Language
|
||||
|
||||
Let's add French as an example.
|
||||
|
||||
### Quick Reference (For Experienced Users)
|
||||
|
||||
If you're familiar with Hugo i18n, here's what you need:
|
||||
|
||||
1. **Config:** `hugo.toml` - Add `languages.fr` section with `languageCode`, `languageName`, `title`, `weight`, `contentDir`
|
||||
2. **Translations:** `i18n/fr.toml` - Copy from `i18n/en.toml` and translate all keys
|
||||
3. **Content:** `content/fr/` - Create directory structure and translate content
|
||||
4. **Menus:** `languages.fr.menu.main` + 3 footer menus
|
||||
5. **Params:** `languages.fr.params` - **Must include**: `cta`, `footer` (with uppercase column titles), `header`, `blog`
|
||||
|
||||
**Critical:** Don't forget the `footer` configuration - it's required for footer to display correctly!
|
||||
|
||||
### Detailed Step-by-Step Guide
|
||||
|
||||
### 1. Add Language Configuration
|
||||
|
||||
```toml
|
||||
[languages.fr]
|
||||
languageCode = "fr-fr"
|
||||
languageName = "Français"
|
||||
title = "Votre Site"
|
||||
weight = 3
|
||||
contentDir = "content/fr"
|
||||
```
|
||||
|
||||
### 2. Create Translation File
|
||||
|
||||
Copy the example and translate:
|
||||
|
||||
```bash
|
||||
cp themes/chill-theme/docs/zh-cn.toml.example i18n/fr.toml
|
||||
```
|
||||
|
||||
Edit `i18n/fr.toml`:
|
||||
```toml
|
||||
[readMore]
|
||||
other = "Lire la suite"
|
||||
|
||||
[minRead]
|
||||
other = "min de lecture"
|
||||
|
||||
[previousPost]
|
||||
other = "Article précédent"
|
||||
|
||||
[nextPost]
|
||||
other = "Article suivant"
|
||||
|
||||
[dateFormat]
|
||||
other = "2 January 2006"
|
||||
|
||||
[recentArticles]
|
||||
other = "Articles récents"
|
||||
|
||||
[categories]
|
||||
other = "Catégories"
|
||||
|
||||
[popularTags]
|
||||
other = "Tags populaires"
|
||||
|
||||
# ... translate all keys
|
||||
```
|
||||
|
||||
### 3. Create French Content
|
||||
|
||||
```
|
||||
content/fr/
|
||||
├── _index.md
|
||||
├── blog/
|
||||
└── features/
|
||||
```
|
||||
|
||||
### 4. Configure French Menu
|
||||
|
||||
```toml
|
||||
[[languages.fr.menu.main]]
|
||||
name = "Fonctionnalités"
|
||||
url = "/fr/features"
|
||||
weight = 1
|
||||
|
||||
[[languages.fr.menu.main]]
|
||||
name = "Blog"
|
||||
url = "/fr/blog"
|
||||
weight = 2
|
||||
```
|
||||
|
||||
### 5. Language-Specific Parameters (Required)
|
||||
|
||||
Configure language-specific parameters for your new language. **Important:** These parameters are required for proper navigation and UI display.
|
||||
|
||||
```toml
|
||||
# French language specific params
|
||||
[languages.fr.params]
|
||||
# Global CTA Configuration
|
||||
[languages.fr.params.cta]
|
||||
enable = true
|
||||
title = "Prêt à commencer?"
|
||||
description = "Rejoignez les entreprises qui utilisent notre plateforme"
|
||||
gradient_from = "#2563eb"
|
||||
gradient_to = "#7c3aed"
|
||||
gradient_angle = 30
|
||||
[languages.fr.params.cta.primary_button]
|
||||
text = "Commencer"
|
||||
url = "/fr/get-started"
|
||||
[languages.fr.params.cta.secondary_button]
|
||||
text = "Démo"
|
||||
url = "/fr/demo"
|
||||
|
||||
# Footer Configuration (IMPORTANT - Required for footer to display correctly)
|
||||
[languages.fr.params.footer]
|
||||
column_1_title = "FONCTIONNALITÉS"
|
||||
column_2_title = "ENTREPRISE"
|
||||
column_3_title = "LÉGAL"
|
||||
|
||||
# Header Configuration
|
||||
[languages.fr.params.header]
|
||||
[languages.fr.params.header.buttons]
|
||||
[languages.fr.params.header.buttons.signIn]
|
||||
text = "Connexion"
|
||||
url = "/fr/signin"
|
||||
[languages.fr.params.header.buttons.getStarted]
|
||||
text = "Commencer"
|
||||
url = "/fr/get-started"
|
||||
|
||||
# Blog configuration
|
||||
[languages.fr.params.blog]
|
||||
enable = true
|
||||
title = "Derniers Articles"
|
||||
subtitle = "Apprenez-en plus sur le développement web et les meilleures pratiques"
|
||||
```
|
||||
|
||||
**Important Notes:**
|
||||
- **Footer Configuration:** The `footer` section is required. Without it, footer column titles may not display correctly in the new language.
|
||||
- **Use uppercase** for footer column titles to maintain consistency with other languages
|
||||
- **URL paths:** Include the language prefix (e.g., `/fr/`) in all button URLs
|
||||
- All parameters should mirror the structure used in other languages (check English or Chinese examples)
|
||||
|
||||
### 6. Complete Checklist
|
||||
|
||||
Use this checklist to ensure you've configured everything correctly:
|
||||
|
||||
- [ ] **Language Config:** Added language configuration in `hugo.toml` with `languageCode`, `languageName`, `title`, `weight`, and `contentDir`
|
||||
- [ ] **Translation File:** Created `i18n/[lang].toml` with all UI translations (50+ keys)
|
||||
- [ ] **Content Directory:** Created `content/[lang]/` directory structure
|
||||
- [ ] **Homepage:** Created `content/[lang]/_index.md` with translated homepage content
|
||||
- [ ] **Navigation Menus:** Configured `languages.[lang].menu.main`, `footer_column_1`, `footer_column_2`, `footer_column_3`
|
||||
- [ ] **Language Params - CTA:** Added `languages.[lang].params.cta` configuration
|
||||
- [ ] **Language Params - Footer:** Added `languages.[lang].params.footer` with all three column titles (UPPERCASE)
|
||||
- [ ] **Language Params - Header:** Added `languages.[lang].params.header.buttons` configuration
|
||||
- [ ] **Language Params - Blog:** Added `languages.[lang].params.blog` configuration
|
||||
- [ ] **URL Prefixes:** All menu URLs include the language prefix (e.g., `/fr/features`)
|
||||
- [ ] **Test:** Verified language switcher appears in header with new language
|
||||
- [ ] **Test:** Verified homepage displays correctly in new language
|
||||
- [ ] **Test:** Verified top navigation menu shows translated items
|
||||
- [ ] **Test:** Verified footer navigation shows translated items
|
||||
- [ ] **Test:** Verified footer column titles display in new language
|
||||
|
||||
### Common Mistakes to Avoid
|
||||
|
||||
1. **Missing Footer Config:** Forgetting to add `languages.[lang].params.footer` will cause footer titles to not display
|
||||
2. **Inconsistent Capitalization:** Footer column titles should be UPPERCASE to match the theme's style
|
||||
3. **Missing URL Prefixes:** All language-specific URLs must include the language code (e.g., `/fr/`, not just `/`)
|
||||
4. **Incomplete Menus:** Ensure all three footer menus (`footer_column_1`, `footer_column_2`, `footer_column_3`) are configured
|
||||
5. **Missing i18n Keys:** Make sure all 50+ translation keys are present in your translation file
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Consistent Structure:** Mirror your content directory structure across all languages
|
||||
2. **Translation Keys:** Use descriptive i18n keys like `readMore` instead of abbreviations
|
||||
3. **Avoid Hardcoding:** Don't set text parameters in global config; let i18n handle it
|
||||
4. **Test Switching:** Verify language switching works correctly on all pages
|
||||
5. **Date Formats:** Define appropriate date formats for each language
|
||||
6. **Menus:** Configure language-specific menus with translated labels
|
||||
7. **URLs:** Include language code in URLs for non-default languages
|
||||
|
||||
## Resources
|
||||
|
||||
- **Hugo i18n Documentation:** https://gohugo.io/content-management/multilingual/
|
||||
- **Theme i18n Files:** `themes/chill-theme/i18n/`
|
||||
- **Demo Site Configuration:** See complete trilingual setup in demo site's `hugo.toml`
|
||||
- **Translation Examples:**
|
||||
- English: `i18n/en.toml` (reference for all keys)
|
||||
- Chinese: `i18n/zh-cn.toml` (complete translation)
|
||||
- German: `i18n/de.toml` (complete translation)
|
||||
- **Content Structure Examples:**
|
||||
- `content/` (English)
|
||||
- `content/zh-cn/` (Chinese)
|
||||
- `content/de/` (German)
|
||||
|
||||
## Support
|
||||
|
||||
For issues or questions about i18n:
|
||||
1. Check [TROUBLESHOOTING.md](TROUBLESHOOTING.md)
|
||||
2. Review the demo site's working multilingual setup
|
||||
3. Open an issue on GitHub with details about your configuration
|
||||
@@ -0,0 +1,785 @@
|
||||
# Layouts Guide
|
||||
|
||||
Complete guide to the Hugo Saasify Theme's layout system, templates, and components.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Layout Architecture](#layout-architecture)
|
||||
- [Base Template](#base-template)
|
||||
- [Default Layouts](#default-layouts)
|
||||
- [Page Templates](#page-templates)
|
||||
- [Partial Components](#partial-components)
|
||||
- [Custom Layouts](#custom-layouts)
|
||||
- [Layout Variables](#layout-variables)
|
||||
- [Best Practices](#best-practices)
|
||||
|
||||
## Layout Architecture
|
||||
|
||||
The Hugo Saasify Theme follows Hugo's template lookup order with specialized layouts for different page types.
|
||||
|
||||
### Directory Structure
|
||||
|
||||
```
|
||||
layouts/
|
||||
├── _default/
|
||||
│ ├── baseof.html # Base template (all pages)
|
||||
│ ├── single.html # Single page layout
|
||||
│ ├── list.html # List page layout
|
||||
│ ├── simple.html # Simple page layout
|
||||
│ ├── pricing.html # Pricing page layout
|
||||
│ ├── company.html # Company/About page layout
|
||||
│ ├── career.html # Careers page layout
|
||||
│ ├── job-single.html # Single job posting layout
|
||||
│ └── feature.html # Feature page layout
|
||||
├── docs/
|
||||
│ └── single.html # Documentation page layout
|
||||
├── partials/
|
||||
│ ├── header.html # Site header
|
||||
│ ├── footer.html # Site footer
|
||||
│ ├── sidebar.html # Blog sidebar
|
||||
│ ├── docs-sidebar.html # Documentation sidebar
|
||||
│ ├── post-card.html # Blog post card
|
||||
│ ├── post-meta.html # Post metadata
|
||||
│ ├── google-analytics.html # GA4 tracking
|
||||
│ ├── google-tag-manager.html # GTM tracking
|
||||
│ └── components/
|
||||
│ ├── cta.html # CTA component
|
||||
│ └── subscribe-form.html # Newsletter form
|
||||
├── taxonomy/
|
||||
│ ├── list.html # Category/tag listing
|
||||
│ └── terms.html # All categories/tags
|
||||
├── shortcodes/
|
||||
│ └── [various shortcodes] # See SHORTCODES.md
|
||||
└── index.html # Homepage template
|
||||
```
|
||||
|
||||
## Base Template
|
||||
|
||||
The `baseof.html` template provides the HTML structure for all pages.
|
||||
|
||||
### Location
|
||||
`layouts/_default/baseof.html`
|
||||
|
||||
### Structure
|
||||
|
||||
```html
|
||||
<!DOCTYPE html>
|
||||
<html lang="{{ .Site.Language.Lang }}">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
<title>{{ block "title" . }}{{ .Title }} | {{ .Site.Title }}{{ end }}</title>
|
||||
|
||||
<!-- Meta tags -->
|
||||
<meta name="description" content="{{ block "description" . }}{{ .Description | default .Site.Params.description }}{{ end }}">
|
||||
|
||||
<!-- Styles -->
|
||||
{{ $styles := resources.Get "scss/main.scss" }}
|
||||
{{ $styles = $styles | postCSS | minify | fingerprint }}
|
||||
<link rel="stylesheet" href="{{ $styles.RelPermalink }}">
|
||||
|
||||
<!-- Analytics -->
|
||||
{{ partial "google-tag-manager.html" . }}
|
||||
{{ partial "google-analytics.html" . }}
|
||||
</head>
|
||||
<body>
|
||||
<!-- GTM noscript -->
|
||||
{{ partial "google-tag-manager.html" . }}
|
||||
|
||||
<!-- Header -->
|
||||
{{ partial "header.html" . }}
|
||||
|
||||
<!-- Main content -->
|
||||
<main>
|
||||
{{ block "main" . }}{{ end }}
|
||||
</main>
|
||||
|
||||
<!-- Footer -->
|
||||
{{ partial "footer.html" . }}
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
### Available Blocks
|
||||
|
||||
1. **title** - Page title (default: `{{ .Title }} | {{ .Site.Title }}`)
|
||||
2. **description** - Meta description
|
||||
3. **main** - Main content area
|
||||
|
||||
### Customizing Base Template
|
||||
|
||||
To override the base template, create:
|
||||
```
|
||||
layouts/baseof.html
|
||||
```
|
||||
|
||||
Or extend it in your custom layouts:
|
||||
```html
|
||||
{{ define "main" }}
|
||||
<!-- Your content -->
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
## Default Layouts
|
||||
|
||||
### Single Page Layout
|
||||
|
||||
**File**: `layouts/_default/single.html`
|
||||
|
||||
Used for individual blog posts and standard pages.
|
||||
|
||||
**Features**:
|
||||
- Full-width content area
|
||||
- Post metadata (date, author, reading time)
|
||||
- Table of contents support
|
||||
- Related posts
|
||||
- CTA section
|
||||
- Social sharing buttons
|
||||
|
||||
**Front Matter Example**:
|
||||
```yaml
|
||||
---
|
||||
title: "My Blog Post"
|
||||
date: 2025-10-06
|
||||
author: "John Doe"
|
||||
description: "Post description"
|
||||
layout: single # Optional, default for posts
|
||||
---
|
||||
```
|
||||
|
||||
**Template Structure**:
|
||||
```html
|
||||
{{ define "main" }}
|
||||
<article class="max-w-4xl mx-auto px-4 py-12">
|
||||
<!-- Post header -->
|
||||
<header class="mb-8">
|
||||
<h1 class="text-4xl font-bold mb-4">{{ .Title }}</h1>
|
||||
{{ partial "post-meta.html" . }}
|
||||
</header>
|
||||
|
||||
<!-- Post content -->
|
||||
<div class="prose prose-lg">
|
||||
{{ .Content }}
|
||||
</div>
|
||||
|
||||
<!-- CTA section -->
|
||||
{{ if .Site.Params.blog.cta.enable }}
|
||||
{{ partial "components/cta.html" . }}
|
||||
{{ end }}
|
||||
</article>
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
### List Page Layout
|
||||
|
||||
**File**: `layouts/_default/list.html`
|
||||
|
||||
Used for blog index, category pages, and section listings.
|
||||
|
||||
**Features**:
|
||||
- Grid layout for posts
|
||||
- Pagination
|
||||
- Filtering by category/tag
|
||||
- Sidebar with widgets
|
||||
- Post previews
|
||||
|
||||
**Template Structure**:
|
||||
```html
|
||||
{{ define "main" }}
|
||||
<div class="container py-12">
|
||||
<div class="grid lg:grid-cols-3 gap-12">
|
||||
<!-- Main content -->
|
||||
<div class="lg:col-span-2">
|
||||
<div class="grid gap-8">
|
||||
{{ range .Paginator.Pages }}
|
||||
{{ partial "post-card.html" . }}
|
||||
{{ end }}
|
||||
</div>
|
||||
|
||||
<!-- Pagination -->
|
||||
{{ template "_internal/pagination.html" . }}
|
||||
</div>
|
||||
|
||||
<!-- Sidebar -->
|
||||
<aside class="lg:col-span-1">
|
||||
{{ partial "sidebar.html" . }}
|
||||
</aside>
|
||||
</div>
|
||||
</div>
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
### Simple Page Layout
|
||||
|
||||
**File**: `layouts/_default/simple.html`
|
||||
|
||||
Used for clean, content-focused pages like privacy policy, terms of service.
|
||||
|
||||
**Features**:
|
||||
- Centered content
|
||||
- No sidebar
|
||||
- Minimal chrome
|
||||
- Full prose styling
|
||||
|
||||
**Front Matter**:
|
||||
```yaml
|
||||
---
|
||||
title: "Privacy Policy"
|
||||
layout: simple
|
||||
---
|
||||
```
|
||||
|
||||
**Use Cases**:
|
||||
- Legal pages
|
||||
- Documentation
|
||||
- Long-form content
|
||||
- Landing pages
|
||||
|
||||
## Page Templates
|
||||
|
||||
### Pricing Page Layout
|
||||
|
||||
**File**: `layouts/_default/pricing.html`
|
||||
|
||||
Specialized layout for pricing pages.
|
||||
|
||||
**Features**:
|
||||
- Pricing table support
|
||||
- Feature comparison
|
||||
- FAQ section
|
||||
- CTA integration
|
||||
- Custom pricing shortcodes
|
||||
|
||||
**Front Matter**:
|
||||
```yaml
|
||||
---
|
||||
title: "Pricing"
|
||||
layout: pricing
|
||||
description: "Choose the perfect plan for your needs"
|
||||
---
|
||||
```
|
||||
|
||||
**Content Example**:
|
||||
```markdown
|
||||
---
|
||||
title: "Pricing"
|
||||
layout: pricing
|
||||
---
|
||||
|
||||
{{< pricing-table-1 >}}
|
||||
{
|
||||
"title": "Choose Your Plan",
|
||||
"description": "Start free, upgrade as you grow",
|
||||
"plans": [...]
|
||||
}
|
||||
{{< /pricing-table-1 >}}
|
||||
|
||||
{{< faq >}}
|
||||
# Frequently Asked Questions
|
||||
...
|
||||
{{< /faq >}}
|
||||
```
|
||||
|
||||
### Company/About Page Layout
|
||||
|
||||
**File**: `layouts/_default/company.html`
|
||||
|
||||
Designed for company and about pages.
|
||||
|
||||
**Features**:
|
||||
- Team member showcase
|
||||
- Company stats
|
||||
- Mission/vision sections
|
||||
- Investor logos
|
||||
- Value propositions
|
||||
|
||||
**Front Matter**:
|
||||
```yaml
|
||||
---
|
||||
title: "About Us"
|
||||
layout: company
|
||||
description: "Learn about our mission and team"
|
||||
---
|
||||
```
|
||||
|
||||
**Typical Structure**:
|
||||
```markdown
|
||||
{{< hero headline="About Our Company" ... >}}
|
||||
|
||||
{{< section-container >}}
|
||||
## Our Mission
|
||||
...
|
||||
{{< /section-container >}}
|
||||
|
||||
{{< stat value="100+" label="Happy Clients" >}}
|
||||
{{< stat value="50+" label="Team Members" >}}
|
||||
|
||||
{{< team-member name="John Doe" ... >}}
|
||||
{{< team-member name="Jane Smith" ... >}}
|
||||
```
|
||||
|
||||
### Career Page Layout
|
||||
|
||||
**File**: `layouts/_default/career.html`
|
||||
|
||||
For careers/jobs listing pages.
|
||||
|
||||
**Features**:
|
||||
- Job listings grid
|
||||
- Department filtering
|
||||
- Location filtering
|
||||
- Application CTA
|
||||
- Company culture section
|
||||
|
||||
**Front Matter**:
|
||||
```yaml
|
||||
---
|
||||
title: "Careers"
|
||||
layout: career
|
||||
description: "Join our team"
|
||||
---
|
||||
```
|
||||
|
||||
### Job Single Layout
|
||||
|
||||
**File**: `layouts/_default/job-single.html`
|
||||
|
||||
Individual job posting pages.
|
||||
|
||||
**Features**:
|
||||
- Job details
|
||||
- Requirements list
|
||||
- Benefits list
|
||||
- Apply button
|
||||
- Share functionality
|
||||
|
||||
**Front Matter**:
|
||||
```yaml
|
||||
---
|
||||
title: "Senior Developer"
|
||||
layout: job-single
|
||||
department: "Engineering"
|
||||
location: "Remote"
|
||||
type: "Full-time"
|
||||
---
|
||||
```
|
||||
|
||||
### Feature Page Layout
|
||||
|
||||
**File**: `layouts/_default/feature.html`
|
||||
|
||||
Showcase individual features or products.
|
||||
|
||||
**Features**:
|
||||
- Hero section
|
||||
- Feature highlights
|
||||
- Screenshots/demos
|
||||
- Use cases
|
||||
- Integration info
|
||||
|
||||
**Front Matter**:
|
||||
```yaml
|
||||
---
|
||||
title: "Performance Features"
|
||||
layout: feature
|
||||
description: "Lightning-fast performance"
|
||||
---
|
||||
```
|
||||
|
||||
## Partial Components
|
||||
|
||||
Reusable components used across layouts.
|
||||
|
||||
### Header Partial
|
||||
|
||||
**File**: `layouts/partials/header.html`
|
||||
|
||||
**Features**:
|
||||
- Responsive navigation
|
||||
- Dropdown menus
|
||||
- Logo
|
||||
- CTA buttons
|
||||
- Mobile menu
|
||||
|
||||
**Variables**:
|
||||
- `Site.Params.header.*` - Header configuration
|
||||
- `Site.Menus.main` - Navigation menu items
|
||||
|
||||
**Customization**:
|
||||
```toml
|
||||
[params.header]
|
||||
background = "bg-white"
|
||||
[params.header.logo]
|
||||
src = "/images/logo.svg"
|
||||
```
|
||||
|
||||
### Footer Partial
|
||||
|
||||
**File**: `layouts/partials/footer.html`
|
||||
|
||||
**Features**:
|
||||
- Multi-column layout
|
||||
- Footer menus
|
||||
- Social media links
|
||||
- Newsletter signup
|
||||
- Copyright notice
|
||||
|
||||
**Variables**:
|
||||
- `Site.Params.footer.*` - Footer configuration
|
||||
- `Site.Params.social.*` - Social media links
|
||||
- `Site.Menus.footer_column_*` - Footer menus
|
||||
|
||||
### Sidebar Partial
|
||||
|
||||
**File**: `layouts/partials/sidebar.html`
|
||||
|
||||
Blog sidebar with widgets.
|
||||
|
||||
**Features**:
|
||||
- Recent posts
|
||||
- Categories
|
||||
- Tags cloud
|
||||
- Newsletter subscription
|
||||
- Search (optional)
|
||||
|
||||
**Configuration**:
|
||||
```toml
|
||||
[params.blog.sidebar]
|
||||
[params.blog.sidebar.recent]
|
||||
enable = true
|
||||
count = 5
|
||||
```
|
||||
|
||||
### Documentation Sidebar
|
||||
|
||||
**File**: `layouts/partials/docs-sidebar.html`
|
||||
|
||||
Navigation for documentation pages.
|
||||
|
||||
**Features**:
|
||||
- Hierarchical navigation
|
||||
- Active page highlighting
|
||||
- Collapsible sections
|
||||
- Search integration
|
||||
|
||||
**Usage**:
|
||||
Automatically included in `layouts/docs/single.html`
|
||||
|
||||
### Post Card Partial
|
||||
|
||||
**File**: `layouts/partials/post-card.html`
|
||||
|
||||
Blog post preview card.
|
||||
|
||||
**Features**:
|
||||
- Featured image
|
||||
- Title and excerpt
|
||||
- Post metadata
|
||||
- Read more link
|
||||
- Category badge
|
||||
|
||||
**Usage**:
|
||||
```html
|
||||
{{ range .Pages }}
|
||||
{{ partial "post-card.html" . }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
### Post Meta Partial
|
||||
|
||||
**File**: `layouts/partials/post-meta.html`
|
||||
|
||||
Display post metadata.
|
||||
|
||||
**Shows**:
|
||||
- Publication date
|
||||
- Author
|
||||
- Reading time
|
||||
- Categories
|
||||
- Tags
|
||||
|
||||
**Usage**:
|
||||
```html
|
||||
{{ partial "post-meta.html" . }}
|
||||
```
|
||||
|
||||
### CTA Component
|
||||
|
||||
**File**: `layouts/partials/components/cta.html`
|
||||
|
||||
Call-to-action section.
|
||||
|
||||
**Features**:
|
||||
- Gradient background
|
||||
- Primary/secondary buttons
|
||||
- Customizable text
|
||||
|
||||
**Configuration**:
|
||||
```toml
|
||||
[params.cta]
|
||||
enable = true
|
||||
title = "Ready to start?"
|
||||
```
|
||||
|
||||
### Subscribe Form Component
|
||||
|
||||
**File**: `layouts/partials/components/subscribe-form.html`
|
||||
|
||||
Newsletter subscription form.
|
||||
|
||||
**Features**:
|
||||
- Email input
|
||||
- Submit button
|
||||
- Privacy notice
|
||||
- Form validation
|
||||
|
||||
**Configuration**:
|
||||
```toml
|
||||
[params.blog.sidebar.subscribe]
|
||||
enable = true
|
||||
action = "https://formspree.io/f/xxx"
|
||||
```
|
||||
|
||||
### Analytics Partials
|
||||
|
||||
**Google Analytics**: `layouts/partials/google-analytics.html`
|
||||
- GA4 tracking code
|
||||
- Automatic page views
|
||||
- Event tracking ready
|
||||
|
||||
**Google Tag Manager**: `layouts/partials/google-tag-manager.html`
|
||||
- GTM container code
|
||||
- Head and body scripts
|
||||
- DataLayer support
|
||||
|
||||
**Custom Head**: `layouts/partials/custom-head.html`
|
||||
- User-overridable partial for custom code
|
||||
- Add any tracking scripts not covered by GA/GTM
|
||||
- Add verification meta tags
|
||||
- Include custom fonts or stylesheets
|
||||
- Loaded at the end of `<head>` section
|
||||
|
||||
To use, create `layouts/partials/custom-head.html` in your site with your custom content.
|
||||
|
||||
## Custom Layouts
|
||||
|
||||
### Creating Custom Layouts
|
||||
|
||||
1. **Single Page Custom Layout**
|
||||
|
||||
Create `layouts/_default/mycustom.html`:
|
||||
```html
|
||||
{{ define "main" }}
|
||||
<div class="custom-layout">
|
||||
<h1>{{ .Title }}</h1>
|
||||
{{ .Content }}
|
||||
</div>
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Use in front matter:
|
||||
```yaml
|
||||
---
|
||||
title: "My Page"
|
||||
layout: mycustom
|
||||
---
|
||||
```
|
||||
|
||||
2. **Section-Specific Layout**
|
||||
|
||||
For pages in `content/products/`, create:
|
||||
`layouts/products/single.html`
|
||||
|
||||
3. **Type-Based Layout**
|
||||
|
||||
Specify type in front matter:
|
||||
```yaml
|
||||
---
|
||||
title: "My Page"
|
||||
type: custom
|
||||
---
|
||||
```
|
||||
|
||||
Create `layouts/custom/single.html`
|
||||
|
||||
### Layout Lookup Order
|
||||
|
||||
Hugo looks for templates in this order:
|
||||
|
||||
For `content/blog/my-post.md`:
|
||||
1. `layouts/blog/single.html`
|
||||
2. `layouts/_default/single.html`
|
||||
|
||||
For `content/blog/_index.md`:
|
||||
1. `layouts/blog/list.html`
|
||||
2. `layouts/_default/list.html`
|
||||
|
||||
## Layout Variables
|
||||
|
||||
### Page Variables
|
||||
|
||||
Available in all layouts:
|
||||
|
||||
```html
|
||||
{{ .Title }} <!-- Page title -->
|
||||
{{ .Content }} <!-- Page content -->
|
||||
{{ .Description }} <!-- Page description -->
|
||||
{{ .Date }} <!-- Publication date -->
|
||||
{{ .Lastmod }} <!-- Last modified date -->
|
||||
{{ .WordCount }} <!-- Word count -->
|
||||
{{ .ReadingTime }} <!-- Reading time in minutes -->
|
||||
{{ .Permalink }} <!-- Absolute URL -->
|
||||
{{ .RelPermalink }} <!-- Relative URL -->
|
||||
{{ .Params.custom }} <!-- Custom front matter -->
|
||||
```
|
||||
|
||||
### Site Variables
|
||||
|
||||
```html
|
||||
{{ .Site.Title }} <!-- Site title -->
|
||||
{{ .Site.Params.description }} <!-- Site description -->
|
||||
{{ .Site.Params.logo }} <!-- Logo path -->
|
||||
{{ .Site.BaseURL }} <!-- Base URL -->
|
||||
{{ .Site.Language.Lang }} <!-- Language code -->
|
||||
{{ .Site.Menus.main }} <!-- Main menu -->
|
||||
{{ .Site.Params.social.twitter }} <!-- Social links -->
|
||||
```
|
||||
|
||||
### Taxonomy Variables
|
||||
|
||||
```html
|
||||
{{ .Data.Terms }} <!-- All terms in taxonomy -->
|
||||
{{ .Data.Singular }} <!-- Singular name -->
|
||||
{{ .Data.Plural }} <!-- Plural name -->
|
||||
```
|
||||
|
||||
### Page Context
|
||||
|
||||
```html
|
||||
{{ .IsHome }} <!-- Is homepage? -->
|
||||
{{ .IsPage }} <!-- Is single page? -->
|
||||
{{ .IsSection }} <!-- Is section? -->
|
||||
{{ .Kind }} <!-- Page kind -->
|
||||
{{ .Type }} <!-- Page type -->
|
||||
{{ .Section }} <!-- Section name -->
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Extend, Don't Replace
|
||||
|
||||
Prefer extending base template:
|
||||
```html
|
||||
{{ define "main" }}
|
||||
<!-- Your content -->
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Over replacing entire baseof.html.
|
||||
|
||||
### 2. Use Partials
|
||||
|
||||
Break complex layouts into partials:
|
||||
```html
|
||||
{{ partial "components/hero.html" . }}
|
||||
{{ partial "components/features.html" . }}
|
||||
{{ partial "components/testimonials.html" . }}
|
||||
```
|
||||
|
||||
### 3. Conditional Content
|
||||
|
||||
Use configuration to control features:
|
||||
```html
|
||||
{{ if .Site.Params.blog.sidebar.recent.enable }}
|
||||
{{ partial "sidebar-recent.html" . }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
### 4. Responsive Design
|
||||
|
||||
Use Tailwind responsive classes:
|
||||
```html
|
||||
<div class="grid md:grid-cols-2 lg:grid-cols-3 gap-8">
|
||||
```
|
||||
|
||||
### 5. Semantic HTML
|
||||
|
||||
Use proper HTML5 elements:
|
||||
```html
|
||||
<article>
|
||||
<header>
|
||||
<h1>{{ .Title }}</h1>
|
||||
<time datetime="{{ .Date }}">{{ .Date.Format "Jan 2, 2006" }}</time>
|
||||
</header>
|
||||
<main>{{ .Content }}</main>
|
||||
</article>
|
||||
```
|
||||
|
||||
### 6. Performance
|
||||
|
||||
Optimize images and assets:
|
||||
```html
|
||||
{{ $image := resources.Get "images/hero.jpg" }}
|
||||
{{ $image = $image.Resize "1200x" }}
|
||||
<img src="{{ $image.RelPermalink }}" loading="lazy">
|
||||
```
|
||||
|
||||
### 7. Accessibility
|
||||
|
||||
Include ARIA attributes:
|
||||
```html
|
||||
<nav aria-label="Main navigation">
|
||||
<!-- Menu items -->
|
||||
</nav>
|
||||
```
|
||||
|
||||
### 8. SEO
|
||||
|
||||
Include proper meta tags:
|
||||
```html
|
||||
<meta name="description" content="{{ .Description }}">
|
||||
<meta property="og:title" content="{{ .Title }}">
|
||||
<meta property="og:description" content="{{ .Description }}">
|
||||
```
|
||||
|
||||
## Testing Layouts
|
||||
|
||||
### Local Testing
|
||||
|
||||
```bash
|
||||
# Test with development server
|
||||
hugo server -D
|
||||
|
||||
# Test specific page
|
||||
hugo server -D --navigateToChanged
|
||||
|
||||
# Test with different baseURL
|
||||
hugo server -D --baseURL http://localhost:1313
|
||||
```
|
||||
|
||||
### Build Testing
|
||||
|
||||
```bash
|
||||
# Build without drafts
|
||||
hugo
|
||||
|
||||
# Build with drafts
|
||||
hugo -D
|
||||
|
||||
# Build with verbose output
|
||||
hugo --verbose
|
||||
```
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [SHORTCODES.md](SHORTCODES.md) - Available shortcodes
|
||||
- [STYLING.md](STYLING.md) - Styling and customization
|
||||
- [CONTENT-CREATION.md](CONTENT-CREATION.md) - Creating content
|
||||
- [CONFIGURATION.md](CONFIGURATION.md) - Configuration options
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [Hugo Template Documentation](https://gohugo.io/templates/)
|
||||
- [Hugo Lookup Order](https://gohugo.io/templates/lookup-order/)
|
||||
- [Hugo Variables](https://gohugo.io/variables/)
|
||||
- [Hugo Functions](https://gohugo.io/functions/)
|
||||
@@ -0,0 +1,313 @@
|
||||
# Hugo Saasify Theme Documentation
|
||||
|
||||
Welcome to the complete documentation for Hugo Saasify Theme - a modern, high-performance Hugo theme built specifically for SaaS websites.
|
||||
|
||||
## 📚 Documentation Overview
|
||||
|
||||
This documentation is organized into focused guides to help you get started quickly and master every aspect of the theme.
|
||||
|
||||
### Getting Started
|
||||
|
||||
Start here if you're new to the theme:
|
||||
|
||||
1. **[Installation Guide](INSTALLATION.md)** - Set up the theme and its dependencies
|
||||
2. **[Configuration Guide](CONFIGURATION.md)** - Configure your site settings
|
||||
3. **[Content Creation Guide](CONTENT-CREATION.md)** - Create pages and blog posts
|
||||
|
||||
### Core Concepts
|
||||
|
||||
Learn about the theme's architecture and features:
|
||||
|
||||
4. **[Layouts Guide](LAYOUTS.md)** - Understanding layout templates and structure
|
||||
5. **[Shortcodes Reference](SHORTCODES.md)** - Complete guide to all 21 shortcodes
|
||||
6. **[Styling Guide](STYLING.md)** - TailwindCSS configuration and customization
|
||||
|
||||
### Deployment & Production
|
||||
|
||||
Ready to go live?
|
||||
|
||||
7. **[Deployment Guide](DEPLOYMENT.md)** - Deploy to Netlify, Vercel, GitHub Pages, and more
|
||||
8. **[Troubleshooting Guide](TROUBLESHOOTING.md)** - Common issues and solutions
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
Get your site running in 5 minutes:
|
||||
|
||||
```bash
|
||||
# 1. Create new Hugo site
|
||||
hugo new site my-saas-site
|
||||
cd my-saas-site
|
||||
|
||||
# 2. Add theme as submodule
|
||||
git init
|
||||
git submodule add https://github.com/chaoming/chill-theme themes/chill-theme
|
||||
|
||||
# 3. Copy example site
|
||||
cp -r themes/chill-theme/exampleSite/* .
|
||||
|
||||
# 4. Install dependencies
|
||||
npm install
|
||||
|
||||
# 5. Start development server
|
||||
npm run start
|
||||
```
|
||||
|
||||
Visit `http://localhost:1313` to see your site!
|
||||
|
||||
## 📖 Documentation Guides
|
||||
|
||||
### [Installation Guide](INSTALLATION.md)
|
||||
|
||||
Learn how to install and set up the Hugo Saasify Theme:
|
||||
|
||||
- System requirements (Hugo Extended, Node.js)
|
||||
- Installation methods (new site vs. existing site)
|
||||
- Configuration setup
|
||||
- Troubleshooting installation issues
|
||||
- Updating the theme
|
||||
|
||||
**Start here if:** You're installing the theme for the first time.
|
||||
|
||||
---
|
||||
|
||||
### [Configuration Guide](CONFIGURATION.md)
|
||||
|
||||
Complete reference for all configuration options:
|
||||
|
||||
- Basic site configuration
|
||||
- Header and footer customization
|
||||
- Call-to-action (CTA) settings
|
||||
- Blog configuration
|
||||
- Social media links
|
||||
- Google Analytics and Tag Manager
|
||||
- Menu configuration
|
||||
- Build settings
|
||||
|
||||
**Start here if:** You need to customize site settings.
|
||||
|
||||
---
|
||||
|
||||
### [Layouts Guide](LAYOUTS.md)
|
||||
|
||||
Understanding the theme's layout system:
|
||||
|
||||
- Layout architecture overview
|
||||
- Base template structure
|
||||
- Default layouts (single, list, etc.)
|
||||
- Page templates (pricing, company, careers, features)
|
||||
- Partial components
|
||||
- Creating custom layouts
|
||||
- Layout variables reference
|
||||
|
||||
**Start here if:** You want to understand or modify page templates.
|
||||
|
||||
---
|
||||
|
||||
### [Shortcodes Reference](SHORTCODES.md)
|
||||
|
||||
Complete documentation for all 21 shortcodes:
|
||||
|
||||
**Hero & Layout:**
|
||||
- `hero` - Hero sections with gradient backgrounds
|
||||
- `hero-image` - Simple hero images
|
||||
- `section-container` - Section wrappers
|
||||
- `features-section` - Feature collection containers
|
||||
|
||||
**Features & Benefits:**
|
||||
- `feature` - Feature displays with images
|
||||
- `features-list` - Vertical feature lists
|
||||
- `benefits-grid` - Benefit card grids
|
||||
- `value-card` - Company value cards
|
||||
|
||||
**Social Proof:**
|
||||
- `testimonials` - Customer testimonial carousels
|
||||
- `client-logos` - Animated logo carousels
|
||||
- `stat` - Statistics display
|
||||
|
||||
**Pricing:**
|
||||
- `pricing-table-1` - Simple pricing tables
|
||||
- `pricing-table-2` - Advanced pricing tables
|
||||
|
||||
**Team & Company:**
|
||||
- `team-member` - Team member cards
|
||||
- `investor-logo` - Investor/partner logos
|
||||
- `case-study-card` - Case study cards
|
||||
|
||||
**Content:**
|
||||
- `cta` - Call-to-action sections
|
||||
- `faq` - FAQ accordions
|
||||
- `toc` - Table of contents
|
||||
- `figure` - Images with captions
|
||||
- `code` - Code blocks with syntax highlighting
|
||||
|
||||
**Start here if:** You're building pages with shortcodes.
|
||||
|
||||
---
|
||||
|
||||
### [Styling Guide](STYLING.md)
|
||||
|
||||
Everything about the theme's styling system:
|
||||
|
||||
- TailwindCSS integration and configuration
|
||||
- Color system (primary and secondary palettes)
|
||||
- Typography (Inter and Plus Jakarta Sans)
|
||||
- Custom components (buttons, cards, etc.)
|
||||
- Responsive design patterns
|
||||
- Syntax highlighting themes
|
||||
- Custom CSS and utilities
|
||||
- Performance optimization
|
||||
|
||||
**Start here if:** You want to customize colors, fonts, or styles.
|
||||
|
||||
---
|
||||
|
||||
### [Content Creation Guide](CONTENT-CREATION.md)
|
||||
|
||||
Learn how to create and organize content:
|
||||
|
||||
- Content structure and organization
|
||||
- Front matter options
|
||||
- Page types (homepage, features, pricing, etc.)
|
||||
- Creating blog posts
|
||||
- Creating documentation pages
|
||||
- Using taxonomies (categories and tags)
|
||||
- Media management and image optimization
|
||||
- SEO best practices
|
||||
- Markdown formatting
|
||||
- Draft and scheduled content
|
||||
|
||||
**Start here if:** You're ready to add content to your site.
|
||||
|
||||
---
|
||||
|
||||
### [Deployment Guide](DEPLOYMENT.md)
|
||||
|
||||
Deploy your site to production:
|
||||
|
||||
- Building for production
|
||||
- Platform-specific guides:
|
||||
- Netlify
|
||||
- Vercel
|
||||
- GitHub Pages
|
||||
- Cloudflare Pages
|
||||
- AWS S3 + CloudFront
|
||||
- Custom server deployment (Nginx, Apache)
|
||||
- Environment variables
|
||||
- Performance optimization
|
||||
- Continuous deployment
|
||||
- Testing before deployment
|
||||
|
||||
**Start here if:** You're ready to launch your site.
|
||||
|
||||
---
|
||||
|
||||
### [Troubleshooting Guide](TROUBLESHOOTING.md)
|
||||
|
||||
Solutions to common problems:
|
||||
|
||||
- Installation issues
|
||||
- Build errors
|
||||
- Styling problems
|
||||
- Content issues
|
||||
- Deployment problems
|
||||
- Performance issues
|
||||
- Browser compatibility
|
||||
- Getting help and reporting issues
|
||||
|
||||
**Start here if:** You're experiencing issues.
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Common Tasks
|
||||
|
||||
### How do I...?
|
||||
|
||||
**...install the theme?**
|
||||
→ See [Installation Guide](INSTALLATION.md)
|
||||
|
||||
**...customize colors?**
|
||||
→ See [Styling Guide - Color System](STYLING.md#color-system)
|
||||
|
||||
**...create a blog post?**
|
||||
→ See [Content Creation - Blog Posts](CONTENT-CREATION.md#blog-posts)
|
||||
|
||||
**...add a pricing page?**
|
||||
→ See [Shortcodes - Pricing Tables](SHORTCODES.md#pricing)
|
||||
|
||||
**...configure the header menu?**
|
||||
→ See [Configuration - Menu Configuration](CONFIGURATION.md#menu-configuration)
|
||||
|
||||
**...deploy to Netlify?**
|
||||
→ See [Deployment - Netlify](DEPLOYMENT.md#netlify)
|
||||
|
||||
**...add team members?**
|
||||
→ See [Shortcodes - Team Member](SHORTCODES.md#team-member)
|
||||
|
||||
**...enable Google Analytics?**
|
||||
→ See [Configuration - Analytics](CONFIGURATION.md#analytics-configuration)
|
||||
|
||||
**...customize fonts?**
|
||||
→ See [Styling - Typography](STYLING.md#typography)
|
||||
|
||||
**...fix build errors?**
|
||||
→ See [Troubleshooting - Build Errors](TROUBLESHOOTING.md#build-errors)
|
||||
|
||||
## 🌟 Key Features
|
||||
|
||||
This theme includes:
|
||||
|
||||
- ✅ **21 Pre-built Shortcodes** - Hero sections, features, pricing tables, testimonials, and more
|
||||
- ✅ **TailwindCSS Integration** - Modern, utility-first CSS framework
|
||||
- ✅ **Responsive Design** - Mobile-first, looks great on all devices
|
||||
- ✅ **Performance Optimized** - Fast builds, minimal JavaScript, optimized assets
|
||||
- ✅ **SEO Ready** - Meta tags, Open Graph, Twitter Cards
|
||||
- ✅ **Blog System** - Categories, tags, sidebar, table of contents
|
||||
- ✅ **Multiple Page Templates** - Pricing, features, company, careers, jobs
|
||||
- ✅ **Analytics Integration** - Google Analytics and Tag Manager support
|
||||
- ✅ **Syntax Highlighting** - Beautiful code blocks with dark theme
|
||||
- ✅ **Easy Customization** - Configurable colors, fonts, and layouts
|
||||
|
||||
## 📋 Requirements
|
||||
|
||||
- **Hugo Extended** v0.80.0 or higher
|
||||
- **Node.js** v14.x or higher
|
||||
- **npm** or **yarn**
|
||||
- **Git** (for submodule installation)
|
||||
|
||||
## 🔗 Useful Links
|
||||
|
||||
- [Demo Site](https://saasify-demo.chaoming.li)
|
||||
- [GitHub Repository](https://github.com/chaoming/chill-theme)
|
||||
- [Report Issues](https://github.com/chaoming/chill-theme/issues)
|
||||
- [Hugo Documentation](https://gohugo.io/documentation/)
|
||||
- [TailwindCSS Documentation](https://tailwindcss.com/docs)
|
||||
|
||||
## 🤝 Support
|
||||
|
||||
Need help?
|
||||
|
||||
1. **Check the Documentation** - Start with the relevant guide above
|
||||
2. **Review Troubleshooting** - See [Troubleshooting Guide](TROUBLESHOOTING.md)
|
||||
3. **Search Issues** - Check [existing issues](https://github.com/chaoming/chill-theme/issues)
|
||||
4. **Ask for Help** - Open a [new issue](https://github.com/chaoming/chill-theme/issues/new) with:
|
||||
- Hugo version (`hugo version`)
|
||||
- Node version (`node --version`)
|
||||
- Error messages
|
||||
- Steps to reproduce
|
||||
- Your configuration
|
||||
|
||||
## 📝 License
|
||||
|
||||
This theme is released under the [MIT License](../LICENSE).
|
||||
|
||||
## 👨💻 Author
|
||||
|
||||
Created by [Chaoming Li](https://chaoming.li)
|
||||
|
||||
## 🎉 Contributing
|
||||
|
||||
Contributions are welcome! Please feel free to submit a Pull Request.
|
||||
|
||||
---
|
||||
|
||||
**Ready to get started?** Begin with the [Installation Guide](INSTALLATION.md) →
|
||||
@@ -0,0 +1,866 @@
|
||||
# Shortcodes Guide
|
||||
|
||||
Complete reference for all shortcodes available in the Hugo Saasify Theme. Shortcodes are reusable content components that help you build beautiful pages quickly.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Hero & Layout](#hero--layout)
|
||||
- [Features & Benefits](#features--benefits)
|
||||
- [Social Proof](#social-proof)
|
||||
- [Pricing](#pricing)
|
||||
- [Team & Company](#team--company)
|
||||
- [Content Components](#content-components)
|
||||
- [Utility Shortcodes](#utility-shortcodes)
|
||||
- [Usage Tips](#usage-tips)
|
||||
|
||||
## Hero & Layout
|
||||
|
||||
### hero
|
||||
|
||||
Create an eye-catching hero section for your pages.
|
||||
|
||||
**Parameters:**
|
||||
- `headline` (string, required) - Main headline text
|
||||
- `sub_headline` (string, required) - Subheading text
|
||||
- `primary_button_text` (string, optional) - Primary CTA button text
|
||||
- `primary_button_url` (string, optional) - Primary button link
|
||||
- `secondary_button_text` (string, optional) - Secondary button text
|
||||
- `secondary_button_url` (string, optional) - Secondary button link
|
||||
- `hero_image` (string, optional) - Path to hero image
|
||||
- `background_image` (string, optional) - Background image path
|
||||
- `gradient-from` (string, optional) - Gradient start color (hex)
|
||||
- `gradient-to` (string, optional) - Gradient end color (hex)
|
||||
- `gradient-angle` (integer, optional) - Gradient angle in degrees (default: 180)
|
||||
|
||||
**Example:**
|
||||
```markdown
|
||||
{{< hero
|
||||
headline="Build Your SaaS <span class='text-primary-600'>Faster</span>"
|
||||
sub_headline="A modern Hugo theme designed for SaaS and technology companies"
|
||||
primary_button_text="Get Started Free"
|
||||
primary_button_url="/signup"
|
||||
secondary_button_text="View Demo"
|
||||
secondary_button_url="/demo"
|
||||
hero_image="/images/hero-dashboard.png"
|
||||
gradient-from="#2563eb"
|
||||
gradient-to="#7c3aed"
|
||||
gradient-angle="30"
|
||||
>}}
|
||||
```
|
||||
|
||||
**With Background Image:**
|
||||
```markdown
|
||||
{{< hero
|
||||
headline="Welcome to Our Platform"
|
||||
sub_headline="Everything you need in one place"
|
||||
background_image="/images/hero-bg.jpg"
|
||||
primary_button_text="Learn More"
|
||||
primary_button_url="/features"
|
||||
>}}
|
||||
```
|
||||
|
||||
### hero-image
|
||||
|
||||
Standalone hero image component.
|
||||
|
||||
**Parameters:**
|
||||
- `src` (string, required) - Image source path
|
||||
- `alt` (string, optional) - Alternative text
|
||||
|
||||
**Example:**
|
||||
```markdown
|
||||
{{< hero-image src="/images/product-screenshot.png" alt="Product Dashboard" >}}
|
||||
```
|
||||
|
||||
### section-container
|
||||
|
||||
Wrapper for creating consistent section spacing and layout.
|
||||
|
||||
**Parameters:**
|
||||
- `background` (string, optional) - Background color or class
|
||||
- `padding` (string, optional) - Custom padding classes
|
||||
|
||||
**Example:**
|
||||
```markdown
|
||||
{{< section-container background="bg-gray-50" >}}
|
||||
## Your Content Here
|
||||
This content will be wrapped in a properly spaced section.
|
||||
{{< /section-container >}}
|
||||
```
|
||||
|
||||
## Features & Benefits
|
||||
|
||||
### feature
|
||||
|
||||
Display a single feature with icon, title, and description.
|
||||
|
||||
**Parameters:**
|
||||
- `icon` (string, required) - Icon name or SVG
|
||||
- `title` (string, required) - Feature title
|
||||
- `description` (string, required) - Feature description
|
||||
- `image` (string, optional) - Feature image path
|
||||
- `image_position` (string, optional) - "left" or "right" (default: "right")
|
||||
|
||||
**Example:**
|
||||
```markdown
|
||||
{{< feature
|
||||
icon="zap"
|
||||
title="Lightning Fast"
|
||||
description="Built with performance in mind. Your site loads in milliseconds."
|
||||
image="/images/feature-performance.png"
|
||||
image_position="right"
|
||||
>}}
|
||||
```
|
||||
|
||||
**With Custom Icon:**
|
||||
```markdown
|
||||
{{< feature
|
||||
title="Secure by Default"
|
||||
description="Enterprise-grade security built into every layer"
|
||||
>}}
|
||||
<svg>...</svg>
|
||||
{{< /feature >}}
|
||||
```
|
||||
|
||||
### features-section
|
||||
|
||||
Wrapper for multiple features with section header.
|
||||
|
||||
**Parameters:**
|
||||
- `title` (string, optional) - Section title
|
||||
- `description` (string, optional) - Section description
|
||||
|
||||
**Example:**
|
||||
```markdown
|
||||
{{< features-section
|
||||
title="Why Choose Our Platform"
|
||||
description="Everything you need to build and grow your business"
|
||||
>}}
|
||||
|
||||
{{< feature icon="rocket" title="Fast Deployment" description="Deploy in minutes" >}}
|
||||
{{< feature icon="shield" title="Secure" description="Bank-level security" >}}
|
||||
{{< feature icon="chart" title="Analytics" description="Deep insights" >}}
|
||||
|
||||
{{< /features-section >}}
|
||||
```
|
||||
|
||||
### features-list
|
||||
|
||||
Display features in a list format.
|
||||
|
||||
**Parameters:**
|
||||
- `title` (string, optional) - List title
|
||||
|
||||
**Example:**
|
||||
```markdown
|
||||
{{< features-list title="Key Features" >}}
|
||||
- Real-time collaboration
|
||||
- Advanced analytics
|
||||
- 99.9% uptime SLA
|
||||
- 24/7 customer support
|
||||
- Enterprise SSO
|
||||
- Custom integrations
|
||||
{{< /features-list >}}
|
||||
```
|
||||
|
||||
### benefits-grid
|
||||
|
||||
Display benefits in a grid layout.
|
||||
|
||||
**Parameters:**
|
||||
- `columns` (integer, optional) - Number of columns (default: 3)
|
||||
|
||||
**Example:**
|
||||
```markdown
|
||||
{{< benefits-grid columns="3" >}}
|
||||
{
|
||||
"items": [
|
||||
{
|
||||
"icon": "clock",
|
||||
"title": "Save Time",
|
||||
"description": "Automate repetitive tasks and focus on what matters"
|
||||
},
|
||||
{
|
||||
"icon": "dollar",
|
||||
"title": "Reduce Costs",
|
||||
"description": "Cut operational expenses by up to 50%"
|
||||
},
|
||||
{
|
||||
"icon": "users",
|
||||
"title": "Scale Easily",
|
||||
"description": "Grow from 10 to 10,000 users effortlessly"
|
||||
}
|
||||
]
|
||||
}
|
||||
{{< /benefits-grid >}}
|
||||
```
|
||||
|
||||
### value-card
|
||||
|
||||
Display a value proposition card.
|
||||
|
||||
**Parameters:**
|
||||
- `icon` (string, required) - Icon name
|
||||
- `title` (string, required) - Card title
|
||||
- `description` (string, required) - Card description
|
||||
|
||||
**Example:**
|
||||
```markdown
|
||||
{{< value-card
|
||||
icon="heart"
|
||||
title="Customer First"
|
||||
description="We put our customers at the center of everything we do"
|
||||
>}}
|
||||
```
|
||||
|
||||
## Social Proof
|
||||
|
||||
### testimonials
|
||||
|
||||
Display customer testimonials in a scrolling carousel.
|
||||
|
||||
**Parameters:**
|
||||
- `title` (string, optional) - Section title
|
||||
- `description` (string, optional) - Section description
|
||||
- `background-color` (string, optional) - Background color
|
||||
- `animate` (boolean, optional) - Enable auto-scroll animation (default: true)
|
||||
|
||||
**Note:** Testimonials data comes from page front matter.
|
||||
|
||||
**Front Matter:**
|
||||
```yaml
|
||||
---
|
||||
title: "Home"
|
||||
testimonials:
|
||||
- name: "Sarah Johnson"
|
||||
title: "CEO, TechCorp"
|
||||
avatar: "/images/avatar-sarah.jpg"
|
||||
quote: "This platform transformed how we work. Highly recommended!"
|
||||
- name: "Michael Chen"
|
||||
title: "CTO, StartupXYZ"
|
||||
avatar: "/images/avatar-michael.jpg"
|
||||
quote: "Amazing product with outstanding support. 5 stars!"
|
||||
- name: "Emma Davis"
|
||||
title: "Product Manager, BigCo"
|
||||
avatar: "/images/avatar-emma.jpg"
|
||||
quote: "Best decision we made this year. Game changer!"
|
||||
---
|
||||
```
|
||||
|
||||
**Example:**
|
||||
```markdown
|
||||
{{< testimonials
|
||||
title="Loved by Teams Worldwide"
|
||||
description="See what our customers have to say"
|
||||
animate="true"
|
||||
>}}
|
||||
```
|
||||
|
||||
### client-logos
|
||||
|
||||
Display client or partner logos.
|
||||
|
||||
**Parameters:**
|
||||
- `title` (string, optional) - Section title
|
||||
- `background` (string, optional) - Background color class
|
||||
|
||||
**Note:** Logos should be passed as inner content in JSON format.
|
||||
|
||||
**Example:**
|
||||
```markdown
|
||||
{{< client-logos title="Trusted by Industry Leaders" >}}
|
||||
{
|
||||
"logos": [
|
||||
{ "src": "/images/clients/company1.svg", "alt": "Company 1" },
|
||||
{ "src": "/images/clients/company2.svg", "alt": "Company 2" },
|
||||
{ "src": "/images/clients/company3.svg", "alt": "Company 3" },
|
||||
{ "src": "/images/clients/company4.svg", "alt": "Company 4" },
|
||||
{ "src": "/images/clients/company5.svg", "alt": "Company 5" }
|
||||
]
|
||||
}
|
||||
{{< /client-logos >}}
|
||||
```
|
||||
|
||||
### case-study-card
|
||||
|
||||
Display a case study preview card.
|
||||
|
||||
**Parameters:**
|
||||
- `title` (string, required) - Case study title
|
||||
- `company` (string, required) - Company name
|
||||
- `industry` (string, required) - Industry
|
||||
- `result` (string, required) - Key result/metric
|
||||
- `image` (string, required) - Card image
|
||||
- `url` (string, required) - Link to full case study
|
||||
|
||||
**Example:**
|
||||
```markdown
|
||||
{{< case-study-card
|
||||
title="How Acme Corp Increased Revenue by 300%"
|
||||
company="Acme Corp"
|
||||
industry="E-commerce"
|
||||
result="300% revenue increase"
|
||||
image="/images/case-studies/acme.jpg"
|
||||
url="/case-studies/acme"
|
||||
>}}
|
||||
```
|
||||
|
||||
## Pricing
|
||||
|
||||
### pricing-table-1
|
||||
|
||||
Three-column pricing table with feature lists.
|
||||
|
||||
**Example:**
|
||||
```markdown
|
||||
{{< pricing-table-1 >}}
|
||||
{
|
||||
"title": "Choose Your Plan",
|
||||
"description": "Start free, upgrade as you grow",
|
||||
"plans": [
|
||||
{
|
||||
"name": "Starter",
|
||||
"description": "Perfect for individuals",
|
||||
"price": "0",
|
||||
"featured": false,
|
||||
"features": [
|
||||
"Up to 10 projects",
|
||||
"Basic analytics",
|
||||
"Email support",
|
||||
"1 GB storage"
|
||||
],
|
||||
"button": {
|
||||
"text": "Start Free",
|
||||
"url": "/signup"
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "Professional",
|
||||
"description": "For growing teams",
|
||||
"price": "29",
|
||||
"featured": true,
|
||||
"features": [
|
||||
"Unlimited projects",
|
||||
"Advanced analytics",
|
||||
"Priority support",
|
||||
"10 GB storage",
|
||||
"Custom integrations"
|
||||
],
|
||||
"button": {
|
||||
"text": "Get Started",
|
||||
"url": "/signup?plan=pro"
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "Enterprise",
|
||||
"description": "For large organizations",
|
||||
"price": "99",
|
||||
"featured": false,
|
||||
"features": [
|
||||
"Everything in Pro",
|
||||
"Dedicated support",
|
||||
"Unlimited storage",
|
||||
"Custom contracts",
|
||||
"SLA guarantee"
|
||||
],
|
||||
"button": {
|
||||
"text": "Contact Sales",
|
||||
"url": "/contact"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
{{< /pricing-table-1 >}}
|
||||
```
|
||||
|
||||
### pricing-table-2
|
||||
|
||||
Alternative pricing table design with comparison features.
|
||||
|
||||
**Example:**
|
||||
```markdown
|
||||
{{< pricing-table-2 >}}
|
||||
{
|
||||
"title": "Flexible Pricing for Every Team",
|
||||
"plans": [
|
||||
{
|
||||
"name": "Basic",
|
||||
"price": "19",
|
||||
"period": "month",
|
||||
"features": [
|
||||
"5 team members",
|
||||
"10 GB storage",
|
||||
"Basic support"
|
||||
],
|
||||
"highlighted": false,
|
||||
"cta": {
|
||||
"text": "Choose Basic",
|
||||
"url": "/signup?plan=basic"
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "Premium",
|
||||
"price": "49",
|
||||
"period": "month",
|
||||
"features": [
|
||||
"Unlimited team members",
|
||||
"100 GB storage",
|
||||
"Priority support",
|
||||
"Advanced features"
|
||||
],
|
||||
"highlighted": true,
|
||||
"cta": {
|
||||
"text": "Choose Premium",
|
||||
"url": "/signup?plan=premium"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
{{< /pricing-table-2 >}}
|
||||
```
|
||||
|
||||
## Team & Company
|
||||
|
||||
### team-member
|
||||
|
||||
Display a team member card.
|
||||
|
||||
**Parameters:**
|
||||
- `name` (string, required) - Team member name
|
||||
- `title` (string, required) - Job title
|
||||
- `image` (string, required) - Profile image path
|
||||
- `bio` (string, optional) - Short biography
|
||||
- `linkedin` (string, optional) - LinkedIn URL
|
||||
- `twitter` (string, optional) - Twitter URL
|
||||
- `github` (string, optional) - GitHub URL
|
||||
|
||||
**Example:**
|
||||
```markdown
|
||||
{{< team-member
|
||||
name="Jane Doe"
|
||||
title="Chief Technology Officer"
|
||||
image="/images/team/jane.jpg"
|
||||
bio="Jane leads our engineering team with 15 years of experience in SaaS"
|
||||
linkedin="https://linkedin.com/in/janedoe"
|
||||
twitter="https://twitter.com/janedoe"
|
||||
>}}
|
||||
```
|
||||
|
||||
### investor-logo
|
||||
|
||||
Display investor or partner logo.
|
||||
|
||||
**Parameters:**
|
||||
- `src` (string, required) - Logo image path
|
||||
- `alt` (string, required) - Alternative text
|
||||
- `url` (string, optional) - Link URL
|
||||
|
||||
**Example:**
|
||||
```markdown
|
||||
{{< investor-logo
|
||||
src="/images/investors/vc-firm.svg"
|
||||
alt="VC Firm"
|
||||
url="https://vcfirm.com"
|
||||
>}}
|
||||
```
|
||||
|
||||
### stat
|
||||
|
||||
Display a statistic or metric.
|
||||
|
||||
**Parameters:**
|
||||
- `value` (string, required) - The number/metric
|
||||
- `label` (string, required) - Description label
|
||||
- `icon` (string, optional) - Icon name
|
||||
|
||||
**Example:**
|
||||
```markdown
|
||||
{{< stat value="10,000+" label="Happy Customers" icon="users" >}}
|
||||
{{< stat value="99.9%" label="Uptime SLA" icon="check" >}}
|
||||
{{< stat value="24/7" label="Support Available" icon="headphones" >}}
|
||||
```
|
||||
|
||||
## Content Components
|
||||
|
||||
### cta
|
||||
|
||||
Call-to-action section.
|
||||
|
||||
**Parameters:**
|
||||
- `title` (string, required) - CTA heading
|
||||
- `description` (string, optional) - CTA description
|
||||
- `button_text` (string, required) - Button text
|
||||
- `button_url` (string, required) - Button link
|
||||
- `background` (string, optional) - Background color/gradient
|
||||
|
||||
**Example:**
|
||||
```markdown
|
||||
{{< cta
|
||||
title="Ready to Get Started?"
|
||||
description="Join thousands of teams already using our platform"
|
||||
button_text="Start Free Trial"
|
||||
button_url="/signup"
|
||||
background="gradient"
|
||||
>}}
|
||||
```
|
||||
|
||||
### faq
|
||||
|
||||
Frequently Asked Questions accordion.
|
||||
|
||||
**Example:**
|
||||
```markdown
|
||||
{{< faq >}}
|
||||
{
|
||||
"title": "Frequently Asked Questions",
|
||||
"description": "Find answers to common questions",
|
||||
"questions": [
|
||||
{
|
||||
"question": "How do I get started?",
|
||||
"answer": "Simply sign up for a free account and follow our onboarding guide. You'll be up and running in minutes."
|
||||
},
|
||||
{
|
||||
"question": "What payment methods do you accept?",
|
||||
"answer": "We accept all major credit cards, PayPal, and wire transfers for enterprise customers."
|
||||
},
|
||||
{
|
||||
"question": "Can I cancel anytime?",
|
||||
"answer": "Yes, you can cancel your subscription at any time. No questions asked, no hidden fees."
|
||||
},
|
||||
{
|
||||
"question": "Do you offer refunds?",
|
||||
"answer": "We offer a 30-day money-back guarantee. If you're not satisfied, contact us for a full refund."
|
||||
}
|
||||
]
|
||||
}
|
||||
{{< /faq >}}
|
||||
```
|
||||
|
||||
### toc
|
||||
|
||||
Generate a table of contents from page headings.
|
||||
|
||||
**Parameters:**
|
||||
- None (automatically generates from page content)
|
||||
|
||||
**Example:**
|
||||
```markdown
|
||||
{{< toc >}}
|
||||
```
|
||||
|
||||
**Custom Title:**
|
||||
```markdown
|
||||
<div class="table-of-contents">
|
||||
<h2>Table of Contents</h2>
|
||||
{{< toc >}}
|
||||
</div>
|
||||
```
|
||||
|
||||
## Utility Shortcodes
|
||||
|
||||
### code
|
||||
|
||||
Enhanced code block with syntax highlighting.
|
||||
|
||||
**Parameters:**
|
||||
- `lang` (string, required) - Programming language
|
||||
- `title` (string, optional) - Code block title
|
||||
- `lineNumbers` (boolean, optional) - Show line numbers (default: true)
|
||||
- `highlight` (string, optional) - Lines to highlight (e.g., "1-3,5")
|
||||
|
||||
**Example:**
|
||||
```markdown
|
||||
{{< code lang="javascript" title="app.js" lineNumbers="true" highlight="2-4" >}}
|
||||
function greet(name) {
|
||||
return `Hello, ${name}!`;
|
||||
}
|
||||
|
||||
console.log(greet('World'));
|
||||
{{< /code >}}
|
||||
```
|
||||
|
||||
**Without Line Numbers:**
|
||||
```markdown
|
||||
{{< code lang="python" lineNumbers="false" >}}
|
||||
def hello_world():
|
||||
print("Hello, World!")
|
||||
{{< /code >}}
|
||||
```
|
||||
|
||||
### figure
|
||||
|
||||
Enhanced image with caption and optional link.
|
||||
|
||||
**Parameters:**
|
||||
- `src` (string, required) - Image source
|
||||
- `alt` (string, required) - Alternative text
|
||||
- `caption` (string, optional) - Image caption
|
||||
- `link` (string, optional) - Link URL
|
||||
- `width` (string, optional) - Image width
|
||||
- `height` (string, optional) - Image height
|
||||
|
||||
**Example:**
|
||||
```markdown
|
||||
{{< figure
|
||||
src="/images/architecture-diagram.png"
|
||||
alt="System Architecture"
|
||||
caption="Our microservices architecture overview"
|
||||
width="800"
|
||||
>}}
|
||||
```
|
||||
|
||||
**With Link:**
|
||||
```markdown
|
||||
{{< figure
|
||||
src="/images/product-thumbnail.jpg"
|
||||
alt="Product Screenshot"
|
||||
caption="Click to see full size"
|
||||
link="/images/product-full.jpg"
|
||||
>}}
|
||||
```
|
||||
|
||||
## Advanced Shortcodes
|
||||
|
||||
### Nested Shortcodes
|
||||
|
||||
You can nest shortcodes for complex layouts:
|
||||
|
||||
```markdown
|
||||
{{< section-container background="bg-white" >}}
|
||||
|
||||
{{< features-section title="Our Platform" >}}
|
||||
|
||||
{{< feature
|
||||
icon="zap"
|
||||
title="Fast"
|
||||
description="Lightning fast performance"
|
||||
>}}
|
||||
|
||||
{{< feature
|
||||
icon="lock"
|
||||
title="Secure"
|
||||
description="Enterprise-grade security"
|
||||
>}}
|
||||
|
||||
{{< /features-section >}}
|
||||
|
||||
{{< /section-container >}}
|
||||
```
|
||||
|
||||
### Combining Shortcodes
|
||||
|
||||
Create rich page layouts:
|
||||
|
||||
```markdown
|
||||
{{< hero headline="Welcome" ... >}}
|
||||
|
||||
{{< client-logos title="Trusted by" >}}
|
||||
...
|
||||
{{< /client-logos >}}
|
||||
|
||||
{{< features-section title="Features" >}}
|
||||
...
|
||||
{{< /features-section >}}
|
||||
|
||||
{{< testimonials >}}
|
||||
|
||||
{{< pricing-table-1 >}}
|
||||
...
|
||||
{{< /pricing-table-1 >}}
|
||||
|
||||
{{< faq >}}
|
||||
...
|
||||
{{< /faq >}}
|
||||
|
||||
{{< cta title="Get Started" ... >}}
|
||||
```
|
||||
|
||||
## Usage Tips
|
||||
|
||||
### 1. JSON Formatting
|
||||
|
||||
For shortcodes that accept JSON (pricing, FAQ, client logos):
|
||||
- Use valid JSON syntax
|
||||
- Ensure proper quotes (double quotes for JSON)
|
||||
- Validate JSON before adding to content
|
||||
- Use online JSON validators if needed
|
||||
|
||||
### 2. Images
|
||||
|
||||
Always use proper image paths:
|
||||
- Absolute paths from site root: `/images/photo.jpg`
|
||||
- Or use Hugo's resource management
|
||||
- Optimize images before uploading
|
||||
- Use appropriate formats (WebP, PNG, JPG)
|
||||
|
||||
### 3. Accessibility
|
||||
|
||||
- Always provide `alt` text for images
|
||||
- Use semantic headings in correct order
|
||||
- Ensure sufficient color contrast
|
||||
- Test keyboard navigation
|
||||
|
||||
### 4. Performance
|
||||
|
||||
- Lazy load images when possible
|
||||
- Minimize the number of shortcodes per page
|
||||
- Optimize JSON data structures
|
||||
- Use appropriate image sizes
|
||||
|
||||
### 5. Responsive Design
|
||||
|
||||
All shortcodes are mobile-responsive by default:
|
||||
- Test on multiple screen sizes
|
||||
- Check touch interactions
|
||||
- Verify text readability
|
||||
- Ensure buttons are tappable
|
||||
|
||||
### 6. Customization
|
||||
|
||||
You can override shortcode templates:
|
||||
1. Copy shortcode from `themes/chill-theme/layouts/shortcodes/`
|
||||
2. Paste to `layouts/shortcodes/` in your site
|
||||
3. Modify as needed
|
||||
|
||||
### 7. Testing
|
||||
|
||||
Before deploying:
|
||||
- Preview with `hugo server -D`
|
||||
- Test all interactive elements
|
||||
- Verify links work
|
||||
- Check on mobile devices
|
||||
- Validate HTML output
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Landing Page
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: "Home"
|
||||
layout: single
|
||||
---
|
||||
|
||||
{{< hero ... >}}
|
||||
{{< client-logos ... >}}
|
||||
{{< features-section ... >}}
|
||||
{{< testimonials >}}
|
||||
{{< cta ... >}}
|
||||
```
|
||||
|
||||
### Pricing Page
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: "Pricing"
|
||||
layout: pricing
|
||||
---
|
||||
|
||||
{{< pricing-table-1 >}}
|
||||
...
|
||||
{{< /pricing-table-1 >}}
|
||||
|
||||
{{< faq >}}
|
||||
...
|
||||
{{< /faq >}}
|
||||
|
||||
{{< cta ... >}}
|
||||
```
|
||||
|
||||
### About Page
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: "About Us"
|
||||
layout: company
|
||||
---
|
||||
|
||||
{{< hero ... >}}
|
||||
|
||||
{{< section-container >}}
|
||||
## Our Story
|
||||
...
|
||||
{{< /section-container >}}
|
||||
|
||||
{{< stat ... >}}
|
||||
{{< stat ... >}}
|
||||
{{< stat ... >}}
|
||||
|
||||
{{< team-member ... >}}
|
||||
{{< team-member ... >}}
|
||||
```
|
||||
|
||||
### Feature Page
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: "Features"
|
||||
layout: feature
|
||||
---
|
||||
|
||||
{{< hero ... >}}
|
||||
|
||||
{{< features-section ... >}}
|
||||
{{< feature ... >}}
|
||||
{{< feature ... >}}
|
||||
{{< /features-section >}}
|
||||
|
||||
{{< case-study-card ... >}}
|
||||
|
||||
{{< cta ... >}}
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Shortcode Not Rendering
|
||||
|
||||
**Problem**: Shortcode appears as text
|
||||
|
||||
**Solutions**:
|
||||
- Check syntax: `{{<` not `{<`
|
||||
- Verify shortcode name spelling
|
||||
- Ensure shortcode file exists
|
||||
- Check Hugo version compatibility
|
||||
|
||||
### JSON Parse Error
|
||||
|
||||
**Problem**: Error parsing JSON in shortcode
|
||||
|
||||
**Solutions**:
|
||||
- Validate JSON syntax
|
||||
- Use double quotes, not single
|
||||
- Escape special characters
|
||||
- Check for trailing commas
|
||||
|
||||
### Images Not Showing
|
||||
|
||||
**Problem**: Images don't display
|
||||
|
||||
**Solutions**:
|
||||
- Verify image path is correct
|
||||
- Check image exists in `static/` folder
|
||||
- Use correct path format (`/images/...`)
|
||||
- Check file permissions
|
||||
|
||||
### Styling Issues
|
||||
|
||||
**Problem**: Shortcode styling doesn't match
|
||||
|
||||
**Solutions**:
|
||||
- Clear Hugo cache: `hugo --gc`
|
||||
- Rebuild site: `hugo`
|
||||
- Check Tailwind compilation
|
||||
- Verify CSS is loading
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [LAYOUTS.md](LAYOUTS.md) - Layout templates
|
||||
- [CONTENT-CREATION.md](CONTENT-CREATION.md) - Creating content
|
||||
- [STYLING.md](STYLING.md) - Customizing styles
|
||||
- [TROUBLESHOOTING.md](TROUBLESHOOTING.md) - Common issues
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [Hugo Shortcodes Documentation](https://gohugo.io/content-management/shortcodes/)
|
||||
- [Creating Custom Shortcodes](https://gohugo.io/templates/shortcode-templates/)
|
||||
- [Theme Shortcode Examples](../exampleSite/content/)
|
||||
@@ -0,0 +1,751 @@
|
||||
# Styling Guide
|
||||
|
||||
Complete guide to styling and customization in the Hugo Saasify Theme. Learn how to customize colors, typography, components, and create your own design system.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Tailwind CSS Integration](#tailwind-css-integration)
|
||||
- [Color System](#color-system)
|
||||
- [Typography](#typography)
|
||||
- [Custom Components](#custom-components)
|
||||
- [Responsive Design](#responsive-design)
|
||||
- [Syntax Highlighting](#syntax-highlighting)
|
||||
- [Customization](#customization)
|
||||
- [Best Practices](#best-practices)
|
||||
|
||||
## Tailwind CSS Integration
|
||||
|
||||
The Hugo Saasify Theme is built with Tailwind CSS v3, providing a utility-first approach to styling.
|
||||
|
||||
### How It Works
|
||||
|
||||
1. **Main CSS File**: `themes/chill-theme/assets/scss/main.scss`
|
||||
2. **Tailwind Config**: `tailwind.config.js` (copied to site root during installation)
|
||||
3. **PostCSS Config**: `postcss.config.js` (copied to site root during installation)
|
||||
4. **Hugo Processing**: Automatic PostCSS compilation
|
||||
5. **Build Stats**: Required for PurgeCSS optimization
|
||||
|
||||
### Configuration File
|
||||
|
||||
**Location**: `tailwind.config.js` (in your site root)
|
||||
|
||||
During installation, you copied this file from `themes/chill-theme/tailwind.config.copy.js` to your site root as `tailwind.config.js`.
|
||||
|
||||
```javascript
|
||||
module.exports = {
|
||||
content: ["./layouts/**/*.html"],
|
||||
theme: {
|
||||
extend: {
|
||||
colors: {
|
||||
primary: { /* custom colors */ },
|
||||
secondary: { /* custom colors */ }
|
||||
},
|
||||
fontFamily: {
|
||||
sans: ['Inter', 'system-ui', 'sans-serif'],
|
||||
heading: ['Plus Jakarta Sans', 'sans-serif']
|
||||
}
|
||||
}
|
||||
},
|
||||
plugins: [
|
||||
require('@tailwindcss/forms'),
|
||||
require('@tailwindcss/typography')
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Tailwind Plugins
|
||||
|
||||
The theme includes two official plugins:
|
||||
|
||||
1. **@tailwindcss/forms** - Beautiful form styling
|
||||
2. **@tailwindcss/typography** - Prose content styling
|
||||
|
||||
## Color System
|
||||
|
||||
The theme uses a comprehensive color palette with primary and secondary colors.
|
||||
|
||||
### Primary Colors
|
||||
|
||||
Blue-based palette for main brand elements.
|
||||
|
||||
```javascript
|
||||
primary: {
|
||||
50: '#eef1fc', // Lightest
|
||||
100: '#dde3f9',
|
||||
200: '#bbc7f3',
|
||||
300: '#99abec',
|
||||
400: '#778fe6',
|
||||
500: '#5573df', // Base
|
||||
600: '#425ad6', // Main (default)
|
||||
700: '#3548ab',
|
||||
800: '#283680',
|
||||
900: '#1b2456' // Darkest
|
||||
}
|
||||
```
|
||||
|
||||
### Secondary Colors
|
||||
|
||||
Purple-based palette for accents and highlights.
|
||||
|
||||
```javascript
|
||||
secondary: {
|
||||
50: '#faf5ff', // Lightest
|
||||
100: '#f3e8ff',
|
||||
200: '#e9d5ff',
|
||||
300: '#d8b4fe',
|
||||
400: '#c084fc',
|
||||
500: '#a855f7', // Base
|
||||
600: '#9333ea', // Main (default)
|
||||
700: '#7e22ce',
|
||||
800: '#6b21a8',
|
||||
900: '#581c87' // Darkest
|
||||
}
|
||||
```
|
||||
|
||||
### Using Colors
|
||||
|
||||
**In Templates**:
|
||||
```html
|
||||
<div class="bg-primary-600 text-white">Primary background</div>
|
||||
<div class="text-secondary-600">Secondary text</div>
|
||||
<button class="bg-primary-600 hover:bg-primary-700">Button</button>
|
||||
```
|
||||
|
||||
**In Custom CSS**:
|
||||
```css
|
||||
.custom-element {
|
||||
@apply bg-primary-50 text-primary-900;
|
||||
}
|
||||
```
|
||||
|
||||
### Customizing Colors
|
||||
|
||||
To change the color scheme, edit `tailwind.config.js`:
|
||||
|
||||
```javascript
|
||||
theme: {
|
||||
extend: {
|
||||
colors: {
|
||||
primary: {
|
||||
50: '#your-color',
|
||||
100: '#your-color',
|
||||
// ... continue for all shades
|
||||
900: '#your-color'
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Quick Method** - Use a color palette generator:
|
||||
1. Choose your base color
|
||||
2. Generate shades using tools like [Tailwind Shades](https://tailwindshades.com/)
|
||||
3. Replace values in `tailwind.config.js`
|
||||
|
||||
### Gray Scale
|
||||
|
||||
Default Tailwind gray scale is available:
|
||||
|
||||
```html
|
||||
<div class="bg-gray-50">Light gray background</div>
|
||||
<div class="bg-gray-100">...</div>
|
||||
<!-- ... -->
|
||||
<div class="bg-gray-900">Dark gray background</div>
|
||||
```
|
||||
|
||||
## Typography
|
||||
|
||||
The theme uses two modern typefaces for optimal readability and visual appeal.
|
||||
|
||||
### Font Families
|
||||
|
||||
**Body Text**: Inter
|
||||
- Variable font for optimal loading
|
||||
- Used for all body text, UI elements
|
||||
- Applied to: paragraphs, lists, forms, buttons
|
||||
|
||||
**Headings**: Plus Jakarta Sans
|
||||
- Bold, modern sans-serif
|
||||
- Used for all headings (h1-h6)
|
||||
- Applied to: titles, section headers
|
||||
|
||||
### Font Configuration
|
||||
|
||||
**Tailwind Config**:
|
||||
```javascript
|
||||
fontFamily: {
|
||||
sans: ['Inter', 'system-ui', 'sans-serif'],
|
||||
heading: ['Plus Jakarta Sans', 'sans-serif']
|
||||
}
|
||||
```
|
||||
|
||||
**CSS Application**:
|
||||
```css
|
||||
body {
|
||||
@apply font-sans text-gray-700;
|
||||
}
|
||||
|
||||
h1, h2, h3, h4, h5, h6 {
|
||||
@apply font-heading font-bold text-gray-900;
|
||||
}
|
||||
```
|
||||
|
||||
### Font Loading
|
||||
|
||||
Fonts are loaded via Google Fonts CDN in the base template:
|
||||
|
||||
```html
|
||||
<link rel="preconnect" href="https://fonts.googleapis.com">
|
||||
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
|
||||
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=Plus+Jakarta+Sans:wght@700;800&display=swap" rel="stylesheet">
|
||||
```
|
||||
|
||||
### Typography Scale
|
||||
|
||||
**Headings**:
|
||||
```html
|
||||
<h1 class="text-4xl md:text-5xl lg:text-6xl">Main Heading</h1>
|
||||
<h2 class="text-3xl md:text-4xl">Section Heading</h2>
|
||||
<h3 class="text-2xl md:text-3xl">Subsection Heading</h3>
|
||||
<h4 class="text-xl md:text-2xl">Small Heading</h4>
|
||||
```
|
||||
|
||||
**Body Text**:
|
||||
```html
|
||||
<p class="text-base">Normal text (16px)</p>
|
||||
<p class="text-lg">Large text (18px)</p>
|
||||
<p class="text-xl">XL text (20px)</p>
|
||||
<p class="text-sm">Small text (14px)</p>
|
||||
```
|
||||
|
||||
### Custom Fonts
|
||||
|
||||
To use different fonts:
|
||||
|
||||
1. **Add Font Files** to `static/fonts/` or use CDN
|
||||
2. **Update Tailwind Config**:
|
||||
```javascript
|
||||
fontFamily: {
|
||||
sans: ['Your Font', 'system-ui', 'sans-serif'],
|
||||
heading: ['Your Heading Font', 'sans-serif']
|
||||
}
|
||||
```
|
||||
3. **Load Font** in baseof.html or CSS
|
||||
|
||||
## Custom Components
|
||||
|
||||
Pre-built component classes for common UI elements.
|
||||
|
||||
### Buttons
|
||||
|
||||
**Primary Button**:
|
||||
```html
|
||||
<a href="#" class="btn-primary">Get Started</a>
|
||||
```
|
||||
|
||||
CSS:
|
||||
```css
|
||||
.btn {
|
||||
@apply inline-flex items-center justify-center px-6 py-3 font-medium transition duration-200 ease-in-out;
|
||||
border-radius: 2rem;
|
||||
}
|
||||
|
||||
.btn-primary {
|
||||
@apply btn bg-primary-600 text-white hover:bg-primary-700 hover:scale-105;
|
||||
}
|
||||
```
|
||||
|
||||
**Secondary Button**:
|
||||
```html
|
||||
<a href="#" class="btn-secondary">Learn More</a>
|
||||
```
|
||||
|
||||
**Outline Button**:
|
||||
```html
|
||||
<a href="#" class="btn-outline">View Demo</a>
|
||||
```
|
||||
|
||||
### Cards
|
||||
|
||||
**Standard Card**:
|
||||
```html
|
||||
<div class="card">
|
||||
<h3>Card Title</h3>
|
||||
<p>Card content goes here</p>
|
||||
</div>
|
||||
```
|
||||
|
||||
CSS:
|
||||
```css
|
||||
.card {
|
||||
@apply bg-white p-6 transition duration-200 hover:shadow-md;
|
||||
border-radius: 2rem;
|
||||
}
|
||||
```
|
||||
|
||||
### Container
|
||||
|
||||
**Responsive Container**:
|
||||
```html
|
||||
<div class="container">
|
||||
<!-- Content automatically centered with responsive padding -->
|
||||
</div>
|
||||
```
|
||||
|
||||
CSS:
|
||||
```css
|
||||
.container {
|
||||
@apply mx-auto px-4 sm:px-6 lg:px-8 max-w-7xl;
|
||||
}
|
||||
```
|
||||
|
||||
### Sections
|
||||
|
||||
**Section Spacing**:
|
||||
```html
|
||||
<section class="section">
|
||||
<!-- Consistent vertical spacing -->
|
||||
</section>
|
||||
```
|
||||
|
||||
CSS:
|
||||
```css
|
||||
.section {
|
||||
@apply py-16 md:py-24;
|
||||
}
|
||||
```
|
||||
|
||||
### Navigation
|
||||
|
||||
**Nav Links**:
|
||||
```html
|
||||
<a href="#" class="nav-link">Features</a>
|
||||
```
|
||||
|
||||
CSS:
|
||||
```css
|
||||
.nav-link {
|
||||
@apply text-gray-600 hover:text-primary-600 font-bold transition duration-200;
|
||||
}
|
||||
```
|
||||
|
||||
### Grids
|
||||
|
||||
**Feature Grid**:
|
||||
```html
|
||||
<div class="feature-grid">
|
||||
<div>Feature 1</div>
|
||||
<div>Feature 2</div>
|
||||
<div>Feature 3</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
CSS:
|
||||
```css
|
||||
.feature-grid {
|
||||
@apply grid gap-8 md:grid-cols-2 lg:grid-cols-3;
|
||||
}
|
||||
```
|
||||
|
||||
## Responsive Design
|
||||
|
||||
The theme is mobile-first and fully responsive.
|
||||
|
||||
### Breakpoints
|
||||
|
||||
Tailwind's default breakpoints:
|
||||
|
||||
```javascript
|
||||
sm: '640px', // Small devices
|
||||
md: '768px', // Medium devices
|
||||
lg: '1024px', // Large devices
|
||||
xl: '1280px', // Extra large devices
|
||||
2xl: '1536px' // 2X large devices
|
||||
```
|
||||
|
||||
### Responsive Utilities
|
||||
|
||||
**Responsive Visibility**:
|
||||
```html
|
||||
<div class="hidden md:block">Visible on medium screens and up</div>
|
||||
<div class="block md:hidden">Visible only on small screens</div>
|
||||
```
|
||||
|
||||
**Responsive Spacing**:
|
||||
```html
|
||||
<div class="py-8 md:py-12 lg:py-16">
|
||||
Responsive padding
|
||||
</div>
|
||||
```
|
||||
|
||||
**Responsive Grid**:
|
||||
```html
|
||||
<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-8">
|
||||
<!-- Responsive columns -->
|
||||
</div>
|
||||
```
|
||||
|
||||
**Responsive Text**:
|
||||
```html
|
||||
<h1 class="text-3xl md:text-4xl lg:text-5xl">
|
||||
Responsive heading
|
||||
</h1>
|
||||
```
|
||||
|
||||
### Mobile Menu
|
||||
|
||||
The header includes a responsive mobile menu that automatically adapts to smaller screens.
|
||||
|
||||
## Syntax Highlighting
|
||||
|
||||
Code blocks are styled with custom syntax highlighting.
|
||||
|
||||
### Configuration
|
||||
|
||||
**Hugo Config** (`hugo.toml`):
|
||||
```toml
|
||||
[markup.highlight]
|
||||
noClasses = false
|
||||
lineNos = true
|
||||
codeFences = true
|
||||
guessSyntax = true
|
||||
lineNumbersInTable = true
|
||||
```
|
||||
|
||||
### Highlight Styles
|
||||
|
||||
**Base Styles**:
|
||||
```css
|
||||
.highlight {
|
||||
@apply text-sm font-mono text-gray-200;
|
||||
}
|
||||
```
|
||||
|
||||
**Syntax Colors**:
|
||||
```css
|
||||
/* Keywords */
|
||||
.highlight .k, .highlight .kd {
|
||||
@apply text-purple-400 font-semibold;
|
||||
}
|
||||
|
||||
/* Functions */
|
||||
.highlight .nf, .highlight .nx {
|
||||
@apply text-blue-400;
|
||||
}
|
||||
|
||||
/* Strings */
|
||||
.highlight .s, .highlight .s1, .highlight .s2 {
|
||||
@apply text-green-400;
|
||||
}
|
||||
|
||||
/* Numbers */
|
||||
.highlight .mi, .highlight .mf {
|
||||
@apply text-orange-400;
|
||||
}
|
||||
|
||||
/* Comments */
|
||||
.highlight .c, .highlight .c1, .highlight .cm {
|
||||
@apply text-gray-500 italic;
|
||||
}
|
||||
|
||||
/* Operators */
|
||||
.highlight .o {
|
||||
@apply text-yellow-400;
|
||||
}
|
||||
|
||||
/* Punctuation */
|
||||
.highlight .p {
|
||||
@apply text-gray-400;
|
||||
}
|
||||
```
|
||||
|
||||
### Line Numbers
|
||||
|
||||
Line numbers are styled with table layout for better copy/paste experience:
|
||||
|
||||
```css
|
||||
.highlight table td:first-child {
|
||||
@apply pr-4 text-right select-none text-gray-500 border-r border-gray-700;
|
||||
}
|
||||
```
|
||||
|
||||
### Customizing Syntax Theme
|
||||
|
||||
To use a different color scheme, modify the `.highlight` classes in `assets/scss/main.scss`.
|
||||
|
||||
## Prose Styling
|
||||
|
||||
Blog posts and content pages use prose styling.
|
||||
|
||||
### Prose Classes
|
||||
|
||||
The theme includes custom prose styling:
|
||||
|
||||
```css
|
||||
.prose {
|
||||
@apply max-w-none;
|
||||
}
|
||||
|
||||
.prose h1 {
|
||||
@apply text-4xl mb-8;
|
||||
}
|
||||
|
||||
.prose h2 {
|
||||
@apply text-3xl mt-12 mb-6;
|
||||
}
|
||||
|
||||
.prose h3 {
|
||||
@apply text-2xl mt-8 mb-4;
|
||||
}
|
||||
|
||||
.prose p {
|
||||
@apply text-gray-700 leading-relaxed mb-6;
|
||||
}
|
||||
|
||||
.prose a {
|
||||
@apply text-primary-600 hover:text-primary-700 no-underline;
|
||||
}
|
||||
|
||||
.prose ul, .prose ol {
|
||||
@apply my-6 ml-6;
|
||||
}
|
||||
|
||||
.prose blockquote {
|
||||
@apply border-l-4 border-gray-200 pl-4 italic text-gray-700 my-8;
|
||||
}
|
||||
|
||||
.prose code:not(pre code) {
|
||||
@apply bg-gray-100 text-gray-900 px-1.5 py-0.5 rounded text-sm font-mono;
|
||||
}
|
||||
```
|
||||
|
||||
### Using Prose
|
||||
|
||||
Wrap content in prose class:
|
||||
|
||||
```html
|
||||
<article class="prose prose-lg">
|
||||
{{ .Content }}
|
||||
</article>
|
||||
```
|
||||
|
||||
## Customization
|
||||
|
||||
### Adding Custom CSS
|
||||
|
||||
1. **Create Custom CSS File**:
|
||||
`static/css/custom.css`
|
||||
|
||||
```css
|
||||
/* Your custom styles */
|
||||
.my-custom-class {
|
||||
background: linear-gradient(to right, #your-colors);
|
||||
}
|
||||
```
|
||||
|
||||
2. **Add to Configuration**:
|
||||
```toml
|
||||
[params]
|
||||
customCSS = ["css/custom.css"]
|
||||
```
|
||||
|
||||
### Extending Tailwind
|
||||
|
||||
**Add to `tailwind.config.js`**:
|
||||
|
||||
```javascript
|
||||
module.exports = {
|
||||
theme: {
|
||||
extend: {
|
||||
// Custom spacing
|
||||
spacing: {
|
||||
'128': '32rem',
|
||||
'144': '36rem'
|
||||
},
|
||||
// Custom colors
|
||||
colors: {
|
||||
'brand': '#your-color'
|
||||
},
|
||||
// Custom border radius
|
||||
borderRadius: {
|
||||
'xl': '1.5rem',
|
||||
'2xl': '2rem'
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Overriding Component Styles
|
||||
|
||||
To override existing components:
|
||||
|
||||
1. **Copy Original** from `themes/.../assets/scss/main.scss`
|
||||
2. **Add to Your CSS** in project root `assets/css/custom.css`
|
||||
3. **Import After Main** in your build process
|
||||
|
||||
Or use `@layer` directive:
|
||||
|
||||
```css
|
||||
@layer components {
|
||||
.btn-primary {
|
||||
@apply bg-red-600 hover:bg-red-700;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Custom Color Scheme
|
||||
|
||||
Complete color scheme override:
|
||||
|
||||
```javascript
|
||||
// tailwind.config.js in your site root
|
||||
module.exports = {
|
||||
theme: {
|
||||
extend: {
|
||||
colors: {
|
||||
primary: {
|
||||
50: '#f0f9ff',
|
||||
100: '#e0f2fe',
|
||||
// ... your colors
|
||||
900: '#0c4a6e'
|
||||
},
|
||||
secondary: {
|
||||
// ... your secondary palette
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Dark Mode Support
|
||||
|
||||
To add dark mode support:
|
||||
|
||||
1. **Enable in Tailwind Config**:
|
||||
```javascript
|
||||
module.exports = {
|
||||
darkMode: 'class', // or 'media'
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
2. **Add Dark Variants**:
|
||||
```html
|
||||
<div class="bg-white dark:bg-gray-900 text-gray-900 dark:text-white">
|
||||
Content
|
||||
</div>
|
||||
```
|
||||
|
||||
3. **Toggle Script** (add to baseof.html):
|
||||
```javascript
|
||||
// Dark mode toggle logic
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Use Tailwind Utilities First
|
||||
|
||||
Prefer Tailwind utilities over custom CSS:
|
||||
|
||||
```html
|
||||
<!-- Good -->
|
||||
<div class="flex items-center justify-between p-4 bg-white rounded-lg shadow">
|
||||
|
||||
<!-- Avoid -->
|
||||
<div class="custom-header" style="...">
|
||||
```
|
||||
|
||||
### 2. Extract Repeated Patterns
|
||||
|
||||
For repeated patterns, create component classes:
|
||||
|
||||
```css
|
||||
@layer components {
|
||||
.product-card {
|
||||
@apply bg-white rounded-2xl p-6 shadow-sm hover:shadow-lg transition;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Maintain Consistency
|
||||
|
||||
Use the theme's design tokens:
|
||||
- Colors from the palette
|
||||
- Spacing from the scale
|
||||
- Typography from defined classes
|
||||
|
||||
### 4. Optimize for Performance
|
||||
|
||||
- Use PurgeCSS (automatic with Hugo)
|
||||
- Minimize custom CSS
|
||||
- Avoid `!important`
|
||||
- Use efficient selectors
|
||||
|
||||
### 5. Accessibility
|
||||
|
||||
- Maintain color contrast ratios (WCAG AA minimum)
|
||||
- Use semantic HTML
|
||||
- Include focus states
|
||||
- Test with keyboard navigation
|
||||
|
||||
### 6. Mobile-First
|
||||
|
||||
Build mobile layouts first:
|
||||
|
||||
```html
|
||||
<!-- Mobile first, then desktop -->
|
||||
<div class="text-sm md:text-base lg:text-lg">
|
||||
```
|
||||
|
||||
### 7. Test Across Browsers
|
||||
|
||||
- Chrome/Edge (Chromium)
|
||||
- Firefox
|
||||
- Safari
|
||||
- Mobile browsers
|
||||
|
||||
## Testing Styles
|
||||
|
||||
### Local Development
|
||||
|
||||
```bash
|
||||
# Watch for changes
|
||||
hugo server -D
|
||||
|
||||
# Clear cache if styles don't update
|
||||
hugo --gc
|
||||
hugo server -D
|
||||
```
|
||||
|
||||
### Build for Production
|
||||
|
||||
```bash
|
||||
# Build with minification
|
||||
hugo --minify
|
||||
|
||||
# Check file sizes
|
||||
ls -lh public/css/
|
||||
```
|
||||
|
||||
### Browser Testing
|
||||
|
||||
1. Chrome DevTools - Responsive mode
|
||||
2. Firefox Developer Tools
|
||||
3. Safari Web Inspector
|
||||
4. Real device testing
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [CONFIGURATION.md](CONFIGURATION.md) - Theme configuration
|
||||
- [LAYOUTS.md](LAYOUTS.md) - Layout templates
|
||||
- [CONTENT-CREATION.md](CONTENT-CREATION.md) - Creating content
|
||||
- [TROUBLESHOOTING.md](TROUBLESHOOTING.md) - Common issues
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [Tailwind CSS Documentation](https://tailwindcss.com/docs)
|
||||
- [Tailwind CSS Typography Plugin](https://tailwindcss.com/docs/typography-plugin)
|
||||
- [Hugo Asset Processing](https://gohugo.io/hugo-pipes/)
|
||||
- [PostCSS Documentation](https://postcss.org/)
|
||||
@@ -0,0 +1,895 @@
|
||||
# Troubleshooting Guide
|
||||
|
||||
Common issues and solutions when working with the Hugo Saasify Theme. Find quick fixes for installation, build, styling, content, deployment, and performance problems.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Installation Issues](#installation-issues)
|
||||
- [Build Errors](#build-errors)
|
||||
- [Styling Problems](#styling-problems)
|
||||
- [Content Issues](#content-issues)
|
||||
- [Deployment Problems](#deployment-problems)
|
||||
- [Performance Issues](#performance-issues)
|
||||
- [Browser Compatibility](#browser-compatibility)
|
||||
- [Getting Help](#getting-help)
|
||||
|
||||
## Installation Issues
|
||||
|
||||
### Theme Not Found
|
||||
|
||||
**Problem**: Hugo can't find the theme
|
||||
|
||||
```
|
||||
Error: unable to locate theme directory "chill-theme"
|
||||
```
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. **Verify theme directory exists**:
|
||||
```bash
|
||||
ls themes/chill-theme
|
||||
```
|
||||
|
||||
2. **Check theme name in config**:
|
||||
```toml
|
||||
# hugo.toml
|
||||
theme = "chill-theme" # Must match directory name exactly
|
||||
```
|
||||
|
||||
3. **If using Git submodule, initialize it**:
|
||||
```bash
|
||||
git submodule init
|
||||
git submodule update --recursive
|
||||
```
|
||||
|
||||
4. **Check directory structure**:
|
||||
```bash
|
||||
# Should show theme files
|
||||
ls -la themes/chill-theme/layouts/
|
||||
```
|
||||
|
||||
### Hugo Extended Not Installed
|
||||
|
||||
**Problem**: Error about Hugo Extended being required
|
||||
|
||||
```
|
||||
Error: this theme requires Hugo Extended
|
||||
```
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. **Check your Hugo version**:
|
||||
```bash
|
||||
hugo version
|
||||
```
|
||||
|
||||
Expected output should include "extended":
|
||||
```
|
||||
hugo v0.120.0+extended darwin/amd64
|
||||
```
|
||||
|
||||
2. **Install Hugo Extended**:
|
||||
- Visit [Hugo Releases](https://github.com/gohugoio/hugo/releases)
|
||||
- Download version with "extended" in the name
|
||||
- Install and verify
|
||||
|
||||
3. **On macOS with Homebrew**:
|
||||
```bash
|
||||
brew install hugo
|
||||
```
|
||||
|
||||
### Submodule Empty
|
||||
|
||||
**Problem**: Theme directory exists but is empty
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. **Update submodules**:
|
||||
```bash
|
||||
git submodule update --init --recursive
|
||||
```
|
||||
|
||||
2. **If still empty, remove and re-add**:
|
||||
```bash
|
||||
git submodule deinit -f themes/chill-theme
|
||||
rm -rf .git/modules/themes/chill-theme
|
||||
git rm -f themes/chill-theme
|
||||
git submodule add https://github.com/chaoming/chill-theme.git themes/chill-theme
|
||||
```
|
||||
|
||||
### npm Dependencies Failed
|
||||
|
||||
**Problem**: npm install fails
|
||||
|
||||
```
|
||||
npm ERR! code ENOENT
|
||||
```
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. **Check Node.js is installed**:
|
||||
```bash
|
||||
node --version
|
||||
npm --version
|
||||
```
|
||||
|
||||
2. **Ensure config files are copied to site root**:
|
||||
```bash
|
||||
cp themes/chill-theme/package.json .
|
||||
cp themes/chill-theme/postcss.config.js .
|
||||
cp themes/chill-theme/tailwind.config.copy.js ./tailwind.config.js
|
||||
```
|
||||
|
||||
3. **Clear npm cache**:
|
||||
```bash
|
||||
npm cache clean --force
|
||||
```
|
||||
|
||||
4. **Delete and reinstall**:
|
||||
```bash
|
||||
rm -rf node_modules package-lock.json
|
||||
npm install
|
||||
```
|
||||
|
||||
5. **Use different npm registry** (if blocked):
|
||||
```bash
|
||||
npm config set registry https://registry.npmjs.org/
|
||||
npm install
|
||||
```
|
||||
|
||||
## Build Errors
|
||||
|
||||
### Tailwind CSS Not Processing
|
||||
|
||||
**Problem**: Site loads without styling
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. **Enable build stats** in `hugo.toml`:
|
||||
```toml
|
||||
[build]
|
||||
writeStats = true
|
||||
|
||||
[build.buildStats]
|
||||
enable = true
|
||||
```
|
||||
|
||||
2. **Clear Hugo cache**:
|
||||
```bash
|
||||
hugo --gc
|
||||
```
|
||||
|
||||
3. **Verify Tailwind config exists**:
|
||||
```bash
|
||||
ls themes/chill-theme/tailwind.config.js
|
||||
```
|
||||
|
||||
4. **Rebuild from clean state**:
|
||||
```bash
|
||||
rm -rf public resources
|
||||
hugo server -D
|
||||
```
|
||||
|
||||
### Template Errors
|
||||
|
||||
**Problem**: Error in template execution
|
||||
|
||||
```
|
||||
Error: error calling partial: template: partials/header.html...
|
||||
```
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. **Check the error message** - it usually points to the specific line
|
||||
2. **Common causes**:
|
||||
- Missing closing tags
|
||||
- Incorrect variable names
|
||||
- Missing required parameters
|
||||
- Syntax errors in shortcodes
|
||||
|
||||
3. **Validate configuration**:
|
||||
```bash
|
||||
hugo config
|
||||
```
|
||||
|
||||
4. **Test with minimal config**:
|
||||
- Copy `exampleSite/hugo.toml`
|
||||
- Gradually add your customizations
|
||||
|
||||
### Shortcode Errors
|
||||
|
||||
**Problem**: Shortcode fails to render
|
||||
|
||||
```
|
||||
Error: failed to render shortcode "pricing-table-1"
|
||||
```
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. **Check JSON syntax** (for shortcodes accepting JSON):
|
||||
- Use double quotes, not single quotes
|
||||
- No trailing commas
|
||||
- Valid JSON structure
|
||||
- Use JSON validator online
|
||||
|
||||
2. **Verify shortcode exists**:
|
||||
```bash
|
||||
ls themes/chill-theme/layouts/shortcodes/pricing-table-1.html
|
||||
```
|
||||
|
||||
3. **Check shortcode syntax**:
|
||||
```markdown
|
||||
# Correct
|
||||
{{< shortcode-name >}}
|
||||
|
||||
# Incorrect
|
||||
{< shortcode-name >} # Missing one brace
|
||||
{{<shortcode-name>}} # Missing spaces
|
||||
```
|
||||
|
||||
### Build Fails in CI/CD
|
||||
|
||||
**Problem**: Builds work locally but fail in CI
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. **Match Hugo versions**:
|
||||
- Check local: `hugo version`
|
||||
- Set in CI config: `HUGO_VERSION=0.120.0`
|
||||
|
||||
2. **Install theme dependencies**:
|
||||
```yaml
|
||||
# GitHub Actions example
|
||||
- name: Install dependencies
|
||||
run: |
|
||||
cp themes/chill-theme/package.json .
|
||||
cp themes/chill-theme/postcss.config.js .
|
||||
cp themes/chill-theme/tailwind.config.copy.js ./tailwind.config.js
|
||||
npm install
|
||||
```
|
||||
|
||||
3. **Check environment variables**:
|
||||
- Verify all required env vars are set
|
||||
- Check for typos in variable names
|
||||
|
||||
4. **Review build logs**:
|
||||
- Look for specific error messages
|
||||
- Check file paths are correct
|
||||
- Verify permissions
|
||||
|
||||
## Styling Problems
|
||||
|
||||
### Custom CSS Not Loading
|
||||
|
||||
**Problem**: Custom CSS changes don't appear
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. **Clear browser cache**:
|
||||
- Hard refresh: Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (Mac)
|
||||
- Or use incognito/private mode
|
||||
|
||||
2. **Verify CSS file path**:
|
||||
```toml
|
||||
[params]
|
||||
customCSS = ["css/custom.css"] # File must be in static/css/
|
||||
```
|
||||
|
||||
3. **Check file exists**:
|
||||
```bash
|
||||
ls static/css/custom.css
|
||||
```
|
||||
|
||||
4. **Clear Hugo cache**:
|
||||
```bash
|
||||
hugo --gc
|
||||
rm -rf resources
|
||||
hugo server -D
|
||||
```
|
||||
|
||||
### Tailwind Classes Not Working
|
||||
|
||||
**Problem**: Tailwind utility classes have no effect
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. **Check class is in content paths**:
|
||||
```javascript
|
||||
// tailwind.config.js
|
||||
content: ["./layouts/**/*.html"]
|
||||
```
|
||||
|
||||
2. **Avoid dynamic class names**:
|
||||
```html
|
||||
<!-- Don't do this -->
|
||||
<div class="text-{{ .Color }}-600">
|
||||
|
||||
<!-- Do this instead -->
|
||||
<div class="{{ if eq .Color "blue" }}text-blue-600{{ end }}">
|
||||
```
|
||||
|
||||
3. **Rebuild site**:
|
||||
```bash
|
||||
hugo --gc
|
||||
hugo
|
||||
```
|
||||
|
||||
4. **Check Tailwind version compatibility**:
|
||||
```bash
|
||||
npm list tailwindcss
|
||||
```
|
||||
|
||||
### Colors Not Matching Design
|
||||
|
||||
**Problem**: Colors appear different than expected
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. **Check color values in `tailwind.config.js`**:
|
||||
```javascript
|
||||
colors: {
|
||||
primary: {
|
||||
600: '#425ad6', // Your primary color
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
2. **Verify you're using correct shade**:
|
||||
```html
|
||||
<div class="bg-primary-600"> <!-- Not bg-primary -->
|
||||
```
|
||||
|
||||
3. **Check for color overrides** in custom CSS
|
||||
|
||||
4. **Test in different browsers** to rule out rendering differences
|
||||
|
||||
### Responsive Design Issues
|
||||
|
||||
**Problem**: Layout broken on mobile/tablet
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. **Test with DevTools**:
|
||||
- Open Chrome DevTools (F12)
|
||||
- Toggle device toolbar (Ctrl+Shift+M)
|
||||
- Test various screen sizes
|
||||
|
||||
2. **Check responsive classes**:
|
||||
```html
|
||||
<!-- Use responsive prefixes -->
|
||||
<div class="text-sm md:text-base lg:text-lg">
|
||||
```
|
||||
|
||||
3. **Verify viewport meta tag** (should be in baseof.html):
|
||||
```html
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
```
|
||||
|
||||
4. **Test breakpoints**:
|
||||
- sm: 640px
|
||||
- md: 768px
|
||||
- lg: 1024px
|
||||
- xl: 1280px
|
||||
|
||||
## Content Issues
|
||||
|
||||
### Page Not Rendering
|
||||
|
||||
**Problem**: Page exists but shows 404
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. **Check front matter**:
|
||||
```yaml
|
||||
---
|
||||
title: "My Page"
|
||||
draft: false # Make sure this is false
|
||||
---
|
||||
```
|
||||
|
||||
2. **Verify file location**:
|
||||
```bash
|
||||
ls content/my-page.md
|
||||
```
|
||||
|
||||
3. **Check URL structure**:
|
||||
- `content/about.md` → `/about/`
|
||||
- `content/blog/post.md` → `/blog/post/`
|
||||
|
||||
4. **Restart server**:
|
||||
```bash
|
||||
hugo server -D # -D shows drafts
|
||||
```
|
||||
|
||||
### Images Not Displaying
|
||||
|
||||
**Problem**: Images don't show on page
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. **Check file path**:
|
||||
```markdown
|
||||
# Correct - absolute from static/
|
||||
|
||||
|
||||
# Incorrect - relative path
|
||||
|
||||
```
|
||||
|
||||
2. **Verify file exists**:
|
||||
```bash
|
||||
ls static/images/photo.jpg
|
||||
```
|
||||
|
||||
3. **Check file permissions**:
|
||||
```bash
|
||||
chmod 644 static/images/photo.jpg
|
||||
```
|
||||
|
||||
4. **Test URL directly**:
|
||||
- Visit `http://localhost:1313/images/photo.jpg`
|
||||
- Should display the image
|
||||
|
||||
5. **Check file extension** matches exactly (case-sensitive on some systems)
|
||||
|
||||
### Shortcode Shows as Text
|
||||
|
||||
**Problem**: Shortcode appears as plain text instead of rendering
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. **Check syntax**:
|
||||
```markdown
|
||||
# Correct
|
||||
{{< shortcode >}}
|
||||
|
||||
# Incorrect
|
||||
{{ < shortcode > }}
|
||||
{< shortcode >}
|
||||
```
|
||||
|
||||
2. **Verify shortcode exists**:
|
||||
```bash
|
||||
ls themes/chill-theme/layouts/shortcodes/
|
||||
```
|
||||
|
||||
3. **Check if content uses correct format**:
|
||||
- Markdown files: Use `{{< >}}`
|
||||
- HTML files: Use `{{ .Inner }}`
|
||||
|
||||
### Taxonomy Pages Empty
|
||||
|
||||
**Problem**: Category or tag pages show no posts
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. **Enable taxonomies** in `hugo.toml`:
|
||||
```toml
|
||||
[taxonomies]
|
||||
category = 'categories'
|
||||
tag = 'tags'
|
||||
```
|
||||
|
||||
2. **Check front matter**:
|
||||
```yaml
|
||||
categories: ["Technology"] # Use array, not string
|
||||
tags: ["Hugo", "Tutorial"]
|
||||
```
|
||||
|
||||
3. **Verify taxonomy matches config**:
|
||||
```toml
|
||||
# If you have:
|
||||
[taxonomies]
|
||||
category = 'categories'
|
||||
|
||||
# Use in front matter:
|
||||
categories: ["Tech"] # Not category:
|
||||
```
|
||||
|
||||
## Deployment Problems
|
||||
|
||||
### Build Fails on Platform
|
||||
|
||||
**Problem**: Build works locally but fails on Netlify/Vercel/etc.
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. **Set Hugo version**:
|
||||
|
||||
Netlify:
|
||||
```toml
|
||||
# netlify.toml
|
||||
[build.environment]
|
||||
HUGO_VERSION = "0.120.0"
|
||||
```
|
||||
|
||||
Vercel:
|
||||
```json
|
||||
// vercel.json
|
||||
{
|
||||
"build": {
|
||||
"env": {
|
||||
"HUGO_VERSION": "0.120.0"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
2. **Install theme dependencies**:
|
||||
|
||||
Add to build command:
|
||||
```bash
|
||||
cp themes/chill-theme/package.json . && cp themes/chill-theme/postcss.config.js . && cp themes/chill-theme/tailwind.config.copy.js ./tailwind.config.js && npm install && hugo --minify
|
||||
```
|
||||
|
||||
3. **Check environment variables** are set in platform UI
|
||||
|
||||
### Assets Not Loading After Deploy
|
||||
|
||||
**Problem**: CSS/JS/images don't load on deployed site
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. **Verify baseURL** in `hugo.toml`:
|
||||
```toml
|
||||
baseURL = "https://yourdomain.com/" # Must match your domain
|
||||
```
|
||||
|
||||
2. **Use absolute paths**:
|
||||
```html
|
||||
<!-- Correct -->
|
||||
<img src="/images/logo.svg">
|
||||
|
||||
<!-- Incorrect -->
|
||||
<img src="images/logo.svg">
|
||||
```
|
||||
|
||||
3. **Check CDN/cache**:
|
||||
- Clear CDN cache
|
||||
- Wait for propagation
|
||||
- Hard refresh browser
|
||||
|
||||
4. **Verify build output**:
|
||||
```bash
|
||||
# Check public/ directory
|
||||
ls -la public/css/
|
||||
ls -la public/images/
|
||||
```
|
||||
|
||||
### SSL Certificate Issues
|
||||
|
||||
**Problem**: HTTPS not working or certificate errors
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. **Wait for provisioning** (can take 24-48 hours)
|
||||
|
||||
2. **Check DNS configuration**:
|
||||
- A record points to correct IP
|
||||
- CNAME points to correct host
|
||||
|
||||
3. **Force HTTPS** in platform settings
|
||||
|
||||
4. **Clear browser SSL cache**
|
||||
|
||||
### 404 on Deployed Site
|
||||
|
||||
**Problem**: Pages work locally but 404 on deployed site
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. **Check baseURL** includes trailing slash:
|
||||
```toml
|
||||
baseURL = "https://example.com/" # Note the /
|
||||
```
|
||||
|
||||
2. **Verify case sensitivity**:
|
||||
- URLs are case-sensitive on most servers
|
||||
- Use lowercase for consistency
|
||||
|
||||
3. **Check redirects** (if you have them):
|
||||
- Verify redirect rules are correct
|
||||
- Check for infinite redirect loops
|
||||
|
||||
## Performance Issues
|
||||
|
||||
### Slow Build Times
|
||||
|
||||
**Problem**: Site takes too long to build
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. **Enable caching**:
|
||||
```toml
|
||||
[caches]
|
||||
[caches.images]
|
||||
dir = ":resourceDir/_gen"
|
||||
maxAge = "1440h"
|
||||
```
|
||||
|
||||
2. **Optimize images** before adding:
|
||||
- Compress images
|
||||
- Reduce dimensions
|
||||
- Use appropriate formats
|
||||
|
||||
3. **Limit content during development**:
|
||||
```bash
|
||||
hugo server -D --buildFuture=false --buildExpired=false
|
||||
```
|
||||
|
||||
4. **Check for template loops**:
|
||||
- Review custom templates
|
||||
- Look for inefficient queries
|
||||
|
||||
### Site Loads Slowly
|
||||
|
||||
**Problem**: Pages take long time to load in browser
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. **Enable minification**:
|
||||
```bash
|
||||
hugo --minify
|
||||
```
|
||||
|
||||
2. **Optimize images**:
|
||||
- Compress all images
|
||||
- Use WebP format
|
||||
- Implement lazy loading
|
||||
|
||||
3. **Use CDN** for static assets
|
||||
|
||||
4. **Enable caching** on server:
|
||||
```nginx
|
||||
# Nginx example
|
||||
location ~* \.(jpg|jpeg|png|gif|ico|css|js)$ {
|
||||
expires 1y;
|
||||
}
|
||||
```
|
||||
|
||||
5. **Run Lighthouse audit**:
|
||||
- Open Chrome DevTools
|
||||
- Go to Lighthouse tab
|
||||
- Run performance audit
|
||||
- Follow recommendations
|
||||
|
||||
### Large CSS File
|
||||
|
||||
**Problem**: Generated CSS is too large
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. **Verify PurgeCSS is working**:
|
||||
```bash
|
||||
# Check file size
|
||||
ls -lh public/css/*.css
|
||||
```
|
||||
|
||||
2. **Ensure build stats enabled**:
|
||||
```toml
|
||||
[build]
|
||||
writeStats = true
|
||||
```
|
||||
|
||||
3. **Check content paths** in `tailwind.config.js`:
|
||||
```javascript
|
||||
content: ["./layouts/**/*.html"]
|
||||
```
|
||||
|
||||
## Browser Compatibility
|
||||
|
||||
### Works in Chrome, Not Safari
|
||||
|
||||
**Problem**: Site works in Chrome but has issues in Safari
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. **Check for unsupported CSS**:
|
||||
- Avoid bleeding-edge features
|
||||
- Test CSS properties on [Can I Use](https://caniuse.com/)
|
||||
|
||||
2. **Add vendor prefixes** if needed:
|
||||
```css
|
||||
-webkit-transition: all 0.3s;
|
||||
transition: all 0.3s;
|
||||
```
|
||||
|
||||
3. **Test in multiple browsers**:
|
||||
- Chrome
|
||||
- Firefox
|
||||
- Safari
|
||||
- Edge
|
||||
|
||||
### JavaScript Errors in IE11
|
||||
|
||||
**Problem**: Site broken in Internet Explorer
|
||||
|
||||
**Note**: IE11 is deprecated. Modern browsers only.
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. **Display upgrade message** for old browsers
|
||||
2. **Focus on modern browsers** (Chrome, Firefox, Safari, Edge)
|
||||
3. **IE11 usage is <1%** globally - consider if support is needed
|
||||
|
||||
## Getting Help
|
||||
|
||||
### Before Asking for Help
|
||||
|
||||
1. **Check this guide** for your issue
|
||||
2. **Review documentation**:
|
||||
- [INSTALLATION.md](INSTALLATION.md)
|
||||
- [CONFIGURATION.md](CONFIGURATION.md)
|
||||
- [LAYOUTS.md](LAYOUTS.md)
|
||||
- [SHORTCODES.md](SHORTCODES.md)
|
||||
3. **Search existing issues** on GitHub
|
||||
4. **Try example site** to isolate problem
|
||||
|
||||
### Gathering Information
|
||||
|
||||
When reporting issues, include:
|
||||
|
||||
1. **Hugo version**:
|
||||
```bash
|
||||
hugo version
|
||||
```
|
||||
|
||||
2. **Operating system**:
|
||||
```bash
|
||||
uname -a # Linux/Mac
|
||||
# or
|
||||
ver # Windows
|
||||
```
|
||||
|
||||
3. **Error messages** (complete output)
|
||||
|
||||
4. **Configuration** (relevant parts of `hugo.toml`)
|
||||
|
||||
5. **Steps to reproduce**:
|
||||
- What you did
|
||||
- What you expected
|
||||
- What actually happened
|
||||
|
||||
6. **Minimal reproduction**:
|
||||
- Simplest case that shows the problem
|
||||
- Remove unrelated code/config
|
||||
|
||||
### Where to Get Help
|
||||
|
||||
1. **Documentation**: Check all docs in `/docs` directory
|
||||
|
||||
2. **Example Site**: Review working examples in `/exampleSite`
|
||||
|
||||
3. **GitHub Issues**:
|
||||
- Search: [Existing Issues](https://github.com/chaoming/chill-theme/issues)
|
||||
- Create: [New Issue](https://github.com/chaoming/chill-theme/issues/new)
|
||||
|
||||
4. **Hugo Community**:
|
||||
- [Hugo Discourse](https://discourse.gohugo.io/)
|
||||
- [Hugo Documentation](https://gohugo.io/documentation/)
|
||||
|
||||
5. **Stack Overflow**:
|
||||
- Tag: `hugo`, `hugo-theme`
|
||||
|
||||
### Creating a Good Issue Report
|
||||
|
||||
**Template**:
|
||||
|
||||
```markdown
|
||||
## Description
|
||||
Brief description of the problem
|
||||
|
||||
## Environment
|
||||
- Hugo version: 0.120.0+extended
|
||||
- OS: macOS 14.0
|
||||
- Theme version: main branch
|
||||
|
||||
## Steps to Reproduce
|
||||
1. Step one
|
||||
2. Step two
|
||||
3. Step three
|
||||
|
||||
## Expected Behavior
|
||||
What should happen
|
||||
|
||||
## Actual Behavior
|
||||
What actually happens
|
||||
|
||||
## Error Messages
|
||||
```
|
||||
Paste error messages here
|
||||
```
|
||||
|
||||
## Configuration
|
||||
```toml
|
||||
Relevant parts of hugo.toml
|
||||
```
|
||||
|
||||
## Additional Context
|
||||
Any other relevant information
|
||||
```
|
||||
|
||||
## Common Error Messages
|
||||
|
||||
### "Page Not Found"
|
||||
|
||||
**Cause**: Content file doesn't exist or is draft
|
||||
|
||||
**Fix**:
|
||||
- Check file exists
|
||||
- Verify `draft: false`
|
||||
- Restart server
|
||||
|
||||
### "Template Not Found"
|
||||
|
||||
**Cause**: Missing or misnamed template file
|
||||
|
||||
**Fix**:
|
||||
- Check template file exists
|
||||
- Verify layout name in front matter
|
||||
- Check template lookup order
|
||||
|
||||
### "Failed to Process"
|
||||
|
||||
**Cause**: CSS/Asset processing error
|
||||
|
||||
**Fix**:
|
||||
- Check PostCSS configuration
|
||||
- Verify Hugo Extended installed
|
||||
- Review asset file syntax
|
||||
|
||||
### "Submodule Not Found"
|
||||
|
||||
**Cause**: Git submodule not initialized
|
||||
|
||||
**Fix**:
|
||||
```bash
|
||||
git submodule update --init --recursive
|
||||
```
|
||||
|
||||
## Quick Fixes Checklist
|
||||
|
||||
When something isn't working:
|
||||
|
||||
- [ ] Restart Hugo server
|
||||
- [ ] Clear browser cache (Ctrl+Shift+R)
|
||||
- [ ] Clear Hugo cache (`hugo --gc`)
|
||||
- [ ] Delete `public/` and `resources/` directories
|
||||
- [ ] Verify Hugo version (`hugo version`)
|
||||
- [ ] Check `hugo.toml` syntax
|
||||
- [ ] Review error messages carefully
|
||||
- [ ] Test with example site configuration
|
||||
- [ ] Check file permissions
|
||||
- [ ] Verify file paths are correct
|
||||
|
||||
## Prevention Best Practices
|
||||
|
||||
Avoid issues before they happen:
|
||||
|
||||
1. **Use Version Control**: Commit working states
|
||||
2. **Test Locally**: Before deploying
|
||||
3. **Keep Updated**: Update Hugo and dependencies
|
||||
4. **Follow Documentation**: Don't guess
|
||||
5. **Start Simple**: Add complexity gradually
|
||||
6. **Backup Configuration**: Save working configs
|
||||
7. **Use Example Site**: Reference working examples
|
||||
8. **Read Error Messages**: They usually tell you what's wrong
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [INSTALLATION.md](INSTALLATION.md) - Installation guide
|
||||
- [CONFIGURATION.md](CONFIGURATION.md) - Configuration options
|
||||
- [DEPLOYMENT.md](DEPLOYMENT.md) - Deployment guides
|
||||
- [Hugo Troubleshooting](https://gohugo.io/troubleshooting/)
|
||||
|
||||
## Still Stuck?
|
||||
|
||||
If you've tried everything and still have issues:
|
||||
|
||||
1. **Create minimal reproduction** - Simplest case showing problem
|
||||
2. **Open GitHub issue** with all relevant information
|
||||
3. **Be patient** - Maintainers are volunteers
|
||||
4. **Be detailed** - More info = faster resolution
|
||||
5. **Follow up** - Respond to questions
|
||||
|
||||
Remember: Most issues have been encountered before. Search first, then ask.
|
||||
@@ -0,0 +1,155 @@
|
||||
# Simplified Chinese translations for Hugo Saasify Theme (Example)
|
||||
# Copy this file to your site's i18n directory as zh-cn.toml and customize as needed
|
||||
# 简体中文翻译示例文件
|
||||
|
||||
# 常用UI翻译
|
||||
[readMore]
|
||||
other = "阅读更多"
|
||||
|
||||
[readTime]
|
||||
other = "分钟阅读"
|
||||
|
||||
[published]
|
||||
other = "发布于"
|
||||
|
||||
[updated]
|
||||
other = "更新于"
|
||||
|
||||
[by]
|
||||
other = "作者"
|
||||
|
||||
[shareOn]
|
||||
other = "分享到"
|
||||
|
||||
[relatedPosts]
|
||||
other = "相关文章"
|
||||
|
||||
[categories]
|
||||
other = "分类"
|
||||
|
||||
[tags]
|
||||
other = "标签"
|
||||
|
||||
[allPosts]
|
||||
other = "所有文章"
|
||||
|
||||
[search]
|
||||
other = "搜索"
|
||||
|
||||
[searchPlaceholder]
|
||||
other = "搜索文章..."
|
||||
|
||||
[noResults]
|
||||
other = "未找到结果"
|
||||
|
||||
[backToHome]
|
||||
other = "返回首页"
|
||||
|
||||
[404Title]
|
||||
other = "页面未找到"
|
||||
|
||||
[404Message]
|
||||
other = "您查找的页面不存在或已被移动。"
|
||||
|
||||
# 导航
|
||||
[home]
|
||||
other = "首页"
|
||||
|
||||
[about]
|
||||
other = "关于"
|
||||
|
||||
[contact]
|
||||
other = "联系我们"
|
||||
|
||||
# 博客
|
||||
[latestPosts]
|
||||
other = "最新文章"
|
||||
|
||||
[recentArticles]
|
||||
other = "最近文章"
|
||||
|
||||
[popularTags]
|
||||
other = "热门标签"
|
||||
|
||||
[subscribeNewsletter]
|
||||
other = "订阅新闻通讯"
|
||||
|
||||
[subscribeDescription]
|
||||
other = "将最新文章直接发送到您的收件箱"
|
||||
|
||||
[emailPlaceholder]
|
||||
other = "输入您的邮箱"
|
||||
|
||||
[subscribe]
|
||||
other = "订阅"
|
||||
|
||||
[subscribeDisclaimer]
|
||||
other = "我们尊重您的隐私。您可以随时取消订阅。"
|
||||
|
||||
# 页脚
|
||||
[copyright]
|
||||
other = "© {{ .Year }} {{ .SiteName }}。保留所有权利。"
|
||||
|
||||
[builtWith]
|
||||
other = "使用"
|
||||
|
||||
[and]
|
||||
other = "和"
|
||||
|
||||
# 语言切换
|
||||
[language]
|
||||
other = "语言"
|
||||
|
||||
[switchLanguage]
|
||||
other = "切换语言"
|
||||
|
||||
# 功能特性
|
||||
[seeItInAction]
|
||||
other = "实际演示"
|
||||
|
||||
# 定价
|
||||
[popular]
|
||||
other = "热门"
|
||||
|
||||
[mostPopular]
|
||||
other = "最受欢迎"
|
||||
|
||||
[perMonth]
|
||||
other = "/月"
|
||||
|
||||
# 文档
|
||||
[documentation]
|
||||
other = "文档"
|
||||
|
||||
# 分页
|
||||
[previous]
|
||||
other = "上一页"
|
||||
|
||||
[next]
|
||||
other = "下一页"
|
||||
|
||||
# 首页
|
||||
[trustedByCompanies]
|
||||
other = "受全球领先企业信任"
|
||||
|
||||
[lovedByTeams]
|
||||
other = "受全球团队喜爱"
|
||||
|
||||
[testimonialsDescription]
|
||||
other = "看看我们的客户对使用我们平台的体验有何评价。"
|
||||
|
||||
# 博客文章
|
||||
[tableOfContents]
|
||||
other = "目录"
|
||||
|
||||
[minRead]
|
||||
other = "分钟阅读"
|
||||
|
||||
[previousPost]
|
||||
other = "上一篇"
|
||||
|
||||
[nextPost]
|
||||
other = "下一篇"
|
||||
|
||||
[dateFormat]
|
||||
other = "2006年1月2日"
|
||||
Reference in New Issue
Block a user