Vitrinev1.0.4
  1. Docs
  2. Getting started

Installation

Hugo, the theme, and the three settings Vitrine needs from your site.

Requirements

Check what you have:

sh 
hugo version
git --version
go version

Create a site

Skip this if you have one already.

sh 
hugo new project my-docs
cd my-docs
git init

Add the theme

There are two ways. A Hugo module is the modern one: Hugo downloads the theme itself, in the version you name, and updating is one command. A Git submodule puts a copy of the theme’s repository into your site’s themes/ folder and needs no Go.

Turn your site into a module, then import the theme in hugo.toml:

sh 
hugo mod init github.com/you/my-docs
hugo.toml 
[module]
  [[module.imports]]
    path = "github.com/maxfettinger/vitrine"
sh 
hugo mod get github.com/maxfettinger/vitrine@latest

The module path after init is a name for your site, usually its repository’s address; it doesn’t have to exist. Update the theme later with hugo mod get -u.

The settings Vitrine needs

Hugo lets a theme set only a few kinds of settings for a site (its params, menus, output formats and media types). Vitrine needs three more, so they go in your hugo.toml:

hugo.toml 
# Only Markdown files are pages: an example's example.html can sit in a folder next to its page
[contentTypes]
  [contentTypes.'text/markdown']

# Code colours as CSS classes, so light and dark mode can colour them
[markup.highlight]
  noClasses = false

# "On this page" lists the h2 and h3 headings
[markup.tableOfContents]
  startLevel = 2
  endLevel = 3

Without contentTypes, Hugo treats example.html in a page’s folder as a page of its own and the example shortcode can’t find it. Examples in assets/examples/ work either way.

And a title, a description for search engines and link previews, and the main menu, which becomes the tabs in the header:

hugo.toml 
baseURL = "https://docs.example.org/"
title = "my-lib"

[params]
  description = "my-lib does one thing well."

[[menus.main]]
  name = "Docs"
  pageRef = "/docs"
  weight = 10

Run it

sh 
hugo server

Open the address it prints, usually http://localhost:1313/. The page reloads while you edit. Next: your first pages.