doc: documentation is now in the same repository as the code
Demo site will be generated in subfolder /demo
This commit is contained in:
Jimmy Cai
@@ -0,0 +1,49 @@
|
||||
# Article
|
||||
|
||||
Configuration for the article page.
|
||||
|
||||
Fields under `[Params.Article]`.
|
||||
|
||||
## math
|
||||
|
||||
- Type: `bool`
|
||||
|
||||
Enable math support by [KaTeX](https://katex.org/). Can be overridden by front matter field `toc`.
|
||||
|
||||
## toc
|
||||
|
||||
- Type: `bool`
|
||||
|
||||
Enable by default table of contents. Can be overridden by front matter field `toc`.
|
||||
|
||||
::: warning
|
||||
You will still need to add [`toc` widget](widgets.md#toc) to the sidebar to display the table of contents.
|
||||
:::
|
||||
|
||||
|
||||
## readingTime
|
||||
|
||||
- Type: `bool`
|
||||
- Default: `true`
|
||||
|
||||
Display an estimated reading time for the article.
|
||||
|
||||
## license
|
||||
|
||||
- Type: `map[string]:(bool|string)`
|
||||
|
||||
Configurations related with license.
|
||||
|
||||
### license.enabled
|
||||
|
||||
- Type: `bool`
|
||||
- Default: `false`
|
||||
|
||||
Display license information under the article.
|
||||
|
||||
### license.default
|
||||
|
||||
- Type: `string`
|
||||
- Default: `Licensed under CC BY-NC-SA 4.0`
|
||||
|
||||
Default license text displayed under the article. Can be overridden by front matter field `license`.
|
||||
@@ -0,0 +1,22 @@
|
||||
# Color Scheme
|
||||
|
||||
Light and dark color schemes are available in this theme.
|
||||
|
||||
|
||||
## toggle
|
||||
|
||||
- Type: `bool`
|
||||
- Default: `true`
|
||||
|
||||
Display the color scheme toggle button.
|
||||
|
||||
If it's set to `false`, the color scheme will be determined by the `default` option.
|
||||
|
||||
## default
|
||||
|
||||
- Type: `string (light|dark|auto)`
|
||||
- Default: `auto`
|
||||
|
||||
The default color scheme, used when the `toggle` option is set to `false` or when the user visits the site for the first time.
|
||||
|
||||
When set to `auto`, the color scheme will be determined by the user's system preference (`prefers-color-scheme` media query).
|
||||
@@ -0,0 +1,56 @@
|
||||
# Comments
|
||||
|
||||
Comment system is a very important part of a blog. It allows readers to express their opinions and thoughts about the post. It also allows the author to interact with the readers.
|
||||
|
||||
Stack currently supports the following comment systems:
|
||||
|
||||
- [Cactus](https://cactus.chat/)
|
||||
- [Cusdis](https://cusdis.com/)
|
||||
- [Disqus](https://disqus.com/)
|
||||
- [DisqusJS](https://github.com/SukkaW/DisqusJS)
|
||||
- [Giscus](https://giscus.app/)
|
||||
- [Gitalk](https://github.com/gitalk/gitalk)
|
||||
- [Remark42](https://remark42.com/)
|
||||
- [Twikoo](https://twikoo.js.org/)
|
||||
- [utterances](https://utteranc.es/)
|
||||
- [Vssue](https://vssue.js.org/)
|
||||
- [Waline](https://waline.js.org/)
|
||||
|
||||
Each comment system has its own configuration options placed under `[Params.Comments.COMMENT_SYSTEM]` section.
|
||||
|
||||
For example, utterances's configuration options are placed under `[Params.Comments.utterances]` section.
|
||||
|
||||
::: tip
|
||||
A full list of supported configuration options can be found in [here](https://github.com/CaiJimmy/hugo-theme-stack/blob/master/config.yaml#L38)
|
||||
|
||||
For more information about the meaning of each configuration option, please refer to the documentation of the comment system.
|
||||
:::
|
||||
|
||||
::: warning
|
||||
In case of Disqus, the only configuration option is `disqusShortname`, which is not available at `[Params.Comments.disqus]` section. Instead, it is placed at root section of configuration file.
|
||||
:::
|
||||
|
||||
## enabled
|
||||
|
||||
- Type: `bool`
|
||||
- Default: `false`
|
||||
|
||||
Enable / disable comment system.
|
||||
|
||||
## provider
|
||||
|
||||
- Type: `string`
|
||||
|
||||
Comment system provider. Possible values are:
|
||||
|
||||
- `cactus`
|
||||
- `cusdis`
|
||||
- `disqus`
|
||||
- `disqusjs`
|
||||
- `giscus`
|
||||
- `gitalk`
|
||||
- `remark42`
|
||||
- `twikoo`
|
||||
- `utterances`
|
||||
- `vssue`
|
||||
- `waline`
|
||||
@@ -0,0 +1,19 @@
|
||||
# Date format
|
||||
|
||||
Fields under `[Params.DateFormat]`.
|
||||
|
||||
Date format setting. Notice that Go's date format is slightly different than other programming language, take a look at official documentation: [dateFormat](https://gohugo.io/functions/dateformat/)
|
||||
|
||||
## published
|
||||
|
||||
- Type: `string`
|
||||
- Default: `Jan 02, 2006`
|
||||
|
||||
Page's publish date format.
|
||||
|
||||
## lastUpdated
|
||||
|
||||
- Type: `string`
|
||||
- Default: `Jan 02, 2006 15:04 MST`
|
||||
|
||||
Page's last updated date format
|
||||
@@ -0,0 +1,29 @@
|
||||
# Default Image
|
||||
|
||||
The default image is the image that will be used on a page if no featured image is set. This is useful for Open Graph and Twitter cards.
|
||||
|
||||
## opengraph
|
||||
|
||||
The default image for Open Graph and Twitter.
|
||||
|
||||
### opengraph.enabled
|
||||
|
||||
- Type: `bool`
|
||||
- Default: `false`
|
||||
|
||||
Enable the default image for Open Graph and Twitter.
|
||||
|
||||
### opengraph.src
|
||||
|
||||
- Type: `string`
|
||||
|
||||
Path to the image file.
|
||||
|
||||
### opengraph.local
|
||||
|
||||
- Type: `bool`
|
||||
- Default: `false`
|
||||
|
||||
If `true`, the image is a local file, and must be placed under `assets` folder. Otherwise, it is a remote URL.
|
||||
|
||||
For example, if `src` is set to `img/default.jpg`, the image file must be placed under `assets/img/default.jpg`.
|
||||
@@ -0,0 +1,17 @@
|
||||
# Footer
|
||||
|
||||
The footer is the last section of the page. It is usually used to display the copyright information.
|
||||
|
||||
Fields under `[Params.Footer]`.
|
||||
|
||||
## since
|
||||
|
||||
- Type: `int`
|
||||
|
||||
The year when the site is created.
|
||||
|
||||
## customText
|
||||
|
||||
- Type: `string`
|
||||
|
||||
Custom text displayed in the footer. HTML is supported.
|
||||
@@ -0,0 +1,38 @@
|
||||
# Custom Header / Footer
|
||||
|
||||
There are two empty files reserved for custom HTML in the theme, useful for adding custom scripts or stylesheets:
|
||||
|
||||
* `layouts/partials/head/custom.html`
|
||||
* `layouts/partials/footer/custom.html`
|
||||
|
||||
To overwrite them:
|
||||
|
||||
1. Create `layout/partials/footer/custom.html` under your Hugo site folder
|
||||
2. Insert custom code in that file.
|
||||
|
||||
## Example: Custom font family for article content
|
||||
|
||||
By default, this theme uses [Lato](https://fonts.google.com/specimen/Lato) for article content. This example shows how to use another font instead. For example, let's change article font family to [Merriweather](https://fonts.google.com/specimen/Merriweather).
|
||||
|
||||
Create `layouts/partials/head/custom.html` under your Hugo site folder, with following code:
|
||||
|
||||
```html
|
||||
<style>
|
||||
/// Overwrite CSS variable
|
||||
:root {
|
||||
--article-font-family: "Merriweather", var(--base-font-family);
|
||||
}
|
||||
</style>
|
||||
|
||||
<script>
|
||||
(function () {
|
||||
const customFont = document.createElement('link');
|
||||
customFont.href = "https://fonts.googleapis.com/css2?family=Merriweather:wght@400;700&display=swap";
|
||||
|
||||
customFont.type = "text/css";
|
||||
customFont.rel = "stylesheet";
|
||||
|
||||
document.head.appendChild(customFont);
|
||||
}());
|
||||
</script>
|
||||
```
|
||||
@@ -0,0 +1,38 @@
|
||||
# i18n
|
||||
|
||||
Hugo has built-in support for multilingual sites. You can find more information about it in the [official documentation](https://gohugo.io/content-management/multilingual/).
|
||||
|
||||
Translation files are placed in the `i18n` directory. The file name is the language code. For example, the `en.yaml` file is the translation file for English.
|
||||
|
||||
In order to use a language, set `DefaultContentLanguage` to the language code in the configuration file. For example, if you want to use English, set `DefaultContentLanguage` to `en`.
|
||||
|
||||
Currently, the theme supports the following languages:
|
||||
|
||||
* `ar`: Arabic
|
||||
* `bn`: Bengali
|
||||
* `ca`: Catalan
|
||||
* `de`: German
|
||||
* `el`: Greek
|
||||
* `en`: English
|
||||
* `es`: Spanish
|
||||
* `fa`: Persian
|
||||
* `fr`: French
|
||||
* `hu`: Hungarian
|
||||
* `id`: Indonesian
|
||||
* `it`: Italian
|
||||
* `ja`: Japanese
|
||||
* `ko`: Korean
|
||||
* `nl`: Dutch
|
||||
* `pl`: Polish
|
||||
* `pt-br`: Portuguese
|
||||
* `ru`: Russian
|
||||
* `th`: Thai
|
||||
* `tr`: Turkish
|
||||
* `uk`: Ukrainian
|
||||
* `zh-cn`: Chinese (Simplified)
|
||||
* `zh-hk`: Chinese (Traditional) (Hong Kong)
|
||||
* `zh-tw`: Chinese (Traditional) (Taiwan)
|
||||
|
||||
::: tip
|
||||
PRs for more language support are welcome 😉.
|
||||
:::
|
||||
@@ -0,0 +1,27 @@
|
||||
# Image Processing
|
||||
|
||||
This theme uses Hugo's built-in image processing features to resize and optimize local images (included using page bundle feature). This is done automatically when you build your site.
|
||||
|
||||
When there are many images in your site, this can slow down the build process. You can choose to disable this feature here.
|
||||
|
||||
## cover
|
||||
|
||||
- Type: `map[string]bool`
|
||||
|
||||
### cover.enabled
|
||||
|
||||
- Type: `bool`
|
||||
- Default: `true`
|
||||
|
||||
Enable image processing for cover (featured) images.
|
||||
|
||||
## content
|
||||
|
||||
- Type: `map[string]bool`
|
||||
|
||||
### content.enabled
|
||||
|
||||
- Type: `bool`
|
||||
- Default: `true`
|
||||
|
||||
Enable image processing for images in content.
|
||||
@@ -0,0 +1,13 @@
|
||||
# Introduction
|
||||
|
||||
Hugo acepts `TOML`, `YAML` and `JSON` as configuration formats. This theme currently uses `YAML` and `TOML` as configuration formats.
|
||||
|
||||
::: info
|
||||
In the foreseeable future, this theme will migrate all its configurations to `TOML` format.
|
||||
:::
|
||||
|
||||
If you are using `hugo-theme-stack-starter` template, you can find the configuration file under `config/_default/` folder, separated in different major sections to make it easier to find the configuration you want to modify.
|
||||
|
||||
A full list of available configurations can be found in `config.yaml` file located in the root directory of this theme. (If it is not there, please send an issue to let me know.)
|
||||
|
||||
There are plenty tools that converts `YAML` to `TOML` and vice versa. You can use them to convert the configuration file to the format you prefer.
|
||||
@@ -0,0 +1,67 @@
|
||||
# Custom Menu
|
||||
|
||||
There are two menus in the theme: the main menu (`menu.main`) and the social menu (`menu.social`, icon only). They can be configured in a similar way.
|
||||
|
||||
## First Method (Recommended)
|
||||
If the menu item you'd like to add is a page, add `menu` field to its Front Matter:
|
||||
|
||||
```yaml
|
||||
menu:
|
||||
main:
|
||||
name: title (optional)
|
||||
weight: -90
|
||||
params:
|
||||
icon: icon-name
|
||||
```
|
||||
|
||||
## Second Method
|
||||
|
||||
::: warning
|
||||
This method is not recommended, because the theme can not detect if the current page is in the menu, and the menu item will not be highlighted.
|
||||
:::
|
||||
|
||||
If the menu item you'd like to add is not a page, you can add it to the menu section in the config file:
|
||||
|
||||
Example in TOML:
|
||||
|
||||
```toml
|
||||
[menu]
|
||||
[[menu.main]]
|
||||
name = "Home"
|
||||
url = "/"
|
||||
weight = 10
|
||||
identifier = "home"
|
||||
[menu.main.params]
|
||||
icon = "home"
|
||||
newTab = true
|
||||
```
|
||||
|
||||
Or in YAML:
|
||||
|
||||
```yaml
|
||||
menu:
|
||||
main:
|
||||
- identifier: home
|
||||
name: Home
|
||||
url: /
|
||||
weight: -100
|
||||
params:
|
||||
icon: home
|
||||
newTab: true
|
||||
```
|
||||
|
||||
* `identifier`: Item ID
|
||||
* `name`: Display text
|
||||
* `url`: Link
|
||||
* `weight`: Priority of the item, lower value means higher priority.
|
||||
* `params`:
|
||||
* `icon`: Specify which SVG icon should be used
|
||||
* `newTab`: Open this link in new tab
|
||||
|
||||
If `params.icon` is set to `archive`, theme will look for `archive.svg` under `assets/icons` folder.
|
||||
|
||||
## Add custom icon
|
||||
|
||||
This theme comes with some SVG icons from [Tabler Icons](https://tablericons.com). You can find them under theme folder `assets/icons`.
|
||||
|
||||
To include more icons, just download them from website above, and place them under `assets/icons` folder of your Hugo site.
|
||||
@@ -0,0 +1,26 @@
|
||||
# Open Graph
|
||||
|
||||
The Open Graph protocol enables any web page to become a rich object in a social graph.
|
||||
|
||||
For more information, see [Open Graph protocol](http://ogp.me/).
|
||||
|
||||
Fields are under `[Params.opengraph]` section.
|
||||
|
||||
## twitter
|
||||
|
||||
- type: `map[string]string`
|
||||
|
||||
Available fields:
|
||||
|
||||
### site
|
||||
|
||||
- type: `string`
|
||||
|
||||
The Twitter account name of the site (without `@`).
|
||||
|
||||
### card
|
||||
|
||||
- type: `string`
|
||||
|
||||
[Twitter card type](https://developer.twitter.com/en/docs/twitter-for-websites/cards/overview/abouts-cards). Available values: `summary`, `summary_large_image`.
|
||||
|
||||
@@ -0,0 +1,51 @@
|
||||
# Sidebar
|
||||
|
||||
Settings related with left-side sidebar.
|
||||
|
||||
Fields are under `[Params.Sidebar]` section.
|
||||
|
||||
## compact
|
||||
|
||||
- Type: `bool`
|
||||
- Default: `false`
|
||||
|
||||
Enable compact version of sidebar.
|
||||
|
||||
## emoji
|
||||
|
||||
- Type: `string`
|
||||
|
||||
Emoji displayed above the avatar.
|
||||
|
||||
## subtitle
|
||||
|
||||
- Type: `string`
|
||||
|
||||
Subtitle displayed below the site title.
|
||||
|
||||
## avatar
|
||||
|
||||
- Type: `map[string]:(bool|string)`
|
||||
|
||||
Configurations related with avatar.
|
||||
|
||||
### avatar.enable
|
||||
|
||||
- Type: `bool`
|
||||
- Default: `true`
|
||||
|
||||
Enable avatar.
|
||||
|
||||
### avatar.src
|
||||
|
||||
- Type: `string`
|
||||
- Default: `img/avatar.png`
|
||||
|
||||
Path to avatar image.
|
||||
|
||||
### avatar.local
|
||||
|
||||
- Type: `bool`
|
||||
- Default: `true`
|
||||
|
||||
If `true`, the avatar image should be placed at `assets/${avatar.src}`, this allows theme to automatically resize the image.
|
||||
@@ -0,0 +1,40 @@
|
||||
# Site-wide settings
|
||||
|
||||
Fields under `[Params]`:
|
||||
|
||||
## description
|
||||
|
||||
- Type: `string`
|
||||
|
||||
Site description. By default, it falls back to `.Params.Sidebar.Subtitle`.
|
||||
|
||||
## mainSections
|
||||
|
||||
- Type: `[string]`
|
||||
- Default: `["post"]`
|
||||
|
||||
Pages places under this/those sections will be shown on homepage and archive page.
|
||||
|
||||
For more information, take a look at Hugo's documentation on [Content Sections](https://gohugo.io/content-management/sections/).
|
||||
|
||||
## featuredImageField
|
||||
|
||||
- Type: `string`
|
||||
- Default: `image`
|
||||
|
||||
Front Matter **field** used to get the featured image of a page.
|
||||
|
||||
## rssFullContent
|
||||
|
||||
- Type: `bool`
|
||||
- Default: `true`
|
||||
|
||||
Output page's full content in RSS.
|
||||
|
||||
## favicon
|
||||
|
||||
- Type: `string`
|
||||
|
||||
Site favicon path.
|
||||
|
||||
For example, if you want to use the favicon in `static/favicon.ico`, set `favicon` to `/favicon.ico`.
|
||||
@@ -0,0 +1,46 @@
|
||||
# Widgets
|
||||
|
||||
Widgets are placed at right sidebar of the blog. They are used to display some information such as categories, tags, etc.
|
||||
|
||||
You can configure which widgets to display and their order in the homepage and post page.
|
||||
|
||||
`widget.homepage` and `widget.page` are arrays of maps. Each map contains two keys: `type` and `params`. `type` is the name of the widget. `params` is the configuration of the widget.
|
||||
|
||||
## Available widgets
|
||||
|
||||
### archives
|
||||
|
||||
Display a list of years with the number of posts published in each year.
|
||||
|
||||
You need to create a page with `layout: archives` previously.
|
||||
|
||||
#### Paramters
|
||||
|
||||
- `limit`: Number of years to display. Default: `10`.
|
||||
|
||||
### search
|
||||
|
||||
Display a search box.
|
||||
|
||||
You need to create a page with `layout: search` previously.
|
||||
|
||||
### categories
|
||||
|
||||
Display a list of categories available in the blog.
|
||||
|
||||
#### Parameters
|
||||
|
||||
- `limit`: number of categories to display. Default: 10
|
||||
|
||||
### toc
|
||||
|
||||
Display a table of contents of the page.
|
||||
|
||||
### tag-cloud
|
||||
|
||||
Display a tag cloud.
|
||||
|
||||
#### Parameters
|
||||
|
||||
- `limit`: number of tags to display. Default: 10
|
||||
|
||||
Reference in New Issue
Block a user