Maintenance: Tips, Tricks, and Traps

Disclaimer: Maintenance pages are for those who update this website. Nonetheless, everyone is free to look.

Hugo

• Beware of comments in Markdown, HTML, and/or Go. Because the three languages are mixed in-line in Hugo’s inputs, they don’t necessarily do what you might otherwise expect.
• Posts, and presumably pages and other input files, may be written in either markdown (*.md suffix), or HTML (*.html suffix). Hugo will “do the right thing.”
  • With HTML (*.html or *.htm), note that if you want to use shortcodes etc., the file must have front matter. Absent any front matter, the HTML will be copied as-is.
• A post will use its container’s name (the directory’s name) if the content is in an index.md (or presumably index.html) file therein. This style, for example content/posts/title-goes-here/index.md, is preferred, and any associated images may then be placed in a content/posts/title-goes-here/images/ sub-directory, and referred to in the post (article) as images/fn.webp.
• To prevent an empty summary bullet at a page’s top,
  • the summary: in the frontmatter must be removed (not just left empty or specified as false), and
  • Hugo’s “more” marker (an HTML comment) must be placed as the first line of the page’s content, and be spelled precisely as shown in the Hugo documentation.
• Categories are broad in nature; they should be kept to a minimum. Tags, however, are expected to be specific, and quite numerous. Keywords should be avoided as per industry SEO recommendations.
• In Markdown, to get a simple line break in a rendered HTML, do this:
  Leave two spaces at the end of the Markdown line
  And then continue on the next line.
• The full effects of changes in some files necessitate killing and re-launching hugo’s server. If something doesn’t look right, give this a try.
• Always include the --cleanDestinationDir when generating contnet: hugo --cleanDestinationDir or hugo --cleanDestinationDir server.
• When reading the Hugo documentation, it is vital to remember that *Content Sections" are the immediate subdirectories of content/. The most common are: content/pages/ and content/posts/, and this website adds content/maintanance/ and content/publications/. At the top of any Content Section, be it content/pages/, content/posts/, content/other/, or any other, Hugo looks for any *.md files.
• index.md, _index.md, and other *.md files within a deeper directory affect Hugo’s processing of that (and deeper-still) directories.
  • An index.md file in a directory deeper than the Content Section defining ones will cause Hugo to conclude this (deeper directory) is a leaf - an endpoint with no sub-subdirectories to process. The index.md file be processed with a single.html layout which, presumably, displays its {{ .Content }}. Any subsubdirectories (which Hugo is ignoring) are typically where images or other assets of the leaf are stored.
  • A Markdown file not named index.md or _index.md at these deeper levels are similarly displayed through a single.html layout. And as with index.md, Hugo believes this to be a leaf; it stops at this leve. It goes no deeper.
  • However, when an _index.md file is present, Hugo deems this a branch and applies a list.html layout assuming there are deeper directories to be processed (converted). Hugo then continues down the file-system hierarchy to the next level.
  • The presence of an _index.md file in addition to another Markdown file in that same directory should be avoided. Hugo does not document how this is handled. (And it is presumed any observed behaviour could change with the next release.)
  • Exceptions:
    • The exception to all this is content/_index.md. It contains the websites HOME page. (Note it is above the Content Section defining directories, hence it is above the above rules.)
    • In a similar vein, note that the home page content/_index.md is converted using layouts/index.html and that Hugo considers it a branch-type node so it should be coded as a list-type node. Regardless, the resulting webpage will be named /index.html.
• Enabling the direct-coding of HTML in the markdown is not recommended because Hugo does not always parse it as might be intended.
  Regardless of that, this feature can be enabled by placing the following in the site’s Hugo config.yaml file:

        # Enable HTML in Markdown files
        markup:
          goldmark:
            renderer:
              unsafe: true

• Similarly, use of the html shortcode to allow HTML coding in a markdown file is discouraged.
• Remember when invoking shortcodes:
  • {{% shortcode %}} - Use when the output contains markdown to be converted to HTML
  • {{< shortcode >}} - Use when the output does not contain markdown

Removing Wordpress

• To remove Wordpress from an existing site:
  • Determine the database name, user, and password from the site’s wp-admin.php file.
  • Connect to that database (mysql or equivalent):
    • show databases; # Should see one named wordpress
    • BEWARE: This will delete all wordpress data on that database.
      • drop database wordpress;
    • use mysql;
    • select User from users;
    • BEWARE: Make sure you nail the correct user, if any
      • delete from users where User='xxx';
    • quit;
  • In a shell or file browser connected to the hosting system:
    • cd /var/www/html/
    • BEWARE: Remove only what is appropriate
      • rm -rf wordpress/ # Might be different on your system
    • exit