Stack

https://stack.jimmycai.com/
Admin
Stack is a card-style theme designed for bloggers, featuring no CSS/JavaScript frameworks, dark mode...
Tokens:3,207
Snippets:41
Trust Score:9.7
Update:1 year ago
Show doc for...
Tokens:
Raw
### Utterances Configuration Example

Source: https://stack.jimmycai.com/config/comments

This shows how to configure the utterances comment system, with its specific options nested under the main comments section.

```toml
[Params.Comments.utterances]
# utterances specific options here
```

--------------------------------

### Clone Stack Hugo Theme

Source: https://stack.jimmycai.com/guide/getting-started

This command clones the latest source code of the Stack Hugo theme directly into the 'themes/hugo-theme-stack' directory of your Hugo project. This is one of the methods to install the theme.

```bash
git clone https://github.com/CaiJimmy/hugo-theme-stack/ themes/hugo-theme-stack
```

--------------------------------

### Check Hugo Version

Source: https://stack.jimmycai.com/guide/getting-started

This command checks if the installed Hugo version is the extended version, which is required by the Stack theme due to its use of SCSS and TypeScript. The output should include the keyword 'extended'.

```bash
hugo version
```

--------------------------------

### Copy File for Hugo Module Customization

Source: https://stack.jimmycai.com/guide/modify-theme

When using the Hugo module method to modify a theme, copy the desired file from the theme's directory to the same path within your project's 'layouts' directory. This example shows how to copy a specific partial file.

```text
themes/hugo-theme-stack/layouts/partials/head/custom.html -> layouts/partials/head/custom.html
```

--------------------------------

### Initialize Hugo Module

Source: https://stack.jimmycai.com/guide/getting-started

This command initializes your Hugo site as a Hugo module. This is a prerequisite for using the theme as a Hugo module. Replace 'github.com/me/my-new-blog' with your project's repository path.

```sh
hugo mod init github.com/me/my-new-blog
```

--------------------------------

### Categories Widget Configuration

Source: https://stack.jimmycai.com/config/widgets

Outlines the configuration for the 'categories' widget, used to display available blog categories. It includes an optional 'limit' parameter for the number of categories shown.

```Markdown
### categories 
Display a list of categories available in the blog.
#### Parameters 
  * `limit`: number of categories to display. Default: 10
```

--------------------------------

### Search Widget Configuration

Source: https://stack.jimmycai.com/config/widgets

Describes the 'search' widget, which provides a search box functionality. A pre-existing 'search' layout page is necessary for this widget.

```Markdown
### search 
Display a search box.
You need to create a page with `layout: search` previously.
```

--------------------------------

### Widget Configuration Structure

Source: https://stack.jimmycai.com/config/widgets

Explains the structure for configuring widgets in the blog. Widgets are defined as arrays of maps, each containing a 'type' and 'params' for customization.

```Markdown
widgets.homepage and widgets.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.
```

--------------------------------

### Tag Cloud Widget Configuration

Source: https://stack.jimmycai.com/config/widgets

Explains the 'tag-cloud' widget, used for displaying a cloud of tags. It supports a 'limit' parameter to control the number of tags shown.

```Markdown
### tag-cloud 
Display a tag cloud.
#### Parameters 
  * `limit`: number of tags to display. Default: 10
```

--------------------------------

### Hugo Page Bundle Structure for a Post

Source: https://stack.jimmycai.com/writing/markdown

Illustrates the recommended directory structure for a Hugo page bundle representing a blog post. It includes the main content file (index.md) and associated image resources.

```markdown
content
└── post
    └── my-first-post
        ├── index.md
        ├── image1.png
        └── image2.png
```

--------------------------------

### Import Stack Hugo Theme (YAML)

Source: https://stack.jimmycai.com/guide/getting-started

This YAML configuration snippet demonstrates how to import the Stack Hugo theme (v3) as a dependency in your Hugo site's configuration file (config.yaml). This is an alternative to the TOML method for module integration.

```yaml
# config.yaml
module:
  imports:
    - path: github.com/CaiJimmy/hugo-theme-stack/v3
```

--------------------------------

### Update Stack Hugo Theme Module

Source: https://stack.jimmycai.com/guide/getting-started

These commands update the Stack Hugo theme to the latest version (v3) and tidy up the Hugo modules. Run these in your Hugo site's root directory after initially importing the theme as a module.

```sh
hugo mod get -u github.com/CaiJimmy/hugo-theme-stack/v3
hugo mod tidy
```

--------------------------------

### Import Stack Hugo Theme (TOML)

Source: https://stack.jimmycai.com/guide/getting-started

