Hugo Profile Docs Contribution

Xintong Wang | May 6, 2025 -min read
Hugo Profile Docs Contribution
About

  • Summary: Contributed improvements to the README.md of an open-source Hugo theme (hugo-profile) to enhance clarity, structure, and usability for first-time users (Pull Request: #233).

  • Intended Audience: Beginners building personal websites with Hugo.

  • Written Context: GitHub pull request contribution to the upstream project.

Contributions

  • Rewrote, reformat, and reorganize sections to improve the overall structure and clarity of the README.md file.

  • Added step-by-step instructions in Quick Start section to make it more beginner-friendly.

  • Fixed a broken shortcode example (x) by replacing it with the correct tweet shortcode.

See the pull request on GitHub for details.

README Comparison

The original README had a flat structure with minimal sectioning. In the improved version, the content is logically organized, with clearly separated sections for setup, content management, and deployment. This makes it easier for beginners to follow.

AspectBeforeAfter (Improved)

Requirements

Brief mention of Hugo version only

Expanded with version check command and install link

Getting Started

Basic setup steps without much explanation or trouble-shootings

Step-by-step Quick Start section from site creation to local preview

Content Management

Only a few reference links

New section on editing site content

Deployment

Basic Netlify usage

Clear options for Netlify (template vs manual setup) and static hosting

Tone

Technical and brief, assumes prior knowledge

Beginner-focused, with explanatory details

See below for screenshots of the original and improved README. The updated version is broken into clearer sections for better usability:

Before

Before

After

Requirement
Quick Start
Content Management
Deployment

Shortcode Fix

Fixed a non-functional shortcode in the example content to avoid build errors, and documented known issues of the new solution.

hugo profile readme shortcode