DOCSEARCHbyAlgolia
Submit Docs

Stack Hugo Theme

website·Indexed 34 days ago

https://stack.cai.im/

A simple card-style Hugo theme designed for bloggers. It features a lightweight architecture with no CSS or JavaScript frameworks, using SCSS and vanilla JavaScript. Key capabilities include built-in i18n support, GDPR cookie consent banners, image processing via Hugo, and a flexible configuration for sidebars, widgets, and custom menus.

Tokens
6.8K
Snippets
56
Records
76
Agent score
62%

What's inside Stack

  1. Overview of Stack Hugo Theme features

    Stack is a card-style Hugo theme designed for bloggers. It is built with native JavaScript (no jQuery or frameworks) and does not use a CSS framework to maintain a minimal footprint. Key features include:

    • Responsive and lazy-loaded images
    • Dark mode support
    • Local search functionality
    • PhotoSwipe integration
    • Archive page templates
    • Properly cropped thumbnails
    • Subsection support
    • Table of contents

  2. Quickstart Stack theme using the starter template

    The fastest way to set up a Hugo website with the Stack theme is to use the official starter template. This method is recommended for first-time Hugo users as it includes a pre-configured GitHub Action for automatic deployment to GitHub Pages.
    # Use the starter template repository: https://github.com/CaiJimmy/hugo-theme-stack-starter

  3. Insert images into content in Stack

    When using page bundles, images located in the same directory as the content file can be referenced by their filename. External images are also fully supported and will work with features like image zooming and galleries.
    --- content/post/my-first-post/index.md ---
![Image 1](image1.png)
![Image 2](image2.png)

  4. Add and use custom SVG icons for menus

    The theme uses SVG icons located in the assets/icons folder. To add a custom icon, download an SVG (e.g., from Tabler Icons) and place it in the assets/icons folder of your Hugo site. You can then reference this icon in the menu configuration by providing the filename without the .svg extension in the params.icon field.

  5. Create an image gallery in Stack

    To create an image gallery, organize the images and the content file within a page bundle. Place multiple image markdown tags on the same line to group them into a row. For example, placing two images on the first line and one on the second line will render a gallery with two rows.
    content
└── gallery
    └── my-first-gallery
        ├── index.md
        ├── image1.png
        ├── image2.png
        └── image3.png
    --- content/gallery/my-first-gallery/index.md ---
![Image 1](image1.png) ![Image 2](image2.png)
![Image 3](image3.png)

  6. Add custom HTML, scripts, or styles to the Hugo theme

    The theme provides reserved partial files for injecting custom code. To overwrite these, create the corresponding file within your Hugo site folder.

    • Use layouts/_partials/head/custom.html for custom styles or scripts that belong in the <head> section.
    • Use layouts/_partials/head/custom-font.html specifically for custom font <link> tags.
    • Use layouts/_partials/footer/custom.html for custom scripts that should be placed at the end of the <body> section.

  7. Install Hugo Extended version for Theme Stack

    The Stack theme requires the Hugo extended version because it utilizes SCSS and TypeScript. Using a non-extended version will result in a TOCSS: failed to transform "scss/style.scss" error. Verify your installation by running hugo version and ensuring the output contains the extended keyword.
    hugo version
# Expected output example: hugo v0.157.0+extended+withdeploy ...

  8. Add a page to the menu using Front Matter

    The recommended way to add a page to the menu is by adding a menu field directly to that page's Front Matter. This allows the theme to automatically detect and highlight the current page when it is active in the menu.
    menu:
    main:
        name: title (optional)
        weight: -90
        params:
            icon: icon-name

  9. Install Stack theme as a Hugo module

    You can add the Stack theme as a dependency using Hugo modules. First, initialize your site as a module, then add the theme path to your configuration file. To update the theme, use the hugo mod get -u command followed by hugo mod tidy.
    # Initialize site as a module
hugo mod init github.com/me/my-new-blog

# Update theme to latest version
hugo mod get -u github.com/CaiJimmy/hugo-theme-stack/v4
hugo mod tidy
    # hugo.toml
[[module.imports]]
    path = "github.com/CaiJimmy/hugo-theme-stack/v4"

  10. Upgrade Hugo Theme Stack to v4

    Upgrading to v4 requires Hugo v0.157.0 or later. It is recommended to use the latest stable version of Hugo. To migrate, compare your current configuration against the new demo folder or the official starter template.

  11. Create a custom single-page homepage in Stack theme

    By default, the Stack theme displays a list of recent articles on the homepage. To replace this with a single static page, create an _index.md file in the root of the content directory and set the layout property to single in the frontmatter. This allows you to use the homepage as a standard article with custom Markdown content, shortcodes, and featured images.
    # Create the index file
hugo new content/_index.md
    ---
title: "Welcome to My Blog"
date: 2024-01-01
layout: single
---

This is my custom homepage! You can add any Markdown content here.

  12. Organize content using Hugo page bundles in Stack

    Stack uses Hugo's page bundles to organize content. A page bundle is a directory containing a content file (typically index.md) and its related resources (such as images). This is the recommended organization method for blog posts and other pages.
    content
└── post
    └── my-first-post
        ├── index.md
        ├── image1.png
        └── image2.png