A wishlist of features and customisation

[BikramHalder]

Context

I'm greatly impressed by this theme and currently using it on my website. After working with it, I've identified several enhancements that would significantly improve its flexibility and usability for users like myself who want more control over configuration, layout, and content presentation.

I'm referencing some features from the Blowfish theme which demonstrates excellent implementation of these capabilities, though I understand hugo-narrow has its own unique philosophy and design.

Feature Requests

1. Structured Multi-File Configuration System

Current Behavior:
The theme likely uses a single configuration file (e.g., hugo.toml or config.toml) in the root directory.

Proposed Enhancement:
Support Hugo's modular configuration directory structure under /config/ with environment-specific overrides:

config/
  _default/
    hugo.toml       # Base configuration
    params.toml     # Theme parameters
    menus.toml      # Navigation menus
    languages.toml  # Multi-language settings (if applicable)
  production/
    hugo.toml       # Production overrides (e.g., baseURL)
  development/
    hugo.toml       # Development overrides

Benefits:

• Better organization for complex sites
• Easier environment-specific configuration management
• Improved maintainability for multi-language sites
• Cleaner version control (separate concerns)

References:

• Hugo Configuration Documentation
• Hugo Directory Structure Best Practices

---

2. Customizable Homepage Content Order

Current Behavior:
Homepage layout follows a fixed order of elements (profile, posts list, content, social links).

Proposed Enhancement:
Add configuration parameter to allow users to customize the order of homepage sections:

[params.home]
  sectionOrder = ["profile", "content", "posts", "social"]
  # or alternative ordering:
  # sectionOrder = ["content", "profile", "social", "posts"]

Benefits:

• Flexibility to prioritize what matters most (e.g., showcase writing before profile)
• Better control over first impressions for visitors
• Adaptability for different use cases (portfolio vs blog vs personal site)

---

3. Flexible Table of Contents (ToC) Positioning

Current Behavior:
ToC appears to be hidden or in a fixed position.

Proposed Enhancement:
Provide configuration options for multiple ToC display modes:

[params.page.toc]
  enable = true
  position = "sidebar-right"  # Options: "sidebar-left", "sidebar-right", "top", "hidden"
  keepStatic = false          # Sticky behavior on scroll
  auto = true                 # Auto-generate from headings

Benefits:

• Better navigation for long-form content
• Improved reading experience with persistent ToC visibility
• Flexibility for different content types and screen sizes
• Accessibility improvements for users navigating complex articles

Implementation Examples:

• Hugo PaperMod with Sidebar ToC
• FixIt Theme ToC Configuration
• Hugo Theme Stack ToC

---

4. Full-Width Navbar Option

Current Behavior:
Navbar likely matches the content width constraint.

Proposed Enhancement:
Add configuration to expand navbar to full browser width:

[params.navbar]
  fullWidth = true  # Navbar spans full viewport width
  contentWidth = "narrow"  # Content remains narrow

Benefits:

• Modern design aesthetic option
• Better visual separation between navigation and content
• More space for navigation items on wider screens
• Professional look for portfolio or business sites

---

5. Rich Shortcode Library

Current Situation:
Limited built-in shortcodes for content enhancement.

Proposed Enhancement:
Add a comprehensive shortcode library for richer content presentation:

Essential Shortcodes:

1. Cards - Display content in card layouts

   {{< card img="/image.jpg" title="Card Title" button="/link" >}}
   Card content here
   {{< /card >}}
   

2. Carousel/Slider - Image or content carousels

   {{< carousel duration="5000" >}}
     {{< carousel-item img="/img1.jpg" caption="First" >}}
     {{< carousel-item img="/img2.jpg" caption="Second" >}}
   {{< /carousel >}}
   

3. Code Importer - Import code from external files or GitHub

   {{< code-import file="example.js" lang="javascript" >}}
   

4. GitHub Gist - Embed gists easily

   {{< gist username gist-id >}}
   

5. Lead Text - Emphasized introductory paragraphs

   {{< lead >}}Important introduction text{{< /lead >}}
   

6. Icon Support - Easy icon insertion

   {{< icon "github" >}} {{< icon "twitter" >}}
   

7. Button - Styled call-to-action buttons

   {{< button href="/contact" target="_blank" >}}Contact Me{{< /button >}}
   

8. Badge - Display status badges

   {{< badge >}}New{{< /badge >}}
   

