If you make any website using this theme I encourage you to open an issue, I will be glad to showcase your site.
Table of contents
I highly recommend to read the
How to use section if you want to use
this theme, you may find yourself lost if you don't.
- Social media
- Custom imports
How to use (MUST READ)
This is not the usual Hugo theme you can download and start adding contents right away. But don't get scared, you won't need to read all this document in order to create your site. Unless you aim to create something very customized, you just need to read the basics. Making the theme a SPA comes with some essential features you need to know before starting to build your website.
The only thing you need in order to use this theme is Hugo. If you still don't have it, you can find a complete installation guide here.
I highly recommend Hugo 0.48 or higher, but it may work with older versions superior to 0.43. If you have any trouble with your Hugo version using this theme, I invite you to open an issue on Github so I can help you.
You can find the Hugo's theme installation guide here. But those are the basic steps you should be following (assuming you already installed Hugo):
Open a terminal wherever you want to create your new site. Invoke Hugo to do so using the following command (your Hugo base command may be different):
hugo new site NAME_OF_YOUR_SITE
Navigate to the
themes folder of your site from the terminal:
cd NAME_OF_YOUR_SITE cd themes
Clone this repository inside the
themes folder your are in:
git clone https://github.com/SAGGameDeveloper/hugo-minimalist-spa
Go to the root folder of your site, open the
config.toml file and
set the theme with the following line:
theme = "hugo-minimalist-spa"
That's all! You can now go and test your new site. To do so, open a terminal in the root folder of your site and use:
hugo server -w
To see your new site, you just have to go to
your web browser. This is the local server that will be hosting
your website, as long as you keep that terminal opened.
Adding content to your site is very straightforward, just putting your
.md files into
content folder will do (keep reading).
Take into account that if you change the contents, the individual URL's of each content tab will mostly sure change. So if you just reload your browser your URL may still be pointing to the past tabs names. That will cause the reload to partly or completely fail. So make sure your URL is the right one if you change your content files/filenames.
To add custom content you need add your MarkDown files to the
content default folder of your site. All the content of your page
will be loaded from here, and it MUST be on Markdown (
Do not add any other files/folders into
content. If you do,
the theme will still treat it as a Markdown file, causing
major problems with your final HTML. Also, I highly recommend not
to use spaces or special characters in your filenames, that could
cause critical bugs with the URL's and the loading of your files.
Inside you markdown files you can write HTML if you want,
it will be added to the final
index.html automatically. If you
need to use routes to elements inside your HTML, remember that paths
are relative to the final
There are two ways to title your content. You can use the filename (NOT RECOMMENDED); just create your Markdown file and name it the way you want. Or you can set a custom title inside the Markdown file (RECOMMENDED); start your file with the following snippet, and set the title to the one you want:
--- title: Your title goes here ---
The navigation bar will automatically order your contents alphabetically by filename (not title!). So if you use the filename as title, you cannot only manually order your pages, but you could also cause bugs with the URL (depending on the characters you use).
If you want to manually order your content, I recommend you to name your files alphabetically with the order you want (letters better than numbers), then setting the title inside the Markdown as explained before.
To be able to configure your own website parameters (such as the website title),
you need to have your own
config.toml (or the Hugo supported language
your prefer) in your website's root.
To modify the author, title and language just write it down normally. Using
author = "Me" languageCode = "en-us" title = "My website's title"
To modify the description you need to do it within the
params section. Using
[params] description = "This is my website"
Modifying the social media icons is quite simple, the moment you add your own, the theme default social media will disappear. Here you can see a list of supported icons:
To add your social media just create a
social-media.toml (or the Hugo supported language
your prefer) inside your
data/ folder, in your website's root directory. Then write down
every social media you want with the following syntax (or equivalent if not using
[github] source = "images/social_media/github.svg" target = "https://www.github.com" [name_of_another_socialmedia] source = "path_to_the_icon" target = "socialmedia_url"
All of the supported icons are in
images/social_media/, with its name being the name
of the social media (without spaces and caps) plus the
If you want to add custom icons or custom social-media, you just have to add your images
static/images/social_media/ folder of your own website. Remember that the path to
the source does not start in the
static/ folder, since it disappears after building your
page with Hugo.
Ordering social media
Social media elements are sorted alphabetically by the name you give them. If you want to
keep a certain order, I recommend you to put a number before the name of each element, such
as this (in
[2-github] source = "images/social_media/github.svg" target = "https://www.github.com" [1-instagram] source = "images/social_media/instagram.svg" target = "https://www.instagram.com"
In this case, instagram would be the first social media element, while github would appear right after it. Declaration order does not matter, you can place the elements as you wish in the document.
You can import your own files adding one layout to your page. To do so, create a file
custom_imports.html and put it inside the
layouts/partials/ folder (create it
if you don't have one) of your website.
Hugo minimalist SPA allows you to customize many aspects of its appearance.
You can set custom colors for the theme so you can make it look as you want.
To do so, start by creating a
data folder in the root of your
website. The whole theme is based on 5 colors, so those are the ones you can set. In
# HEADER/NAVBAR COLORS color_header = "#111111" #Background color of the header color_navbar = "#474747" #Background color of the navbar color_social_media = "#1f84b6" #Color of the social media icons color_social_media_hover = "#FFB865" #Color of the social media icons on hover color_navbar_elements = "white" #Color of the navbar elements color_navbar_elements_hover = "#FFC98A" #Color of the navbar elements on hover # MAIN CONTENT COLORS color_text = "black" #Color of normal text color_h1 = "#5863b8" #Color of the h1 elements color_h2 = "#505792" #Color of the h2 elements color_h3 = "#464c7d" #Color of the h3 elements color_link = "#1f84b6" #Color of the main content links color_link_hover = "#FFB865" #Color of the main content links on hover
Those variables are directly passed to the SASS files, so you can use any CSS supported color you want.
The background of the main content is not a color but an image. You can replace it with
your own webpage static files as with any other element, just put a
static/images folder of your site and Hugo will use it automatically. If you want
to use a color instead, you will need to modify the SASS file named
assets/sass/partials. Replace the
background: url(...); statement with
Fonts, images and other static files
Hugo uses Less Sans
(created by Wassim Awadallah) as its default font.
You can add your custom fonts using the
custom_imports.html explained before, but that would
require you to change the SASS source files to use this new font. If you don't want to get
into that mess, you can just rename your font to
default-bold.otf respectively. Then put those files into your
static/fonts folder (create
it if you don't have one) and the will be automatically used as the default font.
To change the logo you need to do the same process, name your logo file (must be a
logo.png. Then place it inside your
static/images/ folder (create it if you don't have one)
and it will be automatically used.
Your static folder is yours, so you can place any asset you might want to use inside, but only
those mentioned in this document have native theme support and will be automatically used. Remember
that every asset included in
static/ will be served into the final building, even if you never use it.
SASS and CSS
You can add your custom CSS as you would do with your normal site, then import it using the custom imports explained before,
Hugo minimalist SPA is built using only SASS, so if you want to modify it I recommend you to read the source files. I do not recommend at all to modify the compiled CSS, that won't keep the modifications the next time you build your website, and it will probably be much harder to do.
You can find the SASS source files in the theme
assets/sass/ folder. In this case, imports are made
by the SASS compiler, so Hugo won't look in your
assets folder before it does in the theme's. So,
if you want to customize the SASS, the simplest option is to modify the theme's files. This is not a practice
I would recommend in normal situations at all, but due to Hugo limitations there's no better way to do
it without getting too deep.
You can modify the core source of the theme directly if you want, here you will find some important aspects to take into account if you do so.
If you want to modify it, you can find the code on
static/js. There are other ways of achieving the same result
The Go implementation that does this can be found in
They use the filename and custom title (if there's any) to inject the proper id's into the final HTML. Those id's are then
Due to Hugo limitations, the custom titles cannot be directly injected into the navigation bar for their use.
To skip this problem, I use a temporal
<div> whose id is the custom title. This
<div> is set in the
which has direct access to the
a custom title has been set), and uses it to set the navigation bar proper names. After that it extracts the inner HTML of
<div>, created by the single layout, to finally get disposed of it.
This project is licensed under the MIT License - see the LICENSE file for details.
If you want to contribute to this theme, you can make a pull request and I will be glad to check it out.
You can modify this theme as much as you want. If you want to distribute a modified version, you must publish a link to this repository indicating that I'm the original author. Also, I would appreciate if you notified me so I can see it.