Hugo

About

• TODO
• SSG
• Template
• CMS
• Hugo
  • Setup
• Hugo relearn theme
  • Page layouts / Templates / Archetypes
  • CSS
  • Markdown
  • Tags
  • Multiple Languages
  • Shortcodes

TODO

• What is Output format (PLAINTEXT / default.plaintext.html)?
• What are hook partial files (.html)?

SSG

A list of Static Site Generators (SSG):

• Next.js
• Hugo
• Gatsby
• Docusaurus
• Nuxt
• Jekyll
• Hexo
• Slate
• Astro
• GitBook
• Docsify
• VuePress
• MkDocs
• SvelteKit
• Eleventy
  …

A complete list can be found here.

Template

Templates make your HTML code reuseable, lets you define variables and lets you even group pages through a formatter and loop them. Templates do use a formatter which is the head / metadata of content files. A list of some template languages which Eleventy uses:

HTML*.html EJS*.ejs Markdown*.md Haml*.haml WebC*.webc Pug*.pug JavaScript*.11ty.js TypeScript*.ts Liquid*.liquid JSX*.jsx Nunjucks*.njk MDX*.mdx Handlebars*.hbs Mustache*.mustache Custom*.*

CMS

Content Management System is a backend which lets you login as admin and modify your content. In a blog you could for example write and publish a new article all in the CMS. There a headless and headful CMSs. A list of some CMS:

• Strapi
• Ghost
• Directus
• WordPress
• Decap CMS / Netlify CMS
• Wagtail
• Playload CMS
• Tina
• Keystone
• Webiny
• Builder.io
• Publii
  …
• TYPO3
  …

A more copmplete list is here.

Hugo

How to get a hugo project running?

1. Install hugo
2. Create a new hugo project: hugo new site <path>
3. Optionally install a hugo theme: git submodule add <repo-url> & add theme = "relearn" to hugo.toml.
4. Add content: hugo new content content/_index.md & set draft to false.
5. Run server: ``hugo server`
6. Publish site: hugo
7. Setup hugo.toml correctly (baseURL, languageCode, title).

You can run the hugo server with more arguments to specify a port: hugo server --bind 192.168.178.30 --baseURL http://192.168.178.30 --port 8080. This is usful because using the default version could cause issues if you want to connect to this website with a different device (from inside your network). For full rebuilds on change: hugo server –disableFastRender.

See: https://gohugo.io/getting-started/quick-start/

Hugo relearn theme

Relearn theme

Page layouts / Templates / Archetypes

Create home page: hugo new --kind home _index.md Create chapter: hugo new --kind chapter <name>/_index.md Create default page: hugo new <chapter>/<name>/_index.md or hugo new <chapter>/<name>.md (unknoen archetypes result in the default archetype)

Use your own page layouts / templates:

1. Create archetypes/<kind>.md and it requires archetype = "<kind>" in its frontmatter.
2. Use it: hugo new --kind <kind> <name>/_index.md

Further customize Archetypes with Partials:

1. Create layouts/partials/archetypes/<kind>

CSS

You can use a custom theme variant, by create a file named theme-<name>.css inside assets/css. If you want this theme to based on another theme you could write at the top of this file for example @import "theme-relearn-dark.css";. It is required to specify the used chroma for this theme. Chroma is a additional CSS file which specifies the styling for code blocks. You can create a own chroma inside assets/css named chroma-<name>.css or just use a already existing one: :root { --CODE-theme: relearn-dark; }. To actually use this theme variant you have to set it inside config.toml: [params] themeVariant = "<name>".

Markdown

Extentions
The relearn theme has the Goldmark markdown standard and additional extentions can be activated. See hugo goldmark extention github: https://github.com/gohugoio/hugo-goldmark-extensions?tab=readme-ov-file#extras-extension. A lot of extentions are activated by default, but Èxtra is one of the extentions you can activate to have additional text formatting.

If you want to use HTML inside your Markdown files, then you have to enable that inside your config.toml file: [markup] [markup.goldmark] [markup.goldmark.renderer] unsafe = true. Alternatively, you can create shortcodes and use them, what is the recommended way.

Keys
Use the <kbd>-tag to add keys. For example: STRG ALT DEL

Tasks

• Basic Test
• More Tests
  • View
  • Hear
  • Smell

Reference ID
You can store your link in a variable / as reference ID to have your URL at one place:

![MyImage][somelinkID]
[MyLink][somelinkID]
[somelinkID]: https://example.com "Go to example domain"

Image effects
You can set query parameter at the end of the image URL to apply an effect. Some examples:

You can set image effects as default:

[params]
  [params.imageEffects]
    border = false
    lazy = true
    lightbox = true
    shadow = false

You can add custom image effects by writing the classes. For example bg-white and nobg-white and then they can be used in toml, frontmatter and of course as query parameter in the URL.

Tags

In the frontmatter you can define tags (tags = 'tutorial'). Tags are displayed at the top and link to a overview page where all chapters with the same tag are listed. You can link a overview page about all tags and categories in your toml file:

[menu]
  [[menu.shortcuts]]
    name = "<i class='fa-fw fas fa-tags'></i> Tags"
    url = '/tags'

  [[menu.shortcuts]]
    name = "<i class='fa-fw fas fa-layer-group'></i> Categories"
    url = '/categories'

Multiple languages

Your default language files does not need an language prefix (e.g. chapter.en.md -> chapter.md). Default language is your first language defined in the [languages] list in .toml. You can use i18n by adding a file e.g. i18n/en.toml. This is intended to be used for common default values (button, search placeholder, ..), but nothing more.

Shortcodes

The hugo relearn theme has multiple shortcodes which can be called with ‘{{% .. %}}’. You can enable the use of HTML inside your Markdown files (inside config.toml), but it is recommended to create and use shortcodes.