This TOML configuration snippet shows how to import the Stack Hugo theme (v3) as a dependency in your Hugo site's configuration file (config.toml). This enables using the theme as a module.

```toml
# config.toml
[[module.imports]]
path = "github.com/CaiJimmy/hugo-theme-stack/v3"
```

--------------------------------

### Archives Widget Configuration

Source: https://stack.jimmycai.com/config/widgets

Details the configuration for the 'archives' widget, which displays a list of years with post counts. It requires a pre-created 'archives' layout page.

```Markdown
### 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.
#### Parameters 
  * `limit`: Number of years to display. Default: `10`.
```

--------------------------------

### Embed Generic Video File

Source: https://stack.jimmycai.com/writing/shortcodes

Embeds a video file from a provided URL or a path relative to the static directory. Supports optional autoplay and poster image attributes.

```Go Templating
{{< video VIDEO_URL >}}

{{< video src="VIDEO_URL" autoplay="true" poster="./video-poster.png" >}}
```

--------------------------------

### Add Stack Hugo Theme as Git Submodule

Source: https://stack.jimmycai.com/guide/getting-started

This command adds the Stack Hugo theme as a Git submodule to your Hugo project. This method is recommended if your project is already managed with Git and allows for easier updates.

```bash
git submodule add https://github.com/CaiJimmy/hugo-theme-stack/ themes/hugo-theme-stack
```

--------------------------------

### Hugo Page Bundle Structure for an Image Gallery

Source: https://stack.jimmycai.com/writing/markdown

Shows the directory structure for a Hugo page bundle specifically designed to hold images for a gallery. Similar to a post bundle, it contains an index.md and multiple image files.

```markdown
content
└── gallery
    └── my-first-gallery
        ├── index.md
        ├── image1.png
        ├── image2.png
        └── image3.png
```

--------------------------------

### Select Comment System Provider (String)

Source: https://stack.jimmycai.com/config/comments

This option specifies which comment system provider to use. The value must be one of the supported providers.

```toml
[Params.Comments]
provider = "giscus"
```

--------------------------------

### Quote with Attribution

Source: https://stack.jimmycai.com/writing/shortcodes

Displays a quote with optional author, source, and URL attributes for attribution. The content of the quote is placed between the opening and closing shortcode tags.

```Go Templating
{{< quote author="A famous person" source="The book they wrote" url="https://en.wikipedia.org/wiki/Book" >}}
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
{{< /quote >}}
```

--------------------------------

### Inserting Images for a Gallery in Markdown

Source: https://stack.jimmycai.com/writing/markdown

Explains how to insert multiple images within a markdown content file to create a gallery layout. The rendering behavior (e.g., rows and columns) depends on the theme's handling of such markdown.

```markdown
---
--- content/gallery/my-first-gallery/index.md ---
![Image 1](image1.png) ![Image 2](image2.png)
![Image 3](image3.png)
---
```

--------------------------------

### Default Color Scheme Setting

Source: https://stack.jimmycai.com/config/color-scheme

Sets the initial color scheme when the toggle is off or for new visitors. Accepts 'light', 'dark', or 'auto' (uses system preference).

```toml
default = "light"
```

```toml
default = "dark"
```

```toml
default = "auto"
```

--------------------------------

### Add Menu Item via TOML Configuration

Source: https://stack.jimmycai.com/config/menu

Add menu items to the site's configuration file using TOML. This method is suitable for non-page links and allows setting the name, URL, weight, identifier, and parameters like icon and newTab behavior.

```toml
[menu]
[[menu.main]]
    name = "Home"
    url = "/"
    weight = 10
    identifier = "home"
    [menu.main.params]
        icon = "home"
        newTab = true
```

--------------------------------

### Add Menu Item via YAML Configuration

Source: https://stack.jimmycai.com/config/menu

Add menu items to the site's configuration file using YAML. This method is suitable for non-page links and allows setting the identifier, name, URL, weight, and parameters like icon and newTab behavior.

```yaml
menu:
    main:
        - identifier: home
          name: Home
          url: /
          weight: -100
          params:
            icon: home
            newTab: true
```

--------------------------------

### Color Scheme Parameters

Source: https://stack.jimmycai.com/config/color-scheme

Configuration fields for the color scheme are located under the `[Params.colorScheme]` section. This includes settings for toggling the color scheme switcher and defining the default color scheme.

```toml
[Params.colorScheme]
toggle = true
default = "auto"
```

--------------------------------

### Embed Tencent Video

Source: https://stack.jimmycai.com/writing/shortcodes

Embeds a Tencent Video using its unique video ID, which can be found in the video's URL.

```Go Templating
{{< tencent VIDEO_ID >}}
```

--------------------------------

### Add Menu Item via Front Matter (YAML)

