Hugo MCP

🚀 Hugo Site Configuration Process Documentation

This documentation provides a detailed guide on configuring a Hugo site, covering installation checks, site creation, theme management, content creation, deployment, and troubleshooting.

🚀 Quick Start

Prerequisites

Before you start, make sure you have the necessary tools installed. You can use the following commands to check and install them if needed.

✨ Features

• Installation Check: Automatically checks and installs Hugo and Git if they are not already installed.
• Site Creation: Allows you to create a new Hugo site with a specified theme.
• Theme Management: Lists available themes and provides details about specific themes.
• Content Creation: Enables you to create new posts and build the site for production.
• Deployment: Supports deploying the site to various platforms, including GitHub Pages, Netlify, Vercel, and custom Git repositories.
• Troubleshooting: Provides solutions to common issues and a way to get help for other problems.

📦 Installation

Check Hugo Installation Status

hugo-mcp check-hugo

Example Output:

{
  "status": "success",
  "version": "0.98.6"
}

If Hugo is not installed, the system will automatically download and install the latest version.

Check Git Installation Status

hugo-mcp check-git

Example Output:

{
  "status": "success",
  "version": "2.34.1"
}

If Git is not installed, the system will automatically download and install the latest version.

💻 Usage Examples

Site Creation and Configuration

Create a New Site

hugo-mcp create-site [site-name] --theme=[theme-url] [--use-example-site]

Example:

hugo-mcp create-site my-blog --theme=https://github.com/nanxiaobei/hugo-paper --use-example-site

Configure Git Information

hugo-mcp config-git [name] [email]

Example:

hugo-mcp config-git "John Doe" john.doe@example.com

Theme Management

List Available Themes

hugo-mcp list-themes

Example Output:

{
  "themes": [
    {
      "name": "Paper",
      "url": "https://github.com/nanxiaobei/hugo-paper"
    },
    {
      "name": "Default",
      "url": "https://github.com/gohugoio/hugo-default-theme"
    }
  ]
}

Get Theme Details

hugo-mcp get-theme-details [theme-name]

Example:

hugo-mcp get-theme-details Paper

Site Management Operations

Start the Preview Server

hugo-mcp start-preview [site-path] [--port=8080]

Example:

hugo-mcp start-preview /path/to/my/blog --port 9000

Content Creation Tools

Create a New Post

hugo-mcp create-post [site-path] [post-title] [--draft]

Example:

hugo-mcp create-post /path/to/my/blog my-first-post --draft

Build for Production

hugo-mcp build-site [site-path] [--minify]

Deployment and Publishing

Deploy the Site to a Specified Platform

hugo-mcp deploy-site [site-path] --platform=[platform] [--branch=main] [--commit-message="Update site"] [--api-key=your-token] [--remote-url=https://example.com]

Supported Platforms:

• GitHub Pages
• Netlify
• Vercel
• Custom Git Repository

Example:

hugo-mcp deploy-site /path/to/my/blog --platform github-pages --branch gh-pages --commit-message "Deploy site" --api-key your-github-token

🔧 Technical Details

The hugo-mcp tool simplifies the process of setting up and managing a Hugo site. It uses shell commands to interact with Hugo and Git, and provides a user-friendly interface for common tasks.

📚 Documentation

For more detailed information, please refer to the GitHub repository.

📄 License

This project is licensed under the MIT License.

🛠️ Troubleshooting

Common Issues

1. Hugo Not Installed: Use the hugo-mcp install-hugo tool to install it.

2. Git Not Installed: Use the hugo-mcp install-git tool to install it.

3. Theme Installation Failed:

   • Check if the theme URL is correct.
   • Ensure that Git and Go are installed correctly to handle submodules and dependencies.

4. Preview Server Failed to Start:

   • Check if the port is already in use.
   • Make sure the site path is correct.

5. Build Failed:

   • Confirm that the site path is correct.
   • Ensure that all dependencies are installed.

Get Help

If you encounter an issue not listed here, please visit the GitHub repository to submit a problem.