# Vibrant Shadows
An insanely customizable, extremely lightweight and ridiculously fast 'Blog Theme' for Hugo, with mobile support and a lot more.
If you like our work & find it useful, please consider to star on GitHub. We are on [Facebook](https://www.facebook.com/Softorage/), [Twitter](https://twitter.com/Softorage) and [Instagram](https://www.instagram.com/softorage/), you can follow us there too! It really motivates us!
## Preview
| Desktop | Mobile |
|---| --- |
|  |  |
## Table of Contents
* [Features](#features)
* [Prerequisites](#prerequisites)
* [Getting up and running](#getting-up-and-running)
* [Setting up new Hugo website](#setting-up-new-hugo-website)
* [1. As a Hugo theme (recommended)](#1-as-a-hugo-theme-recommended)
* [2. As Git Submodule](#2-as-git-submodule)
* [Using boilerplate provided](#using-boilerplate-provided)
* [Installing the node dependencies](#installing-the-node-dependencies)
* [Get started](#get-started)
* [Configuration](#configuration)
* [Global Parameters](#global-parameters)
* [Hugo's built-in parameters](#hugos-built-in-parameters)
* [Vibrant Shadow's custom parameters](#vibrant-shadows-custom-parameters)
* [Page Parameters](#page-parameters)
* [Example `config.yaml`](#example-configyaml)
* [Built with](#built-with)
* [Contributing](#contributing)
* [License](#license)
## Features
* Blog with custom Taxonomy options, including tagging and category options
* Deeplinks
* Insanely customizable (see [config](#configuration))
* Dedicated 'Table of Contents'
* Logo alignment
* Sane defaults
* Mobile support with configurable menu alignment
* Syntax Highlighting
* Social-Media Share buttons on post
* Cookie Consent: "Opt-in", "Opt-out" and "None"
* Custom fonts for different elements
* SEO optimization and customization
* Ability to customize positions of various elements
## Prerequisites
Firstly, *ensure you have installed the latest (min v0.75.1) [extended version of Hugo](https://github.com/gohugoio/hugo/releases)*. You may need to scroll down a bit to see extended versions. Alternatively, you may see installation steps from [Hugo's official docs](https://gohugo.io/getting-started/installing/).
If you don't have or can't have extended version of Hugo installed, copy the resources folder from theme to root of your Hugo website directory. Hugo autodetects required files, and uses them. Note that it might make your website slightly slow to load.
## Getting up and running
Read the [prerequisites](#prerequisites) above and verify you're using the extended version of Hugo. There are at least two ways of quickly getting started with Hugo and the Vibrant Shadows theme:
### Setting up new Hugo website
```bash
hugo new site yourSiteName # generate a new Hugo site if you don't already have one
cd yourSiteName # move in to the Hugo website's directory
```
#### 1. As a Hugo theme (recommended)
1. Download the repo on your machine
2. Extract the zip file and rename the folder from `HugoTheme-VibrantShadows-master` to `HugoTheme-VibrantShadows`.
3. Copy this folder and paste it into `themes` folder in your Hugo Website directory. If there isn't a `themes` folder, create one.
4. Simply add the repo to your theme option in `config.yaml`:
```yaml
theme: "HugoTheme-VibrantShadows"
```
#### 2. As Git Submodule
Inside the folder of your Hugo site run:
```bash
git init # to initiate git if it isn't already
git submodule add https://github.com/Softorage/HugoTheme-VibrantShadows.git themes/HugoTheme-VibrantShadows # add theme as a git submodule
cp -a themes/HugoTheme-VibrantShadows/exampleSite/* . # start with the boilerplate by copying it into current directory
```
Then run
```bash
hugo server
```
And, we're done!
If you have extended version of Hugo installed, copy the `postcss.config.js` file to the root of your Hugo Website directory after setting up the theme. We also recommend creating a `package.json` file in your Hugo Website directory.
### Using boilerplate provided
If this is the first time you are setting up Hugo:
1. Copy the contents of `exampleSite` folder provided, and paste into your Hugo Website directory.
2. Then run `hugo server` in terminal.
### Installing the node dependencies
```bash
# Install nodejs and npm. Change the following command as per you distribution/OS.
sudo apt install nodejs npm
# Go to your Hugo Website directory, then open terminal and type:
npm install -g postcss postcss-cli autoprefixer cssnano @fullhuman/postcss-purgecss
```
### Get started
And, we're done! Now you can write your posts in Markdown format (.md file extension). You just need to keep these posts in `/content` directory. The directory structure that you make in the `content` directory also gets reflected as your blog's (or you website's) structure. For example, say you have post named `my-awesome-post.md` in `content/post/category-one`. Then the post will be available on the internet at `your-web-address.com/post/category-one/my-awesome-post`.
To create a new post, simply do [`hugo new`](https://gohugo.io/commands/hugo_new/) and Hugo will generate a new post for you using archetype. A post needs to have *front-matter* and *content*. *Front-matter* contains all the [Page Level parameters](#page-parameters), while *content* is your actual post.
To test how your blog looks, run `hugo serve`, and log on to the url given at the terminal (or command prompt) after you run `hugo serve`. The url is usually something like `localhost:1227`. To generate production ready website, simply run `hugo build`. Your website will be created in a directory named `public`. You can then copy and paste the contents of the `public` directory on the webserver, and the server should do the rest. You can also setup Hugo to build website automatically from the code and publish to the internet using GitLab, Netlify, etc. though it may require some technical knowledge.
Once set, jump over to the `config.yaml` file and start [configuring](#configuration) your site.
## Configuration
Here, we will mainly see settings that are unique to this theme. If something is not covered here (or elsewhere in this file), there's a good chance it is covered in [this Hugo docs page](https://gohugo.io/getting-started/configuration/#configuration-file). At the end of this section you will find an example `config.yaml` file, with all the options. It may serve in understanding all the options a bit better.
### Global Parameters
These options set global values that some pages or all pages in the site use by default.
#### Hugo's built-in parameters
1. **BaseURL** *(Type: String | Accepts value: URL | Required | No default)*
baseURL is the URL of the website or blog.
Example:
```yaml
baseurl: "https://example.com/"
```
2. **Title** *(Type: String | Accepts value: Text | Required | No default)*
It is the title of the website or blog. Title is usually same as brand name.
Example:
```yaml
title: "ExampleBlog"
```
3. **Author** *(Type: String | Accepts value: Text | Required | No default)*
We won't be using `site.Authors` till this parameter is finalised. See [here](https://github.com/gohugoio/hugo/issues/3088).
4. **Copyright** *(Type: String | Accepts value: Text | Optional | No default)*
It is the copyright text. Due consideration should be given to 'brandName or title' and 'contentLicense' specified in configuration file. Note that it isn't used in footer, but only [in defualt RSS template](https://gohugo.io/templates/rss/#configure-rss).
Example:
```yaml
copyright: "Copyright © 2020 ExampleBlog. All rights reserved."
```
5. **Language Code** *(Type: String | Accepts value: Text | Recommended | No default)*
It stores the language code for the website or blog.
Example:
```yaml
languageCode: "en-us"
```
6. **Theme** *(Type: String | Accepts value: Text | Required | No default)*
This is the name of the theme you are using.
Example:
```yaml
theme: "HugoTheme-VibrantShadows"
```
7. **Google Analytics** *(Type: String | Accepts value: Alphanumeric | Optional | No default)*
It is your Google Analytics ID, if any. Respecting your preference from 'privacy', and 'params -> user_experience' configuration, if you set this value, Google Analytics code will be included. Google Analytics included only when serving the website on 'production' environment (i.e. website built with `hugo` command and not `hugo serve`). If you wish to not use Google Analytics, do not set this variable; also set `disabled` to `true` in privacy configuration for Google Analytics.
Example-1:
```yaml
googleAnalytics: "UA-123456789-0" # the now deprecated Google Universal Analytics tag ID. Supported by Google till July 1, 2023.
```
Example-2:
```yaml
googleAnalytics: "G-123456789-0" # the Google Analytics tag 4 ID. Works only from Hugo v0.82.0 onwards.
```
8. **Disqus Shortname** *(Type: String | Accepts value: Alphanumeric | Optional | No default)*
It is your Disqus Shortname, if any. Respecting your preference from 'privacy', if you set this value, Disqus comments code will be included at the end of the blog posts. Disqus comments are shown only when serving the website on 'production' environment (i.e. website built with `hugo` command and not `hugo serve`)
Example:
```yaml
disqusShortname: "yourdiscussshortname"
```
9. **Taxonomies** *(Type: Map/Dict/Object | Accepts value: - | Optional | Default: Tags & Categories)*
This feature allows to define custom taxonomies for post/page management.
Example:
```yaml
taxonomies:
tag: "tags" # when defining custom taxonomies, we need to redefine even the default taxonomies if we wish to keep them, hence we have redefined 'tags'. see here: https://gohugo.io/content-management/taxonomies#example-adding-a-custom-taxonomy-named-series
category: "categories" # redefined 'categories'
series: "series" # defined a custom taxonomy, 'series'
```
10. **Menus** *(Type: Map/Dict/Object | Accepts value: - | Optional | No default)*
These are the menus that are used by users to navigate the website/blog. An example would be 'main' menu, which usually resides on navbar.
Example:
```yaml
menu:
main:
- identifier: "about" # different for all menu entries, useful especially when menu name coincides
name: "About" # shown on website/blog
url: "/about/" # user is taken to this url when user clicks on menu item
weight: 10 # used to sort menu items by weight
- identifier: "sub-about"
name: "Sub About"
url: "/sub-about/"
parent: "about"
weight: 1
```
11. **Build Stats** *(Type: Map/Dict/Object | Accepts value: - | Required)*
With this, Hugo notes some stats about website, which are then used by CSS processors.
Example:
```yaml
build:
writeStats: true
```
12. **Privacy** *(Type: Map/Dict/Object | Accepts value: - | Optional)*
This feature allows to maintain optimal privacy settings for the website/blog. You can see full list of privacy settings [here](https://gohugo.io/about/hugo-and-gdpr/#all-privacy-settings), and their explanation [here](https://gohugo.io/about/hugo-and-gdpr/#the-privacy-settings-explained).
Example:
```yaml
privacy:
disqus:
disable: false # | default: false
googleAnalytics:
anonymizeIP: true # 'true' makes it so the users' IP addresses are anonymized within Google Analytics | default: false
disable: false # | default: false
respectDoNotTrack: false # 'true' makes the GA templates respect the “Do Not Track” HTTP header | default: false
useSessionStorage: false # 'true' disables the use of Cookies and use Session Storage to Store the GA Client ID | default: false
```
#### Vibrant Shadow's custom parameters
All these properties come under Hugo's built-in property, `params`.
Example:
```yaml
params:
footerMessage: "Awesome footer message"
```
Let's see them one by one.
1. **Social** *(Type: Map/Dict/Object | Accepts value: - | Highly Recommended | No default)*
It stores information related to your social media profiles. It contains:
1. **Profiles** *(Type: Map/Dict/Object | Accepts value: - | Highly Recommended | No default)*
It stores your social media profiles. These are showcased as per your preference.
Supported platforms
```
facebook: "#"
twitter: "#"
github: "#"
gitlab: "#"
steam: "#"
instagram: "#"
youtube: "#"
pinterest: "#"
linkedin: "#"
reddit: "#"
flickr: "#"
deviantart: "#"
vk: "#"
mastodon: "#"
bandcamp: "#"
tumblr: "#"
medium: "#"
wikipedia: "#"
```
To be supported in future:
```
paypal: "#"
slack: "#"
twitch: "#"
stackoverflow: "#"
shutterstock: "#"
soundcloud: "#"
codepen: "#"
```