9. Timeline - Display chronological events

   {{< timeline >}}
     {{< timeline-item date="2023" >}}Event description{{< /timeline-item >}}
     {{< timeline-item date="2024" >}}Another event{{< /timeline-item >}}
   {{< /timeline >}}
   

10. TypeIt - Animated typing effects for text

Benefits:

• Richer, more engaging content without custom HTML
• Consistency in design patterns across the site
• Easier content creation for non-technical users
• Professional presentation capabilities

References:

• Blowfish Shortcodes - Comprehensive implementation
• Hugo Codex Add-ons
• Hugo Mods Shortcodes

6. Display Website/Site Name in Navigation Bar

Current Behavior:
The navigation bar only displays a logo (either custom image or first letter of site title) but does not show the actual site name/title as text.

Proposed Enhancement:
Add a configuration option to display the site name/title next to or instead of the logo in the navigation bar:

[params.navbar]
  showSiteTitle = true              # Display site title text
  showLogo = true                   # Display logo
  titlePosition = "right"           # Options: "left", "right", "only" (hides logo)
  showTitleOnPages = ["all"]        # Options: "all", "home", "posts", ["about", "contact"]

Implementation Options:

1. Logo + Title Combination:

   <!-- In layouts/_partials/navigation/header.html -->
   <div class="flex items-center gap-3">
     <!-- Logo (existing) -->
     <a href="/" class="flex h-10 w-10 items-center...">
       <img src="{{ site.Params.logo.image }}" alt="{{ site.Title }}" />
     </a>
     
     <!-- Site Title (NEW) -->
     {{ if site.Params.navbar.showSiteTitle }}
       <a href="/" class="text-lg font-semibold hover:text-primary transition-colors">
         {{ site.Title }}
       </a>
     {{ end }}
   </div>

2. Conditional Display by Page Type:

   [params.navbar]
     showSiteTitle = true
     showTitleOnPages = ["posts", "about"]  # Only show on specific pages
     # or
     showTitleOnPages = ["all"]              # Show on all pages
     # or  
     hideTitleOnPages = ["home"]             # Hide only on homepage

3. Title-Only Mode (No Logo):

   [params.navbar]
     titlePosition = "only"  # Hides logo, shows only title

Benefits:

• Improved brand recognition across all pages
• Better visual hierarchy with text alongside logo
• More professional appearance for business/portfolio sites
• Accessibility: screen readers get clear site identification
• Flexibility for sites that prefer text-based navigation
• Useful when logo is abstract and needs context

Use Cases:

• Personal blogs: Show "John Doe's Blog" alongside avatar
• Business sites: Display company name prominently
• Portfolio sites: Ensure name is always visible for branding
• Documentation sites: Show project name for clarity

Design Considerations:

• Responsive behavior: On mobile, consider showing only logo or abbreviated title
• Typography: Title should use the site's primary font and sizing
• Positioning: Should integrate smoothly with existing nav layout
• Animation: Optional subtle hover effects on title link

Implementation Example from Current Code:

Looking at the existing layouts/_partials/navigation/header.html, the modification would be around line 7-26 where the logo is currently displayed:

<!-- Enhanced version with site title -->
<div class="flex items-center gap-3">
  {{ if ne site.Params.logo.image "" }}
    <a href="{{ site.Home.RelPermalink }}" 
       class="flex h-10 w-10 items-center justify-center overflow-hidden rounded-full...">
      <img src="{{ site.Params.logo.image }}" alt="{{ site.Title }}" />
    </a>
  {{ else }}
    <a href="{{ site.Home.RelPermalink }}" 
       class="bg-primary text-primary-foreground... flex h-10 w-10...">
      {{ substr site.Title 0 1 | upper }}
    </a>
  {{ end }}
  
  <!-- NEW: Site Title Display -->
  {{ if site.Params.navbar.showSiteTitle }}
    {{ $showOnCurrentPage := false }}
    {{ if eq site.Params.navbar.showTitleOnPages "all" }}
      {{ $showOnCurrentPage = true }}
    {{ else if in site.Params.navbar.showTitleOnPages .Type }}
      {{ $showOnCurrentPage = true }}
    {{ end }}
    
    {{ if $showOnCurrentPage }}
      <a href="{{ site.Home.RelPermalink }}" 
         class="text-lg font-semibold text-foreground hover:text-primary transition-colors duration-200 hidden md:block">
        {{ site.Title }}
      </a>
    {{ end }}
  {{ end }}
