Hermit-V2 Hugo Theme

Local Development

To preview your site locally, run the Hugo server with the -D flag to include posts marked as drafts:

hugo server -D

Your site will be available at http://localhost:1313.

Production Build

When ready to deploy, run the standard Hugo build command. The static files will be generated in the public/ directory:

hugo

To customize the theme without forking it, place files in your site's layouts/ directory. Any file you create will take precedence over the theme's equivalent.

Common override targets:

• layouts/_partials/svg.html: Modify SVG icons
• layouts/_partials/comments.html: Change comment systems
• layouts/_partials/analytics.html: Change analytics providers
• layouts/_partials/extra-head.html: Inject HTML into <head>
• layouts/_partials/extra-foot.html: Inject HTML before </body>

You can customize the theme's appearance by overriding SCSS files in your own assets/scss/ directory. The following files are available for overriding:

• _colors.scss: Color variables
• _fonts.scss: Typography and font stacks
• _syntax.scss: Code block color scheme
• _scrolltotop.scss: Scroll-to-top button styles
• _accessibility.scss: Accessibility-related styles

For general site-wide additions, create assets/scss/_userstyles.scss. Styles here are appended last and will override everything else.

To install Hermit-V2, first ensure you have a Hugo site initialized. You can then add the theme as a Git submodule to simplify future updates.

1. Clone the theme into your themes/hermit-v2 directory:

   git submodule add -b main https://github.com/1bl4z3r/hermit-V2 themes/hermit-v2

2. Update the theme to the latest version using:

   git submodule update --remote

3. Activate the theme by adding the following to your hugo.toml:

   theme = "hermit-v2"

The theme supports i18n (internationalization). To add a new language beyond the built-in ones (English, Spanish, French, Italian, German, and Simplified Chinese), follow these steps:

1. Identify an RFC 5646 language code for your target language.
2. Create a new translation file at i18n/<language-code>.toml.
3. Copy the existing English translation keys (found in i18n/en.toml) into your new file.
4. Translate the values assigned to the other key (e.g., other = "your translation").

Hermit-V2 uses enhanced archetypes to provide pre-populated front matter when creating new content.

• Regular pages should be placed in content/.
• Blog posts should be placed in content/posts/.

Use the hugo new command to generate files with the correct structure.

# Create a new regular page
hugo new page-title.md

# Create a new blog post
hugo new posts/post-title.md

To load specific assets for a single page, declare them in the page's front matter. Files must be placed in the assets directory.

Example Front Matter:

custom_css: ["custom_css/contact.css"]
custom_js:  ["custom_js/contact.js"]

Required Directory Structure:

• assets/custom_css/<file>.css
• assets/custom_js/<file>.js

Mermaid diagrams are rendered natively. Use a fenced code block with mermaid as the language identifier.

You can point Mermaid to a custom library via params.mermaidLib in hugo.toml.

flowchart TD
  A[Start] --> B{Is it working?}
  B -- Yes --> C[Great!]
  B -- No  --> D[Debug]

To apply specific styles when a page is printed:

1. Set print: true in the post's front matter.
2. Create an SCSS file at assets/custom_css/print.scss containing your overrides.

To use LaTeX, you must first enable Goldmark's passthrough extension to prevent Hugo from mangling delimiters, then enable MathJax globally or per-page.

Step 1: Configure Goldmark Passthrough

Add this to hugo.toml:

[markup]
  [markup.goldmark]
    [markup.goldmark.extensions]
      [markup.goldmark.extensions.passthrough]
        enable = true
        [markup.goldmark.extensions.passthrough.delimiters]
          block  = [['\[', '\]'], ['$$', '$$']]
          inline = [['\(', '\)']]

Step 2: Enable MathJax

Globally (in hugo.toml):

[params]
  global_mathjax = true

Per-page (in front matter):

mathjax: true

To use a custom library instead of the CDN, set params.mathjaxLib in hugo.toml.

[params]
  mathjaxLib = "https://your-cdn.example.com/mathjax/tex-chtml.js"