Creating Your First Hugo Website: A Step-by-Step Guide

Creating Your First Hugo Website: A Step-by-Step Guide 创建你的第一个 Hugo 网站：分步指南

Prerequisites | 前提条件

• Hugo installed on your computer | 电脑上已安装 Hugo
• A terminal/command line interface | 终端/命令行界面
• A text editor of your choice | 你选择的文本编辑器

Step 1: Create a Project Directory | 步骤1：创建项目目录

1. Create a folder where you want to store your Hugo projects | 创建一个用于存储 Hugo 项目的文件夹
2. Open your terminal | 打开终端
3. Navigate to your project directory using the cd command | 使用 cd 命令导航到项目目录

Step 2: Create a New Hugo Site | 步骤2：创建新的 Hugo 网站

Run the following command in your terminal: | 在终端中运行以下命令：

hugo new site your_site_name

Replace your_site_name with whatever you want to call your project. | 将 your_site_name 替换为你想要的项目名称。

Step 3: Understanding the Project Structure | 步骤3：了解项目结构

📁 archetypes/

• Contains templates for your content | 包含内容的模板
• Used for defining common metadata across similar content types | 用于定义相似内容类型的通用元数据
• Mainly used for advanced configurations | 主要用于高级配置

📁 content/

• Stores all your website content | 存储所有网站内容
• Place your pages, blog posts, and other content here | 在此放置你的页面、博客文章和其他内容
• Main directory where you’ll spend most of your time writing | 你将花费最多时间写作的主要目录

📁 data/

• Acts as a simple database for your site | 作为网站的简单数据库
• Store JSON, YAML, or TOML files | 存储 JSON、YAML 或 TOML 文件
• Used for site-wide data that can be accessed by your templates | 用于可被模板访问的全站数据

📁 layouts/

• Contains your site’s templates | 包含网站的模板
• Define how your content will be displayed | 定义内容如何显示
• Examples: headers, footers, page layouts | 示例：页眉、页脚、页面布局
• Create consistent looks across your site | 创建全站统一的外观

📁 static/

• Stores unchanging files | 存储不变的文件
• Contains: | 包含：
  • Images | 图片
  • CSS files | CSS 文件
  • JavaScript files | JavaScript 文件
  • Downloads | 下载文件
  • Other static assets | 其他静态资源

📁 themes/

• Houses downloaded themes | 存放下载的主题
• Allows you to use pre-built designs | 允许使用预构建的设计
• Great for beginners who don’t want to create layouts from scratch | 适合不想从头开始创建布局的初学者

📄 config.toml

• Main configuration file | 主配置文件
• Contains your site’s settings | 包含网站的设置
• Define things like: | 定义诸如：
  • Site title | 网站标题
  • Base URL | 基础 URL
  • Language | 语言
  • Other global settings | 其他全局设置

Step 4: Initial Configuration | 步骤4：初始配置

1. Open config.toml in your text editor | 在文本编辑器中打开 config.toml
2. Set basic configurations: | 设置基本配置：

title = "Your Site Title"
baseURL = "http://example.org/"
languageCode = "en-us"

Next Steps | 后续步骤

1. Choose and install a theme | 选择并安装主题
2. Create your first content | 创建你的第一个内容
3. Customize your layouts | 自定义布局
4. Add static assets | 添加静态资源

Tips for Beginners | 给初学者的提示

• Start with the content/ folder for adding pages | 从 content/ 文件夹开始添加页面
• Use a pre-built theme initially | 初期使用预构建的主题
• Don’t worry about complex layouts at first | 开始时不要担心复杂的布局
• Keep your static assets organized in the static/ folder | 在 static/ 文件夹中组织静态资源
• Make regular backups of your config.toml | 定期备份 config.toml

Common Gotchas | 常见陷阱

• Always run Hugo commands from your project root directory | 始终从项目根目录运行 Hugo 命令
• Keep file names lowercase and use hyphens instead of spaces | 保持文件名小写并使用连字符而不是空格
• Remember to rebuild your site after making changes | 记得在做出更改后重新构建网站
• Check your baseURL setting if links aren’t working | 如果链接不工作，检查 baseURL 设置