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.
|docs/faq||Frequently Asked Questions - 1 Document per Question|
|docs/guides||General Guides and Other Documents|
# 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
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.