Source: https://stack.jimmycai.com/config/menu

Configure menu items directly within a page's front matter. This method is recommended for pages and allows specifying the menu name, weight, and optional parameters like an icon.

```yaml
menu:
    main:
        name: title (optional)
        weight: -90
        params:
            icon: icon-name
```

--------------------------------

### Table of Contents (TOC) Widget

Source: https://stack.jimmycai.com/config/widgets

Details the 'toc' widget, which automatically displays the table of contents for the current page.

```Markdown
### toc 
Display a table of contents of the page.
```

--------------------------------

### Default Published Date Format (Go)

Source: https://stack.jimmycai.com/config/date-format

Specifies the default format for displaying the page's publish date. Go's date formatting conventions are used, which may differ from other programming languages.

```go
Jan 02, 2006
```

--------------------------------

### Embed Bilibili Video

Source: https://stack.jimmycai.com/writing/shortcodes

Embeds a Bilibili video using its video ID and an optional part number. The video ID is extracted from the video's URL.

```Go Templating
{{< bilibili VIDEO_ID PART_NUMBER >}}
```

--------------------------------

### Embed YouTube Video

Source: https://stack.jimmycai.com/writing/shortcodes

Embeds a YouTube video using its video ID, which is the unique identifier found in the video's URL.

```Go Templating
{{< youtube VIDEO_ID >}}
```

--------------------------------

### Enable Image Processing for Cover Images (Hugo)

Source: https://stack.jimmycai.com/config/image-processing

This configuration option allows you to enable or disable Hugo's built-in image processing specifically for cover (featured) images. This feature automatically resizes and optimizes local images included via page bundles.

```toml
cover.enabled = true
```

--------------------------------

### Configure Twitter Site Account

Source: https://stack.jimmycai.com/config/open-graph

Sets the Twitter account name for the website, used for attribution. The '@' symbol should be omitted. This is configured within the Open Graph parameters.

```hugo
[[Params.opengraph]]
site = "your_twitter_handle"
```

--------------------------------

### Embed GitLab Snippet

Source: https://stack.jimmycai.com/writing/shortcodes

Embeds a GitLab snippet using its snippet ID, which is found in the URL of the snippet.

```Go Templating
{{< gitlab SNIPPET_ID >}}
```

--------------------------------

### Default Last Updated Date Format (Go)

Source: https://stack.jimmycai.com/config/date-format

Specifies the default format for displaying the page's last updated date. This includes date and time, utilizing Go's specific date formatting.

```go
Jan 02, 2006 15:04 MST
```

--------------------------------

### Inserting Images in Markdown Content

Source: https://stack.jimmycai.com/writing/markdown

Demonstrates how to reference images within a Hugo page bundle directly in the markdown content file. These images are assumed to be in the same directory as the markdown file.

```markdown
---
--- content/post/my-first-post/index.md ---
![Image 1](image1.png)
![Image 2](image2.png)
---
```

--------------------------------

### Configure Twitter Card Type

Source: https://stack.jimmycai.com/config/open-graph

Specifies the Twitter card type for rich media display. Supported types are 'summary' and 'summary_large_image'. This setting is part of the Open Graph parameters.

```hugo
[[Params.opengraph]]
card = "summary_large_image"
```

--------------------------------

### Enable Image Processing for Content Images (Hugo)

Source: https://stack.jimmycai.com/config/image-processing

This configuration option allows you to enable or disable Hugo's built-in image processing for images present within the main content of your site. This process automatically resizes and optimizes local images included via page bundles.

```toml
content.enabled = true
```

--------------------------------

### Disqus Configuration (Root Level)

Source: https://stack.jimmycai.com/config/comments

For Disqus, the 'disqusShortname' configuration option is placed at the root level of the configuration file, not within a nested section.

```toml
disqusShortname = "your-disqus-shortname"
```

--------------------------------

### Enable Comment System (Boolean)

Source: https://stack.jimmycai.com/config/comments

This configuration option controls whether the comment system is enabled or disabled on the website. It accepts a boolean value.

```toml
[Params.Comments]
enabled = true
```

--------------------------------

### Toggle Color Scheme Button

Source: https://stack.jimmycai.com/config/color-scheme

Controls the visibility of the color scheme toggle button. If set to `false`, the `default` option dictates the color scheme. This is a boolean parameter.

```toml
toggle = false
```

--------------------------------

### Add Custom Font Family to Article Content (HTML/CSS/JS)

Source: https://stack.jimmycai.com/config/header-footer

This snippet demonstrates how to override the default article font family to Merriweather. It includes inline CSS to set the font-family variable and JavaScript to dynamically load the Merriweather font from Google Fonts.

```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>
```
Tokens:
Raw