Creating a new Blog Document

The manh Hugo theme includes sample archetypes that can get you started with a new Markdown file based on the Kind of document. The starting document includes starting YAML metadata (Front Matter) which influences the way the document is displayed. The steps to create a new document are as follows

1. Pull the latest from this Repo

Many developers may be contributing to this Repo and theme changes may have occured since you last worked in the Repo, so make it a habit to pull frequently.

git checkout main
git pull --recurse-submodules

2. Create a branch for your new document

Create a new branch for your changes which can later be reviewed / approved through a pull request.

Please follow a standard branch naming convention

• use all lowercase letters
• use - for spaces
• provide a short name of the document being created

git checkout -b new-blog-entry-2022-05-02

3. Run the Hugo Command to generate your new Document in the appropriate location

A series of sub folders below the top level section provide additional organization. Each document is created as a markdown file within its own folder along with an images folder.

# Example for creating a new Blog in the "article" sub section
hugo new blog/article/2022-05-02-example

# Example for creating a new Blog in the "article" sub section
hugo new blog/article/2022-05-02-example

4. Update Front Matter

Update the YAML section at the top of the index.md file created for your document. Important items to update include -

• title and linkTitle
• description

Comments should help explain the variables and their use, feel free to remove / update comments in this section as part of your documentation.

5. Add Content

Finally! Create the documentation that you want to share with your colleagues and the development community. The starting document has some examples of Markdown to help. Using your favorite code editor, you can keep an eye on how the markdown is going to look.

VS Code Users : Here is a handy extension - doc markdown

6. Review your Content Locally

Once you have a good working draft, you can review how it will appear in the site by running Hugo on your local machine.

# Returns the local server hosting pages
# by default, this is likely //localhost:1313/
hugo server

NOTE: You can live edit your documentation, so snap your browser and editor side by side and live edit.

7. Commit your changes and push

Once you have completed your documentation, commit and push your changes to the remote repo

# Supply a commit message and push your changes
git add -a
git commit -m "initial draft"
git push --set-upstream-to origin/new-blog-entry-2022-05-02

8. Create a Pull Request

Now submit your pull request for another colleague to review your documentation.

• ←Previous
Next→