DOCSEARCHbyAlgolia
Submit Docs

Congo Hugo Theme

repository·dev·Indexed 23 days ago

https://github.com/jpanther/congo

A high-performance, minimalist Hugo theme built with Tailwind CSS 3.0, designed for content-heavy sites. It features multilingual and RTL support, dark mode, and built-in integration for KaTeX, Mermaid, Chart.js, and Fuse.js. The theme supports installation via Hugo Modules and provides advanced customization options through Hugo's file lookup order, custom color schemes, and the Tailwind JIT compiler.

Tokens
34.9K
Snippets
122
Records
196
Agent score
80%

What's inside Congo

  1. Overview of Congo theme features

    dev

    Congo is a powerful, lightweight Hugo theme built with Tailwind CSS 3.0. It features a clean, minimalist design and is optimized for performance and accessibility (perfect Lighthouse scores).

    Key capabilities include:

    • Layout & Design: Fully responsive, multiple homepage layouts, multiple color schemes, and dark mode (auto, forced on, or forced off).
    • Content Support: Multilingual and RTL support, HTML and Emoji support, mathematical notation (KaTeX), diagrams (Mermaid), and charts (Chart.js).
    • Search & Navigation: Client-side site search via Fuse.js, heading anchors, Tables of Contents, and flexible taxonomies/menus.
    • Media & SEO: Automatic image resizing via Hugo Pipes, SVG icons (FontAwesome 6), and SEO-friendly social sharing links.
    • Analytics: Support for Fathom, Plausible, Umami, and Google Analytics.
    • Extras: RSS feeds, Favicons, and comments support.

  2. Organise content using Hugo page bundles and images

    dev

    Congo is designed to work with Hugo page bundles.

    Directory Structure

    • List pages: Use _index.md for directory/list pages.
    • Article pages: Use index.md for individual content pages.
    • Assets: Place images or other resources in a sub-directory alongside the index.md file.

    Image Types

    The theme automatically detects images based on their filenames within the page resources:

    • thumb: Used as the article thumbnail in lists (automatically cropped to 4:3 ratio).
    • cover: Displayed at the top of the article content on individual pages.
    • feature: A special type that replaces both thumb and cover. It is also used for social media metadata (Open Graph/Twitter).

    If the terms feature, cover, or thumb are found anywhere in the filename, the theme will use it for that purpose.

    . 
└── content 
    └── posts 
        ├── _index.md 
        └── first-post 
            ├── cover.jpg 
            ├── index.md 
            └── thumb.jpg

  4. Customise Congo using Hugo's file lookup order

    dev

    To customise Congo without modifying the theme files directly, use Hugo's file lookup order. Any files you place in your project's root directories will take precedence over the files in the themes/congo/ directory. This allows you to override HTML templates, partials, shortcodes, config files, data, and assets while maintaining a seamless upgrade path.

    For example, to override the main article template, create layouts/_default/single.html in your project root. This will override the theme's version of that file automatically.

  5. Create menu links using pageRef or url

    dev

    You can create menu items using two primary methods:

    1. Internal Links (pageRef): The easiest way to link to Hugo content pages or Taxonomies. Hugo automatically generates the correct link based on the reference.
    2. External Links (url): Use this parameter to link to an external website.

    Customization via params: Within a menu item, you can use the [menu_name.params] block to add extra functionality:

    • icon: Specifies an icon to display (e.g., github, search).
    • showName: A boolean to toggle whether the link text is visible.
    • target: Sets the URL target (e.g., _blank to open in a new window).
    • title: Sets the HTML title attribute for the link.
    [[main]]
  name = "GitHub"
  url = "https://github.com/jpanther/congo"
  weight = 30
  [main.params]
    icon = "github"
    showName = false
    target = "_blank"

  7. Configure multilingual and RTL support

    dev

    Congo supports multilingual sites and Right-to-Left (RTL) languages.

    • Multilingual: The site builds all available translations defined in your content.
    • RTL: RTL support is controlled on a per-language basis. When enabled for a specific language, the entire site reflows from right-to-left, with all theme elements restyled for RTL compatibility.

  8. How branch pages work in Congo

    dev

    Branch pages are used for high-level organizational content like the homepage, section listings, and taxonomy pages. In Hugo, these are defined using the filename _index.md (with an underscore).

    Congo honors front matter parameters in branch pages, allowing you to override default settings for that specific branch or section. For example, you can override the title or use the cascade parameter to apply settings to all sub-pages in that branch.

    ---
title: "Projects"
description: "Learn about some of my projects."
cascade:
  showReadingTime: false
---
This section contains all my current projects.

  9. Multilingual and RTL support

    dev

    Congo supports multilingual content and Right-to-Left (RTL) languages.

    • Multilingual: The site builds with all available translations ready.
    • RTL: When an RTL language is detected, the site content reflows from right to left. All theme elements are rebuilt to ensure proper visual layout in RTL mode. RTL is controlled on a per-language basis, allowing you to mix RTL and LTR content within the same project.

  10. Configure Multi-language Settings in Congo 2.0

    dev

    Congo 2.0 moves language-specific parameters to new configuration files following the pattern languages.[lang-code].toml.

    To migrate, create a new file in config/_default/ (e.g., languages.en.toml) and move the following parameters from their old locations:

    ParameterOld Location
    titleconfig.toml
    descriptionparams.toml
    copyrightconfig.toml
    dateFormatparams.toml
    [author]config.toml

    Example structure for config/_default/languages.en.toml:

    locale = "en"
label = "English"
displayName = "EN"
htmlCode = "en"
weight = 1
rtl = false

# Place language-specific parameters here

    Additionally, rename your existing menus.toml to menus.[lang-code].toml (e.g., menus.en.toml) to match the language code.

    # config/_default/languages.en.toml

locale = "en"
label = "English"
displayName = "EN"
htmlCode = "en"
weight = 1
rtl = false

# 此处放置特定于语言的参数

  11. Configure article grouping and external links

    dev

    Use the following front matter parameters to control how articles are grouped in lists or how they behave as external links:

    • groupByYear: Determines if articles are grouped by year on list pages.
    • externalUrl: Providing a URL will prevent a content page from being generated and any references to this article will link directly to the third-party website.