</div>

References:

• Hugo Site Variables Documentation
• Hugo Menu Configuration
• Wowchemy Header Customization

---

Priority

Based on implementation complexity and impact:

• High Priority: Feature 3 (ToC positioning), Feature 1 (Multi-file config), Feature 6 (Site name in nav)
• Medium Priority: Feature 2 (Homepage order), Feature 4 (Full-width navbar)
• Nice-to-Have: Feature 5 (Shortcodes library) - Could be implemented incrementally

Additional Notes

I understand these are significant enhancements and may not align with the theme's minimalist philosophy. I'm happy to:

• Test beta implementations
• Provide feedback during development
• Contribute documentation for new features
• Help with use case examples

Thank you for considering these suggestions and for maintaining this excellent theme!

[tom2almighty]

Regarding this issue, I would like to make a few special notes:
It is evident that the entire content of this issue is generated by AI. I'm not sure if you directly submitted your requirements to AI to generate this conversation, or you only indexed the entire theme directory to create this wishlist. I cannot even tell which of these are your real needs and which are redundant content generated by AI.

That said, there are indeed some constructive suggestions in it, and some of these requirements have been implemented:

1. Currently, the configuration files of the Hugo example site have been structurally optimized;
2. Custom sorting of homepage content is now supported;
3. The sidebar table of contents (TOC) feature has been added.

It should be noted that two of the requirements—full-width header and header title are not planned to be supported at this time.
As the theme name "Narrow" suggests, the core design style of this theme is compact and narrow. The current theme header has three predefined sections: logo area, navigation area, and function area, which are arranged in left, center, and right positions respectively. There is no extra space to accommodate a title, which was a deliberate trade-off made in the early stage of theme design. In addition, considering the adaptation logic of mobile devices such as tablets and mobile phones, as well as the consistency of the overall visual style, adding a full-width header and header title is not an optimal design choice.

Shortcodes are the core way for Hugo to extend page styles, and a rich set of shortcodes is indeed an important indicator for evaluating the quality of a theme. However, in my opinion, theme design should focus on writing itself—most, creators do not frequently use a large number of shortcodes in the writing process, and the special format of shortcodes cannot preview styles in most editors. One of the core goals of the Narrow theme is to implement required functions as much as possible through native Markdown syntax. For example, for the justified gallery feature, you only need to insert image resources consecutively to generate it automatically, and it can also be previewed normally in the editor without relying on shortcodes. Of course, for some commonly used shortcodes, it will gradually add support in subsequent version updates. It is also welcome you to contribute more shortcode functions through PR.

Finally, a note on the sidebar TOC: In the initial design plan, I did not intend to support this feature because I was worried that it would disrupt the overall visual consistency of the theme. However, since this requirement was mentioned in multiple subsequent issues, finally I'v added this feature in the latest version and provided parameters to choose whether to enable it independently.

Welcome your issues and pull requests.

[BikramHalder]

Thanks for accommodating my request. I really appreciate that you implemented those three features! I admit I generated this conversation using AI by just listing my requirements in keywords with priority order, and it definitely got carried away with way too many points 😅. I now understand Narrow's core design philosophy, and the points of not implementing some stuffs. At the end, I am thankful that you implemented the most prioritized features. Neverthless, I will try to add some shortcodes via PR, which could be useful in general.

[BikramHalder]

Currently, ToC can only be controlled globally via site.Params.toc position with no way to disable it for specific pages. Please add support for a page-level showToc: false front matter parameter to allow per-page ToC overrides. This would possibly require checking .Params.toc in layouts/_partials/ui/toc-sidebar.html, layouts/_partials/ui/toc-card.html, layouts/baseof.html, and layouts/_partials/ui/dock.html before rendering ToC components.

[BikramHalder]

I just encountered an issue that custom font preloads can't be applied, because the head.html partial doesn't include a call to extend-head.html:

{{ partial "extend-head.html" .  }}

Even though I created layouts/_partials/extend-head.html with font preload links, they weren't being rendered because the theme never invokes this partial. Thanks for considering.

[tom2almighty]

extent-head.html may be used in other themes. For Hugo Narrow customization, see Custom Hugo Narrow