Instructions on how to use and run Hugo to manage this site.

Creating Posts

Choose a taxonomy:

• blog - for non-specific posts
• news - for site and important updates
• technical - for cheat sheets, notes, dotfiles, and the like
• [future] pictures - for pic posts
• [future] perspectives - for posts in the various Perspectives On series

For technical posts:

hugo new technical/cheat_sheets/hugo_cheat_sheet/index.md

For all non-technical posts:

hugo new blog/(YYYY)/(post_dir_name)/index.md

Checklist for new post frontmatter:

• check draft is set to false - the default
• update title: - it will be set to the directory name
• add a slug: for permalink name for the post
• add a lead: for a subtitle
• change toc: true for long posts
  • TOC only lists top level headers (# heading)
• update categories and tags as necessary

Editing Posts

• Each post is stored in its own directory
• Post contents are stored in an index.md file in the post directory
• Images are placed in the post directory
  • Where possible include an AVIF as well as a JPG/PNG file using the figure_avif shortcode

Publishing Posts

When a post is ready:

• re-check post frontmatter
  • add/update categories and tags
  • update post date
• review post using hugo server --buildDrafts
• update draft status to false

To update and publish the site:

• build site using hugo --minify --cleanDestinationDir
• sync public folder to the publishing repository
• check changes to the publishing repository to check:
  • Expected new posts and resources are added
  • No unexpected posts or resources have been added
  • Check which parts of the site are updated/rewritten for the new post
  • NOTE: This process can also indicate typos in categories and tags - as new files for the incorrect entries will be created
• stage and commit changes in the publishing repository
• push main branch of publishing repository to online provider
• check that the online site is updated with the new post