Write basic theme documentation
This commit is contained in:
Yash Mehrotra
@@ -8,11 +8,11 @@ enableEmoji = true
|
|||||||
paginate = 20
|
paginate = 20
|
||||||
|
|
||||||
# Choose one of emacs, trac or perldoc
|
# Choose one of emacs, trac or perldoc
|
||||||
pygmentsStyle = "emacs"
|
pygmentsStyle = "monokai"
|
||||||
|
|
||||||
[params]
|
[params]
|
||||||
footer = "The Marauders"
|
footer = "The Marauders"
|
||||||
description = "You miss 100% of the shots you don't take"
|
description = "Sky above, sand below & peace within"
|
||||||
avatarURL = "https://upload.wikimedia.org/wikipedia/commons/7/7a/1859-Martinique.web.jpg"
|
avatarURL = "https://upload.wikimedia.org/wikipedia/commons/7/7a/1859-Martinique.web.jpg"
|
||||||
customHTML = ""
|
customHTML = ""
|
||||||
showPostsOnHomePage = "popular"
|
showPostsOnHomePage = "popular"
|
||||||
@@ -34,18 +34,18 @@ pygmentsStyle = "emacs"
|
|||||||
weight = 3
|
weight = 3
|
||||||
|
|
||||||
[[menu.main]]
|
[[menu.main]]
|
||||||
name = "Resume"
|
name = "Tags"
|
||||||
url = "/resume/"
|
url = "/tags/"
|
||||||
weight = 4
|
weight = 4
|
||||||
|
|
||||||
[[menu.main]]
|
[[menu.main]]
|
||||||
identifier = "linkedin"
|
identifier = "coffee"
|
||||||
pre = "<span data-feather='linkedin'></span>"
|
pre = "<span data-feather='coffee'></span>"
|
||||||
url = "/a/"
|
url = "/a/"
|
||||||
weight = 5
|
weight = 5
|
||||||
|
|
||||||
[[menu.main]]
|
[[menu.main]]
|
||||||
identifier = "github"
|
identifier = "github"
|
||||||
pre = "<span data-feather='github'></span>"
|
pre = "<span data-feather='github'></span>"
|
||||||
url = "/b/"
|
url = "https://github.com/526avijitgupta/gokarna"
|
||||||
weight = 6
|
weight = 6
|
||||||
|
|||||||
@@ -1,6 +1,6 @@
|
|||||||
---
|
---
|
||||||
title: "Markdown Syntax Guide"
|
title: "Markdown Syntax Guide"
|
||||||
date: 2019-06-01T17:55:28+08:00
|
date: 2019-06-19
|
||||||
description: "Sample article showcasing basic Markdown syntax and formatting for HTML elements."
|
description: "Sample article showcasing basic Markdown syntax and formatting for HTML elements."
|
||||||
tags: ["markdown", "css", "html"]
|
tags: ["markdown", "css", "html"]
|
||||||
type: post
|
type: post
|
||||||
|
|||||||
465
exampleSite/content/posts/theme-documentation-advanced.md
Normal file
465
exampleSite/content/posts/theme-documentation-advanced.md
Normal file
@@ -0,0 +1,465 @@
|
|||||||
|
---
|
||||||
|
weight: 1
|
||||||
|
title: "Theme Documentation - Advanced"
|
||||||
|
date: 2020-05-06T21:29:01+08:00
|
||||||
|
description: "Discover what the Hugo - gokarna theme is all about and the core-concepts behind it."
|
||||||
|
tags: ["installation", "configuration", "markdown"]
|
||||||
|
type: post
|
||||||
|
---
|
||||||
|
|
||||||
|
Discover what the Hugo - Gokarna theme is all about and the core-concepts behind it.
|
||||||
|
TODO: Similar intro as in README, opinionated, authors
|
||||||
|
|
||||||
|
## 1 Requirements
|
||||||
|
|
||||||
|
Thanks to the simplicity of Hugo, [Hugo](https://gohugo.io/) is the only dependency of this theme.
|
||||||
|
|
||||||
|
## 2 Installation
|
||||||
|
|
||||||
|
The following steps are here to help you initialize your new website. If you don’t know Hugo at all, we strongly suggest you learn more about it by following this [great documentation for beginners](https://gohugo.io/getting-started/quick-start/).
|
||||||
|
|
||||||
|
### 2.1 Create Your Project
|
||||||
|
|
||||||
|
Hugo provides a `new` command to create a new website:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
hugo new site my_website
|
||||||
|
cd my_website
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2.2 Install the Theme
|
||||||
|
|
||||||
|
The theme’s repository is: [https://github.com/526avijitgupta/gokarna](https://github.com/526avijitgupta/gokarna).
|
||||||
|
|
||||||
|
You can download the [latest release :books: .zip file](https://github.com/526avijitgupta/gokarna/releases) of the theme and extract it in the `themes` directory.
|
||||||
|
|
||||||
|
Alternatively, clone this repository to the `themes` directory:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git clone https://github.com/526avijitgupta/gokarna.git themes/gokarna
|
||||||
|
```
|
||||||
|
|
||||||
|
Or, create an empty git repository and make this repository a submodule of your site directory:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git init
|
||||||
|
git submodule add https://github.com/526avijitgupta/gokarna.git themes/gokarna
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2.3 Basic Configuration {#basic-configuration}
|
||||||
|
|
||||||
|
The following is a basic configuration for the gokarna theme:
|
||||||
|
|
||||||
|
```toml
|
||||||
|
baseURL = "http://example.org/"
|
||||||
|
defaultContentLanguage = "en"
|
||||||
|
languageCode = "en"
|
||||||
|
|
||||||
|
title = "My New Hugo Site"
|
||||||
|
|
||||||
|
theme = "gokarna"
|
||||||
|
|
||||||
|
[params]
|
||||||
|
# URL for the avatar on homepage
|
||||||
|
avatarURL = ""
|
||||||
|
|
||||||
|
# Description to display on homepage
|
||||||
|
description = "Sky above, sand below & peace within"
|
||||||
|
|
||||||
|
# You can use this to inject any HTML in the <head> tag.
|
||||||
|
# Ideal usecase for this is to import custom js/css or add your analytics snippet
|
||||||
|
customHTML = ""
|
||||||
|
|
||||||
|
# If you want to display posts on the homepage, the options are
|
||||||
|
# "popular" (order posts by weight), "recent" (order posts by date)
|
||||||
|
# or "" (do not display, default option)
|
||||||
|
showPostsOnHomePage = ""
|
||||||
|
|
||||||
|
# Footer text
|
||||||
|
footer = "The Marauders"
|
||||||
|
|
||||||
|
[menu]
|
||||||
|
[[menu.main]]
|
||||||
|
# Unique identifer for a menu item
|
||||||
|
identifier = "posts"
|
||||||
|
|
||||||
|
url = "/posts/"
|
||||||
|
|
||||||
|
# You can add extra information before the name (HTML format is supported), such as icons
|
||||||
|
pre = ""
|
||||||
|
|
||||||
|
# You can add extra information after the name (HTML format is supported), such as icons
|
||||||
|
post = ""
|
||||||
|
|
||||||
|
# Display name
|
||||||
|
name = "Posts"
|
||||||
|
|
||||||
|
# Weights are used to determine the ordering
|
||||||
|
weight = 1
|
||||||
|
|
||||||
|
[[menu.main]]
|
||||||
|
identifier = "tags"
|
||||||
|
pre = ""
|
||||||
|
post = ""
|
||||||
|
name = "Tags"
|
||||||
|
url = "/tags/"
|
||||||
|
title = ""
|
||||||
|
weight = 2
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
|
### 2.4 Create Your First Post
|
||||||
|
|
||||||
|
Here is the way to create your first post:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
hugo new posts/first_post.md
|
||||||
|
```
|
||||||
|
|
||||||
|
Feel free to edit the post file by adding some sample content and replacing the title value in the beginning of the file.
|
||||||
|
|
||||||
|
By default all posts and pages are created as a draft. If you want to render these pages, remove the property `draft: true` from the metadata, set the property `draft: false` or add `-D`/`--buildDrafts` parameter to `hugo` command.
|
||||||
|
|
||||||
|
### 2.5 Launching the Website Locally
|
||||||
|
|
||||||
|
Launch by using the following command:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
hugo serve
|
||||||
|
```
|
||||||
|
|
||||||
|
Go to `http://localhost:1313`.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
When you run `hugo serve`, when the contents of the files change, the page automatically refreshes with the changes.
|
||||||
|
|
||||||
|
Since the theme use `.Scratch` in Hugo to implement some features,
|
||||||
|
it is highly recommended that you add `--disableFastRender` parameter to `hugo server` command for the live preview of the page you are editing.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
hugo serve --disableFastRender
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2.6 Build the Website
|
||||||
|
|
||||||
|
When your site is ready to deploy, run the following command:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
hugo
|
||||||
|
```
|
||||||
|
|
||||||
|
A `public` folder will be generated, containing all static content and assets for your website. It can now be deployed on any web server.
|
||||||
|
|
||||||
|
The website can be automatically published and hosted with [Netlify](https://www.netlify.com/) (Read more about [Automated HUGO deployments with Netlify](https://www.netlify.com/blog/2015/07/30/hosting-hugo-on-netlifyinsanely-fast-deploys/)).
|
||||||
|
Alternatively, you can use [AWS Amplify](https://gohugo.io/hosting-and-deployment/hosting-on-aws-amplify/), [Github pages](https://gohugo.io/hosting-and-deployment/hosting-on-github/), [Render](https://gohugo.io/hosting-and-deployment/hosting-on-render/) and more...
|
||||||
|
|
||||||
|
## 3 Configuration
|
||||||
|
|
||||||
|
### 3.1 Site Configuration {#site-configuration}
|
||||||
|
|
||||||
|
In addition to [Hugo global configuration](https://gohugo.io/overview/configuration/) and [menu configuration](#basic-configuration), **gokarna** lets you define the following parameters in your site configuration (here is a `config.toml`, whose values are default).
|
||||||
|
|
||||||
|
Please open the code block below to view the complete sample configuration :(far fa-hand-point-down fa-fw)::
|
||||||
|
|
||||||
|
```toml
|
||||||
|
[params]
|
||||||
|
version = "1.0.X"
|
||||||
|
# site description
|
||||||
|
description = "This is My New Hugo Site"
|
||||||
|
# site keywords
|
||||||
|
keywords = ["Theme", "Hugo"]
|
||||||
|
# site default theme ("light", "dark", "auto")
|
||||||
|
defaultTheme = "auto"
|
||||||
|
# public git repo url only then enableGitInfo is true
|
||||||
|
gitRepo = ""
|
||||||
|
# ("sha256", "sha384", "sha512", "md5")
|
||||||
|
fingerprint = ""
|
||||||
|
dateFormat = "2006-01-02"
|
||||||
|
# website images for Open Graph and Twitter Cards
|
||||||
|
images = ["/logo.png"]
|
||||||
|
SourceMap = true
|
||||||
|
|
||||||
|
[params.pwa]
|
||||||
|
# whether to enable PWA support
|
||||||
|
enable = true
|
||||||
|
# service-worker version
|
||||||
|
version = "1.0.1"
|
||||||
|
|
||||||
|
[params.app]
|
||||||
|
# optional site title override for the app when added to an iOS home screen or Android launcher
|
||||||
|
title = "gokarna"
|
||||||
|
# whether to omit favicon resource links
|
||||||
|
noFavicon = false
|
||||||
|
# modern SVG favicon to use in place of older style .png and .ico files
|
||||||
|
svgFavicon = ""
|
||||||
|
# Android browser theme color
|
||||||
|
themeColor = "#ffffff"
|
||||||
|
# Safari mask icon color
|
||||||
|
iconColor = "#5bbad5"
|
||||||
|
# Windows v8-10 tile color
|
||||||
|
tileColor = "#da532c"
|
||||||
|
|
||||||
|
[params.search]
|
||||||
|
enable = true
|
||||||
|
# type of search engine ("lunr", "algolia")
|
||||||
|
|
||||||
|
# Header config
|
||||||
|
[params.header]
|
||||||
|
# desktop header mode ("fixed", "normal", "auto")
|
||||||
|
desktopMode = "fixed"
|
||||||
|
# mobile header mode ("fixed", "normal", "auto")
|
||||||
|
mobileMode = "auto"
|
||||||
|
[params.header.title]
|
||||||
|
# URL of the LOGO
|
||||||
|
logo = ""
|
||||||
|
rss = true
|
||||||
|
|
||||||
|
# Footer config
|
||||||
|
[params.footer]
|
||||||
|
enable = true
|
||||||
|
# license info (HTML format is supported)
|
||||||
|
license = '<a rel="license external nofollow noopener noreffer" href="https://creativecommons.org/licenses/by-nc/4.0/" target="_blank">CC BY-NC 4.0</a>'
|
||||||
|
home = ["HTML", "RSS", "JSON"]
|
||||||
|
page = ["HTML", "MarkDown"]
|
||||||
|
section = ["HTML", "RSS"]
|
||||||
|
taxonomy = ["HTML", "RSS"]
|
||||||
|
taxonomyTerm = ["HTML"]
|
||||||
|
```
|
||||||
|
|
||||||
|
Note that some of these parameters are explained in details in other sections of this documentation.
|
||||||
|
|
||||||
|
Default environments are `development` with `hugo serve` and `production` with `hugo`.
|
||||||
|
|
||||||
|
Due to limitations in the local `development` environment,
|
||||||
|
the **comment system**, **CDN** and **fingerprint** will not be enabled in the `development` environment.
|
||||||
|
|
||||||
|
You could enable these features with `hugo serve -e production`.
|
||||||
|
|
||||||
|
````
|
||||||
|
|
||||||
|
The default CDN data file is located in `themes/gokarna/assets/data/cdn/` directory.
|
||||||
|
You can store your own data file in the same path under your project: `assets/data/cdn/`.
|
||||||
|
|
||||||
|
|
||||||
|
You can directly set your ID to get a default social link and its icon:
|
||||||
|
|
||||||
|
```toml
|
||||||
|
[params.social]
|
||||||
|
Mastodon = "@xxxx"
|
||||||
|
```
|
||||||
|
|
||||||
|
The social link generated is `https://mastodon.technology/@xxxx`.
|
||||||
|
|
||||||
|
Or You can set more options through a dict:
|
||||||
|
|
||||||
|
```toml
|
||||||
|
[params.social]
|
||||||
|
[params.social.Mastodon]
|
||||||
|
# weight when arranging icons (the greater the weight, the later the icon is positioned)
|
||||||
|
weight = 0
|
||||||
|
# your social ID
|
||||||
|
id = "@xxxx"
|
||||||
|
# prefix of your social link
|
||||||
|
prefix = "https://mastodon.social/"
|
||||||
|
# content hovering on the icon
|
||||||
|
title = "Mastodon"
|
||||||
|
```
|
||||||
|
|
||||||
|
The default data of all supported social links is located in `themes/gokarna/assets/data/social.yaml`,
|
||||||
|
which is you can refer to.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
### 3.2 Favicons, Browserconfig, Manifest
|
||||||
|
|
||||||
|
It is recommended to put your own favicons:
|
||||||
|
|
||||||
|
* apple-touch-icon.png (180x180)
|
||||||
|
* favicon-32x32.png (32x32)
|
||||||
|
* favicon-16x16.png (16x16)
|
||||||
|
* mstile-150x150.png (150x150)
|
||||||
|
* android-chrome-192x192.png (192x192)
|
||||||
|
* android-chrome-512x512.png (512x512)
|
||||||
|
|
||||||
|
into `/static`. They’re easily created via [https://realfavicongenerator.net/](https://realfavicongenerator.net/).
|
||||||
|
|
||||||
|
Customize `browserconfig.xml` and `site.webmanifest` to set theme-color and background-color.
|
||||||
|
|
||||||
|
### 3.3 Style Customization
|
||||||
|
|
||||||
|
Hugo **extended** version is necessary for the style customization.
|
||||||
|
|
||||||
|
**gokarna** theme has been built to be as configurable as possible by defining custom `.scss` style files.
|
||||||
|
|
||||||
|
The directory including the custom `.scss` style files is `assets/css` relative to **your project root directory**.
|
||||||
|
|
||||||
|
In `assets/css/_override.scss`, you can override the variables in `themes/gokarna/assets/css/_variables.scss` to customize the style.
|
||||||
|
|
||||||
|
Here is a example:
|
||||||
|
|
||||||
|
```scss
|
||||||
|
@import url('https://fonts.googleapis.com/css?family=Fira+Mono:400,700&display=swap&subset=latin-ext');
|
||||||
|
$code-font-family: Fira Mono, Source Code Pro, Menlo, Consolas, Monaco, monospace;
|
||||||
|
```
|
||||||
|
|
||||||
|
In `assets/css/_custom.scss`, you can add some css style code to customize the style.
|
||||||
|
|
||||||
|
## 4 Multilingual and i18n
|
||||||
|
|
||||||
|
**gokarna** theme is fully compatible with Hugo multilingual mode, which provides in-browser language switching.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
### 4.1 Compatibility {#language-compatibility}
|
||||||
|
|
||||||
|
|
||||||
|
| Language | Hugo Code | HTML `lang` Attribute | Theme Docs | Lunr.js Support |
|
||||||
|
|:-------------------- |:---------:|:---------------------:|:-----------------------------:|:-----------------------------:|
|
||||||
|
| German | `de` | `de` | :(far fa-square fa-fw): | :(far fa-check-square fa-fw): |
|
||||||
|
| English | `en` | `en` | :(far fa-check-square fa-fw): | :(far fa-check-square fa-fw): |
|
||||||
|
| Spanish | `es` | `es` | :(far fa-square fa-fw): | :(far fa-check-square fa-fw): |
|
||||||
|
| French | `fr` | `fr` | :(far fa-square fa-fw): | :(far fa-check-square fa-fw): |
|
||||||
|
| Indonesian | `id` | `id` | :(far fa-square fa-fw): | :(far fa-check-square fa-fw): |
|
||||||
|
| Italian | `it` | `it` | :(far fa-square fa-fw): | :(far fa-check-square fa-fw): |
|
||||||
|
| Polish | `pl` | `pl` | :(far fa-square fa-fw): | :(far fa-square fa-fw): |
|
||||||
|
| Brazilian Portuguese | `pt-br` | `pt-BR` | :(far fa-square fa-fw): | :(far fa-check-square fa-fw): |
|
||||||
|
| Romanian | `ro` | `ro` | :(far fa-square fa-fw): | :(far fa-check-square fa-fw): |
|
||||||
|
| Russian | `ru` | `ru` | :(far fa-square fa-fw): | :(far fa-check-square fa-fw): |
|
||||||
|
| Serbian | `sr` | `sr` | :(far fa-square fa-fw): | :(far fa-square fa-fw): |
|
||||||
|
| Vietnamese | `vi` | `vi` | :(far fa-square fa-fw): | :(far fa-check-square fa-fw): |
|
||||||
|
| Simplified Chinese | `zh-cn` | `zh-CN` | :(far fa-check-square fa-fw): | :(far fa-check-square fa-fw): |
|
||||||
|
|
||||||
|
### 4.2 Basic Configuration
|
||||||
|
|
||||||
|
After learning [how Hugo handle multilingual websites](https://gohugo.io/content-management/multilingual), define your languages in your [site configuration](#site-configuration).
|
||||||
|
|
||||||
|
For example with English, Chinese and French website:
|
||||||
|
|
||||||
|
```toml
|
||||||
|
# [en, zh-cn, fr, pl, ...] determines default content language
|
||||||
|
defaultContentLanguage = "en"
|
||||||
|
|
||||||
|
[languages]
|
||||||
|
[languages.en]
|
||||||
|
weight = 1
|
||||||
|
title = "My New Hugo Site"
|
||||||
|
languageCode = "en"
|
||||||
|
languageName = "English"
|
||||||
|
[[languages.en.menu.main]]
|
||||||
|
identifier = "posts"
|
||||||
|
pre = ""
|
||||||
|
post = ""
|
||||||
|
name = "Posts"
|
||||||
|
url = "/posts/"
|
||||||
|
title = ""
|
||||||
|
weight = 1
|
||||||
|
[[languages.en.menu.main]]
|
||||||
|
identifier = "tags"
|
||||||
|
pre = ""
|
||||||
|
post = ""
|
||||||
|
name = "Tags"
|
||||||
|
url = "/tags/"
|
||||||
|
title = ""
|
||||||
|
weight = 2
|
||||||
|
[[languages.en.menu.main]]
|
||||||
|
identifier = "categories"
|
||||||
|
pre = ""
|
||||||
|
post = ""
|
||||||
|
name = "Categories"
|
||||||
|
url = "/categories/"
|
||||||
|
title = ""
|
||||||
|
weight = 3
|
||||||
|
|
||||||
|
[languages.zh-cn]
|
||||||
|
weight = 2
|
||||||
|
title = "我的全新 Hugo 网站"
|
||||||
|
# language code, CN only here
|
||||||
|
languageCode = "zh-CN"
|
||||||
|
languageName = "简体中文"
|
||||||
|
# whether to include Chinese/Japanese/Korean
|
||||||
|
hasCJKLanguage = true
|
||||||
|
[[languages.zh-cn.menu.main]]
|
||||||
|
identifier = "posts"
|
||||||
|
pre = ""
|
||||||
|
post = ""
|
||||||
|
name = "文章"
|
||||||
|
url = "/posts/"
|
||||||
|
title = ""
|
||||||
|
weight = 1
|
||||||
|
[[languages.zh-cn.menu.main]]
|
||||||
|
identifier = "tags"
|
||||||
|
pre = ""
|
||||||
|
post = ""
|
||||||
|
name = "标签"
|
||||||
|
url = "/tags/"
|
||||||
|
title = ""
|
||||||
|
weight = 2
|
||||||
|
[[languages.zh-cn.menu.main]]
|
||||||
|
identifier = "categories"
|
||||||
|
pre = ""
|
||||||
|
post = ""
|
||||||
|
name = "分类"
|
||||||
|
url = "/categories/"
|
||||||
|
title = ""
|
||||||
|
weight = 3
|
||||||
|
|
||||||
|
[languages.fr]
|
||||||
|
weight = 3
|
||||||
|
title = "Mon nouveau site Hugo"
|
||||||
|
languageCode = "fr"
|
||||||
|
languageName = "Français"
|
||||||
|
[[languages.fr.menu.main]]
|
||||||
|
identifier = "posts"
|
||||||
|
pre = ""
|
||||||
|
post = ""
|
||||||
|
name = "Postes"
|
||||||
|
url = "/posts/"
|
||||||
|
title = ""
|
||||||
|
weight = 1
|
||||||
|
[[languages.fr.menu.main]]
|
||||||
|
identifier = "tags"
|
||||||
|
pre = ""
|
||||||
|
post = ""
|
||||||
|
name = "Balises"
|
||||||
|
url = "/tags/"
|
||||||
|
title = ""
|
||||||
|
weight = 2
|
||||||
|
[[languages.fr.menu.main]]
|
||||||
|
identifier = "categories"
|
||||||
|
name = "Catégories"
|
||||||
|
pre = ""
|
||||||
|
post = ""
|
||||||
|
url = "/categories/"
|
||||||
|
title = ""
|
||||||
|
weight = 3
|
||||||
|
```
|
||||||
|
|
||||||
|
Then, for each new page, append the language code to the file name.
|
||||||
|
|
||||||
|
Single file `my-page.md` is split in three files:
|
||||||
|
|
||||||
|
* in English: `my-page.en.md`
|
||||||
|
* in Chinese: `my-page.zh-cn.md`
|
||||||
|
* in French: `my-page.fr.md`
|
||||||
|
|
||||||
|
### 4.3 Overwrite Translation Strings
|
||||||
|
|
||||||
|
Translations strings are used for common default values used in the theme. Translations are available in [some languages](#language-compatibility), but you may use another language or want to override default values.
|
||||||
|
|
||||||
|
To override these values, create a new file in your local i18n folder `i18n/<languageCode>.toml` and inspire yourself from `themes/gokarna/i18n/en.toml`.
|
||||||
|
|
||||||
|
By the way, as these translations could be used by other people, please take the time to propose a translation by [:(fas fa-code-branch fa-fw): making a PR](https://github.com/526avijitgupta/gokarna/pulls) to the theme!
|
||||||
|
|
||||||
|
## 5 Search
|
||||||
|
|
||||||
|
Based on [Lunr.js](https://lunrjs.com/) or [algolia](https://www.algolia.com/), searching is supported in **gokarna** theme.
|
||||||
|
|
||||||
|
### 5.1 Output Configuration
|
||||||
|
|
||||||
|
In order to generate `index.json` for searching, add `JSON` output file type to the `home` of the `outputs` part in your [site configuration](#site-configuration).
|
||||||
|
|
||||||
|
```toml
|
||||||
|
[outputs]
|
||||||
|
home = ["HTML", "RSS", "JSON"]
|
||||||
|
```
|
||||||
420
exampleSite/content/posts/theme-documentation-basics.md
Normal file
420
exampleSite/content/posts/theme-documentation-basics.md
Normal file
@@ -0,0 +1,420 @@
|
|||||||
|
---
|
||||||
|
weight: 1
|
||||||
|
title: "Theme Documentation - Basics"
|
||||||
|
date: 2020-03-06T21:29:01+08:00
|
||||||
|
description: "Discover what the Hugo - gokarna theme is all about and the core-concepts behind it."
|
||||||
|
tags: ["installation", "configuration", "markdown"]
|
||||||
|
type: post
|
||||||
|
---
|
||||||
|
|
||||||
|
Discover what the Hugo - Gokarna theme is all about and the core-concepts behind it.
|
||||||
|
TODO: Similar intro as in README, opinionated, authors
|
||||||
|
|
||||||
|
## 1 Requirements
|
||||||
|
|
||||||
|
Thanks to the simplicity of Hugo, [Hugo](https://gohugo.io/) is the only dependency of this theme.
|
||||||
|
|
||||||
|
## 2 Installation
|
||||||
|
|
||||||
|
The following steps are here to help you initialize your new website. If you don’t know Hugo at all, we strongly suggest you learn more about it by following this [great documentation for beginners](https://gohugo.io/getting-started/quick-start/).
|
||||||
|
|
||||||
|
### 2.1 Create Your Project
|
||||||
|
|
||||||
|
Hugo provides a `new` command to create a new website:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
hugo new site my_website
|
||||||
|
cd my_website
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2.2 Install the Theme
|
||||||
|
|
||||||
|
The theme’s repository is: [https://github.com/526avijitgupta/gokarna](https://github.com/526avijitgupta/gokarna).
|
||||||
|
|
||||||
|
You can download the [latest release :books: .zip file](https://github.com/526avijitgupta/gokarna/releases) of the theme and extract it in the `themes` directory.
|
||||||
|
|
||||||
|
Alternatively, clone this repository to the `themes` directory:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git clone https://github.com/526avijitgupta/gokarna.git themes/gokarna
|
||||||
|
```
|
||||||
|
|
||||||
|
Or, create an empty git repository and make this repository a submodule of your site directory:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git init
|
||||||
|
git submodule add https://github.com/526avijitgupta/gokarna.git themes/gokarna
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2.3 Basic Configuration {#basic-configuration}
|
||||||
|
|
||||||
|
The following is a basic configuration for the gokarna theme:
|
||||||
|
|
||||||
|
```toml
|
||||||
|
baseURL = "http://example.org/"
|
||||||
|
defaultContentLanguage = "en"
|
||||||
|
languageCode = "en"
|
||||||
|
|
||||||
|
title = "My New Hugo Site"
|
||||||
|
|
||||||
|
theme = "gokarna"
|
||||||
|
|
||||||
|
[params]
|
||||||
|
# URL for the avatar on homepage
|
||||||
|
avatarURL = ""
|
||||||
|
|
||||||
|
# Description to display on homepage
|
||||||
|
description = "Sky above, sand below & peace within"
|
||||||
|
|
||||||
|
# You can use this to inject any HTML in the <head> tag.
|
||||||
|
# Ideal usecase for this is to import custom js/css or add your analytics snippet
|
||||||
|
customHTML = ""
|
||||||
|
|
||||||
|
# If you want to display posts on the homepage, the options are
|
||||||
|
# "popular" (order posts by weight), "recent" (order posts by date)
|
||||||
|
# or "" (do not display, default option)
|
||||||
|
showPostsOnHomePage = ""
|
||||||
|
|
||||||
|
# Footer text
|
||||||
|
footer = "The Marauders"
|
||||||
|
|
||||||
|
[menu]
|
||||||
|
[[menu.main]]
|
||||||
|
# Unique identifer for a menu item
|
||||||
|
identifier = "posts"
|
||||||
|
|
||||||
|
url = "/posts/"
|
||||||
|
|
||||||
|
# You can add extra information before the name (HTML format is supported), such as icons
|
||||||
|
pre = ""
|
||||||
|
|
||||||
|
# You can add extra information after the name (HTML format is supported), such as icons
|
||||||
|
post = ""
|
||||||
|
|
||||||
|
# Display name
|
||||||
|
name = "Posts"
|
||||||
|
|
||||||
|
# Weights are used to determine the ordering
|
||||||
|
weight = 1
|
||||||
|
|
||||||
|
[[menu.main]]
|
||||||
|
identifier = "tags"
|
||||||
|
name = "Tags"
|
||||||
|
url = "/tags/"
|
||||||
|
weight = 2
|
||||||
|
|
||||||
|
[[menu.main]]
|
||||||
|
identifier = "github"
|
||||||
|
url = "https://github.com"
|
||||||
|
weight = 3
|
||||||
|
|
||||||
|
# We use feather-icons
|
||||||
|
pre = "<span data-feather='github'></span>"
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
|
### 2.4 Create Your First Post
|
||||||
|
|
||||||
|
Here is the way to create your first post:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
hugo new posts/first_post.md
|
||||||
|
```
|
||||||
|
|
||||||
|
Feel free to edit the post file by adding some sample content and replacing the title value in the beginning of the file.
|
||||||
|
|
||||||
|
For posts you need to add `type: "post"` in the markdown metadata. We currently support 2 types of content:
|
||||||
|
|
||||||
|
1. Post (`type: "post"`): A normal blog-post with tags, date, & content.
|
||||||
|
2. Singles (`type: "singles"`): A standalone content page that will just render the markdown you wrote. You can use it to write custom pages which should not be a part of posts. Like, showing your projects portfolio. You can read in detail about this on the [Theme Documentation - Advanced](/link-TODO) page.
|
||||||
|
|
||||||
|
By default all posts and pages are created as a draft. If you want to render these pages, remove the property `draft: true` from the metadata, set the property `draft: false` or add `-D`/`--buildDrafts` parameter to `hugo` command.
|
||||||
|
|
||||||
|
### 2.5 Launching the Website Locally
|
||||||
|
|
||||||
|
Launch by using the following command:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
hugo serve
|
||||||
|
```
|
||||||
|
|
||||||
|
Go to `http://localhost:1313`.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
When you run `hugo serve`, when the contents of the files change, the page automatically refreshes with the changes.
|
||||||
|
|
||||||
|
Since the theme use `.Scratch` in Hugo to implement some features,
|
||||||
|
it is highly recommended that you add `--disableFastRender` parameter to `hugo server` command for the live preview of the page you are editing.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
hugo serve --disableFastRender
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2.6 Build the Website
|
||||||
|
|
||||||
|
When your site is ready to deploy, run the following command:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
hugo
|
||||||
|
```
|
||||||
|
|
||||||
|
A `public` folder will be generated, containing all static content and assets for your website. It can now be deployed on any web server.
|
||||||
|
|
||||||
|
The website can be automatically published and hosted with [Netlify](https://www.netlify.com/) (Read more about [Automated HUGO deployments with Netlify](https://www.netlify.com/blog/2015/07/30/hosting-hugo-on-netlifyinsanely-fast-deploys/)).
|
||||||
|
Alternatively, you can use [AWS Amplify](https://gohugo.io/hosting-and-deployment/hosting-on-aws-amplify/), [Github pages](https://gohugo.io/hosting-and-deployment/hosting-on-github/), [Render](https://gohugo.io/hosting-and-deployment/hosting-on-render/) and more...
|
||||||
|
|
||||||
|
## 3 Configuration
|
||||||
|
|
||||||
|
### 3.1 Site Configuration {#site-configuration}
|
||||||
|
|
||||||
|
In addition to [Hugo global configuration](https://gohugo.io/overview/configuration/) and [menu configuration](#basic-configuration), **gokarna** lets you define the following parameters in your site configuration (here is a `config.toml`, whose values are default).
|
||||||
|
|
||||||
|
Please open the code block below to view the complete sample configuration :(far fa-hand-point-down fa-fw)::
|
||||||
|
|
||||||
|
```toml
|
||||||
|
[params]
|
||||||
|
version = "1.0.X"
|
||||||
|
# site description
|
||||||
|
description = "This is My New Hugo Site"
|
||||||
|
# site keywords
|
||||||
|
keywords = ["Theme", "Hugo"]
|
||||||
|
# site default theme ("light", "dark", "auto")
|
||||||
|
defaultTheme = "auto"
|
||||||
|
# public git repo url only then enableGitInfo is true
|
||||||
|
gitRepo = ""
|
||||||
|
# ("sha256", "sha384", "sha512", "md5")
|
||||||
|
fingerprint = ""
|
||||||
|
dateFormat = "2006-01-02"
|
||||||
|
# website images for Open Graph and Twitter Cards
|
||||||
|
images = ["/logo.png"]
|
||||||
|
SourceMap = true
|
||||||
|
|
||||||
|
[params.pwa]
|
||||||
|
# whether to enable PWA support
|
||||||
|
enable = true
|
||||||
|
# service-worker version
|
||||||
|
version = "1.0.1"
|
||||||
|
|
||||||
|
[params.app]
|
||||||
|
# optional site title override for the app when added to an iOS home screen or Android launcher
|
||||||
|
title = "gokarna"
|
||||||
|
# whether to omit favicon resource links
|
||||||
|
noFavicon = false
|
||||||
|
# modern SVG favicon to use in place of older style .png and .ico files
|
||||||
|
svgFavicon = ""
|
||||||
|
# Android browser theme color
|
||||||
|
themeColor = "#ffffff"
|
||||||
|
# Safari mask icon color
|
||||||
|
iconColor = "#5bbad5"
|
||||||
|
# Windows v8-10 tile color
|
||||||
|
tileColor = "#da532c"
|
||||||
|
|
||||||
|
[params.search]
|
||||||
|
enable = true
|
||||||
|
# type of search engine ("lunr", "algolia")
|
||||||
|
|
||||||
|
# Header config
|
||||||
|
[params.header]
|
||||||
|
# desktop header mode ("fixed", "normal", "auto")
|
||||||
|
desktopMode = "fixed"
|
||||||
|
# mobile header mode ("fixed", "normal", "auto")
|
||||||
|
mobileMode = "auto"
|
||||||
|
[params.header.title]
|
||||||
|
# URL of the LOGO
|
||||||
|
logo = ""
|
||||||
|
rss = true
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3.2 Favicons, Browserconfig, Manifest
|
||||||
|
|
||||||
|
It is recommended to put your own favicons:
|
||||||
|
|
||||||
|
* apple-touch-icon.png (180x180)
|
||||||
|
* favicon-32x32.png (32x32)
|
||||||
|
* favicon-16x16.png (16x16)
|
||||||
|
* mstile-150x150.png (150x150)
|
||||||
|
* android-chrome-192x192.png (192x192)
|
||||||
|
* android-chrome-512x512.png (512x512)
|
||||||
|
|
||||||
|
into `/static`. They’re easily created via [https://realfavicongenerator.net/](https://realfavicongenerator.net/).
|
||||||
|
|
||||||
|
Customize `browserconfig.xml` and `site.webmanifest` to set theme-color and background-color.
|
||||||
|
|
||||||
|
### 3.3 Style Customization
|
||||||
|
|
||||||
|
Hugo **extended** version is necessary for the style customization.
|
||||||
|
|
||||||
|
**gokarna** theme has been built to be as configurable as possible by defining custom `.scss` style files.
|
||||||
|
|
||||||
|
The directory including the custom `.scss` style files is `assets/css` relative to **your project root directory**.
|
||||||
|
|
||||||
|
In `assets/css/_override.scss`, you can override the variables in `themes/gokarna/assets/css/_variables.scss` to customize the style.
|
||||||
|
|
||||||
|
Here is a example:
|
||||||
|
|
||||||
|
```scss
|
||||||
|
@import url('https://fonts.googleapis.com/css?family=Fira+Mono:400,700&display=swap&subset=latin-ext');
|
||||||
|
$code-font-family: Fira Mono, Source Code Pro, Menlo, Consolas, Monaco, monospace;
|
||||||
|
```
|
||||||
|
|
||||||
|
In `assets/css/_custom.scss`, you can add some css style code to customize the style.
|
||||||
|
|
||||||
|
## 4 Multilingual and i18n
|
||||||
|
|
||||||
|
**gokarna** theme is fully compatible with Hugo multilingual mode, which provides in-browser language switching.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
### 4.1 Compatibility {#language-compatibility}
|
||||||
|
|
||||||
|
|
||||||
|
| Language | Hugo Code | HTML `lang` Attribute | Theme Docs | Lunr.js Support |
|
||||||
|
|:-------------------- |:---------:|:---------------------:|:-----------------------------:|:-----------------------------:|
|
||||||
|
| German | `de` | `de` | :(far fa-square fa-fw): | :(far fa-check-square fa-fw): |
|
||||||
|
| English | `en` | `en` | :(far fa-check-square fa-fw): | :(far fa-check-square fa-fw): |
|
||||||
|
| Spanish | `es` | `es` | :(far fa-square fa-fw): | :(far fa-check-square fa-fw): |
|
||||||
|
| French | `fr` | `fr` | :(far fa-square fa-fw): | :(far fa-check-square fa-fw): |
|
||||||
|
| Indonesian | `id` | `id` | :(far fa-square fa-fw): | :(far fa-check-square fa-fw): |
|
||||||
|
| Italian | `it` | `it` | :(far fa-square fa-fw): | :(far fa-check-square fa-fw): |
|
||||||
|
| Polish | `pl` | `pl` | :(far fa-square fa-fw): | :(far fa-square fa-fw): |
|
||||||
|
| Brazilian Portuguese | `pt-br` | `pt-BR` | :(far fa-square fa-fw): | :(far fa-check-square fa-fw): |
|
||||||
|
| Romanian | `ro` | `ro` | :(far fa-square fa-fw): | :(far fa-check-square fa-fw): |
|
||||||
|
| Russian | `ru` | `ru` | :(far fa-square fa-fw): | :(far fa-check-square fa-fw): |
|
||||||
|
| Serbian | `sr` | `sr` | :(far fa-square fa-fw): | :(far fa-square fa-fw): |
|
||||||
|
| Vietnamese | `vi` | `vi` | :(far fa-square fa-fw): | :(far fa-check-square fa-fw): |
|
||||||
|
| Simplified Chinese | `zh-cn` | `zh-CN` | :(far fa-check-square fa-fw): | :(far fa-check-square fa-fw): |
|
||||||
|
|
||||||
|
### 4.2 Basic Configuration
|
||||||
|
|
||||||
|
After learning [how Hugo handle multilingual websites](https://gohugo.io/content-management/multilingual), define your languages in your [site configuration](#site-configuration).
|
||||||
|
|
||||||
|
For example with English, Chinese and French website:
|
||||||
|
|
||||||
|
```toml
|
||||||
|
# [en, zh-cn, fr, pl, ...] determines default content language
|
||||||
|
defaultContentLanguage = "en"
|
||||||
|
|
||||||
|
[languages]
|
||||||
|
[languages.en]
|
||||||
|
weight = 1
|
||||||
|
title = "My New Hugo Site"
|
||||||
|
languageCode = "en"
|
||||||
|
languageName = "English"
|
||||||
|
[[languages.en.menu.main]]
|
||||||
|
identifier = "posts"
|
||||||
|
pre = ""
|
||||||
|
post = ""
|
||||||
|
name = "Posts"
|
||||||
|
url = "/posts/"
|
||||||
|
title = ""
|
||||||
|
weight = 1
|
||||||
|
[[languages.en.menu.main]]
|
||||||
|
identifier = "tags"
|
||||||
|
pre = ""
|
||||||
|
post = ""
|
||||||
|
name = "Tags"
|
||||||
|
url = "/tags/"
|
||||||
|
title = ""
|
||||||
|
weight = 2
|
||||||
|
[[languages.en.menu.main]]
|
||||||
|
identifier = "categories"
|
||||||
|
pre = ""
|
||||||
|
post = ""
|
||||||
|
name = "Categories"
|
||||||
|
url = "/categories/"
|
||||||
|
title = ""
|
||||||
|
weight = 3
|
||||||
|
|
||||||
|
[languages.zh-cn]
|
||||||
|
weight = 2
|
||||||
|
title = "我的全新 Hugo 网站"
|
||||||
|
# language code, CN only here
|
||||||
|
languageCode = "zh-CN"
|
||||||
|
languageName = "简体中文"
|
||||||
|
# whether to include Chinese/Japanese/Korean
|
||||||
|
hasCJKLanguage = true
|
||||||
|
[[languages.zh-cn.menu.main]]
|
||||||
|
identifier = "posts"
|
||||||
|
pre = ""
|
||||||
|
post = ""
|
||||||
|
name = "文章"
|
||||||
|
url = "/posts/"
|
||||||
|
title = ""
|
||||||
|
weight = 1
|
||||||
|
[[languages.zh-cn.menu.main]]
|
||||||
|
identifier = "tags"
|
||||||
|
pre = ""
|
||||||
|
post = ""
|
||||||
|
name = "标签"
|
||||||
|
url = "/tags/"
|
||||||
|
title = ""
|
||||||
|
weight = 2
|
||||||
|
[[languages.zh-cn.menu.main]]
|
||||||
|
identifier = "categories"
|
||||||
|
pre = ""
|
||||||
|
post = ""
|
||||||
|
name = "分类"
|
||||||
|
url = "/categories/"
|
||||||
|
title = ""
|
||||||
|
weight = 3
|
||||||
|
|
||||||
|
[languages.fr]
|
||||||
|
weight = 3
|
||||||
|
title = "Mon nouveau site Hugo"
|
||||||
|
languageCode = "fr"
|
||||||
|
languageName = "Français"
|
||||||
|
[[languages.fr.menu.main]]
|
||||||
|
identifier = "posts"
|
||||||
|
pre = ""
|
||||||
|
post = ""
|
||||||
|
name = "Postes"
|
||||||
|
url = "/posts/"
|
||||||
|
title = ""
|
||||||
|
weight = 1
|
||||||
|
[[languages.fr.menu.main]]
|
||||||
|
identifier = "tags"
|
||||||
|
pre = ""
|
||||||
|
post = ""
|
||||||
|
name = "Balises"
|
||||||
|
url = "/tags/"
|
||||||
|
title = ""
|
||||||
|
weight = 2
|
||||||
|
[[languages.fr.menu.main]]
|
||||||
|
identifier = "categories"
|
||||||
|
name = "Catégories"
|
||||||
|
pre = ""
|
||||||
|
post = ""
|
||||||
|
url = "/categories/"
|
||||||
|
title = ""
|
||||||
|
weight = 3
|
||||||
|
```
|
||||||
|
|
||||||
|
Then, for each new page, append the language code to the file name.
|
||||||
|
|
||||||
|
Single file `my-page.md` is split in three files:
|
||||||
|
|
||||||
|
* in English: `my-page.en.md`
|
||||||
|
* in Chinese: `my-page.zh-cn.md`
|
||||||
|
* in French: `my-page.fr.md`
|
||||||
|
|
||||||
|
### 4.3 Overwrite Translation Strings
|
||||||
|
|
||||||
|
Translations strings are used for common default values used in the theme. Translations are available in [some languages](#language-compatibility), but you may use another language or want to override default values.
|
||||||
|
|
||||||
|
To override these values, create a new file in your local i18n folder `i18n/<languageCode>.toml` and inspire yourself from `themes/gokarna/i18n/en.toml`.
|
||||||
|
|
||||||
|
By the way, as these translations could be used by other people, please take the time to propose a translation by [:(fas fa-code-branch fa-fw): making a PR](https://github.com/526avijitgupta/gokarna/pulls) to the theme!
|
||||||
|
|
||||||
|
## 5 Search
|
||||||
|
|
||||||
|
Based on [Lunr.js](https://lunrjs.com/) or [algolia](https://www.algolia.com/), searching is supported in **gokarna** theme.
|
||||||
|
|
||||||
|
### 5.1 Output Configuration
|
||||||
|
|
||||||
|
In order to generate `index.json` for searching, add `JSON` output file type to the `home` of the `outputs` part in your [site configuration](#site-configuration).
|
||||||
|
|
||||||
|
```toml
|
||||||
|
[outputs]
|
||||||
|
home = ["HTML", "RSS", "JSON"]
|
||||||
|
```
|
||||||
@@ -3,11 +3,11 @@
|
|||||||
|
|
||||||
<h2 class="list-title">Tags</h2>
|
<h2 class="list-title">Tags</h2>
|
||||||
<ul class="post-tags">
|
<ul class="post-tags">
|
||||||
{{ range $key, $value := .Data.Terms.ByCount }}
|
{{ range $.Site.Taxonomies.tags.ByCount }}
|
||||||
<li class="post-tag">
|
<li class="post-tag">
|
||||||
<a href="/tags/{{ $value.Name | urlize }}/">
|
<a href="/tags/{{ .Name | urlize }}/">
|
||||||
<div class="tag-name">{{ $value.Name }}</div>
|
<div class="tag-name">{{ .Name }}</div>
|
||||||
<div class="tag-posts-count">{{ $value.Count }}</div>
|
<div class="tag-posts-count">{{ .Count }}</div>
|
||||||
</a>
|
</a>
|
||||||
</li>
|
</li>
|
||||||
{{ end }}
|
{{ end }}
|
||||||
|
|||||||
Reference in New Issue
Block a user