reorx/hugo-papermodx

A fast, clean, responsive Hugo theme.

PaperModX

PaperModX is a forked version of PaperMod, it aims at adding new features and improving code quality, makes it easier to read and modify by anyone with basic knowledge of Hugo and HTML.

Features and changes:

• Table of Contents (ToC) floating on the side
• InstantClick integration
• Social icons from Simple Icons
• Opinionated UI enhancements

Getting started

You can use reorx/papermodx-example as a boilerplate to create a new Hugo site with PaperModX theme. For detailed instructions please see the README of papermodx-example repo.

Table of Contents (ToC) floating on the side

By adding config:

params:
  TocSide: 'left'  # or 'right'

ToC will float on the left/right side of the page. You can take a look at how 'right' feels like in Installation | Update.

The ToC box is responsive, it only shows on the side when minimum screen size is 1440px.

This feature is enabled on this site.

InstantClick integration

By adding config:

params:
  EnableInstantClick: true

InstantClick will be enabled, making navigation behaves like Single Page Application.

Note that /search pages are omitted from InstantClick to prevent conflicts from search's JavaScript, this may be changed in the future after refactoring those scripts.

Another thing to notice is smooth scrolling will be disabled if InstantClick is enabled, because they both listen click event on every <a> tags. IMO smooth scrolling is not very useful so it has to give way to InstantCllick.

This feature is enabled on this site.

Give links an accent color.

Though PaperModX is designed to be minimal, accent color is still essential. It's a good way to show personality and make your site feels more delightful.

The default color is a purple vibe, you can customize the colors of link, link underline and their hover variants by override the following css variables in assets/css/extended/custom.css of your site.

:root {
  --link-color: var(--primary);
  --link-hover-color: #573eaa;
  --link-underline-shadow: 0 1px 0 var(--link-color);
  --link-hover-underline-color: #573eaa;
  --link-hover-underline-shadow: 0 2px 0 var(--link-hover-underline-color);
}

Customize pagniator size

In section pages, if you want the paginator size be different from the global config, you can add paginate in the frontmatter to customize.

---
paginate: 10
---

Menus external link

You can add external: true to a menu item's params to mark it as an external link, this will add a small icon to the end, and make the link open in new tab when clicked.

menu:
  main:
    - name: "@Author"
      url: "https://reorx.com"
      params:
        external: true

Highlight code with Chroma, no bullshit

PaperMod uses highlight.js to highlight code blocks. In PaperModX, we use Chroma which is the recommended way in Hugo's official docs, thus changing theme is easily supported.

By default the themes are github for light and dracula for dark, you can change it by adding chroma-light.css and chroma-dark.css in site's assets/css/lib directory.

Social icons from Simple Icons

Add social icons with -simple suffix from Simple Icons.

Available icons:

• github-simple
• rss-simple
• telegram-simple
• twitter-simple
• pinboard-simple

The icons are moved from layouts/partials/svg.html to data/svg.toml, makes it easier to maintain, it's now possible to have an index page to show all the icons, check it out at: Icons Preview

Opinionated UI enhancements

• Distinguish home page width and post page width, post page is wider (800px) for better readability, you can change it by --post-width in theme-vars.css.
• Menu links are always bold, this feels more consistent when clicking around. Active links have deeper color.

hugo-papermodx's Issues

floating TOC is not scrolling down [BUG]

Describe the bug

• Device/Os: MacOS
• Type: Desktop
• Browser and version Chrome
• Hugo Version >=0.83.0
• Theme Version: master

Steps to reproduce the behavior:

Floating TOC is not scrolling down

Expected behavior:

floating TOC is supposed to scroll down to the current section

Screenshots

Additional context

The TocSide does't work for me

Hi, sorry for this issue, but I have a question, I follow the guide to configure my config.yml, I add TocSide: right in it. But when I build it on my local machine, the toc works well, when I use GitHub Actions, the tocside doesn't work well, it is still at the top side rather left side.

I tried both on GitHub pages and cloudflare pages, none of them works well for the TocSide feature. I don't know what happend, So anything wrong with my config file?

Here is my gh-page.yml file.

name: github pages

on:
  push:
    branches:
      - main  # Set a branch to deploy
  pull_request:

jobs:
  deploy:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v3
        with:
          submodules: true  # Fetch Hugo themes (true OR recursive)
          fetch-depth: 0    # Fetch all history for .GitInfo and .Lastmod

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: 'latest'
          extended: true

      - name: Build
        run: hugo --minify

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        if: ${{ github.ref == 'refs/heads/main' }}
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public

Using Collapse

Hi,

I am trying to use the collapse shortcode, but I couldn't figure out how. I am really new to Hugo so I struggle adding new stuff.

I was able to use a custom one but was hoping I could keep the same style as the TOC and use it in-text. Could you tell me what am I doing wrong?

(I was just trying the {{ collapse }} option)

[BUG] Archives page renders as list page

Describe the bug
An archives layout page sometimes display using list.html rather than archives.html.

• Device/Os: MacOS M1
• Type: Desktop
• Browser and version [e.g. Chrome 86.0]: Firefox 125.0 and Chrome 124.0
• Hugo Version [ >=0.83.0 expected]: 0.124 extended
• Theme Version [e.g. v4.0, master, or commit-id ]: b787253

Steps to reproduce the behavior:
Paste the following lines in both layouts/_default/archives.html and list.html, which will print for an archives page.

{{- warnf "list: %s" .Page.Name -}}

However, it seems like the order in which they print doesn't matter, the archives page will still be treated as a list page. Sometimes it displays as an archives page, but when it does it is always empty.

I was only able to have it display as an archives page by copying archives.html and list.html into my own layouts/_default and override the code in list.html with the contents of archives.html. But then the home page behaves like an archive page.

Expected behavior:
A page with layout: archives is displayed with list.html layout.

Additional context
I'm using Github submodule

[Feature Request] Option for different logo in dark/light mode

Hi,

Would it be possible to add a separate dark/light mode logo to the site?

I'm now using a solution by @pushblue.

It is okay for now, but if there will be a major change in the header/footer partial this will cease to work.

My suggestion would be to add two separate icon params under the label group like so:

logo:
  text: "my-title"
  iconDark: "my-darkmode-icon.svg"
  iconLight: "my-lightmode-icon.svg"

Or the approach in the original PaperMod theme would also work: issue 976

Fix highlight js not working with InstantClick

[BUG] Code block can't read in light mode (PaperMod migrate to PaperModX)

Describe the bug

• Device/Os: macOS
• Type: Desktop
• Browser and version [e.g. Chrome 86.0]: Chrome 103.0.5060.134
• Hugo Version [ >=0.83.0 expected]: v0.101.0+extended
• Theme Version [e.g. v4.0, master, or commit-id ]: 61452c1

Steps to reproduce the behavior:

Using the PaperModX theme for my blog (it use PaperMod before).

The code in the code block cannot be read in light mode. If you switch to dark mode, it will be fine.

Expected behavior:

The code block can be read easily.

Screenshots

Light mode (also the four black corners maybe a "bug" too?)

Night mode (it works well)

Additional context

You can preview the example page in here: https://test-papermodx.my-hugo-blog.pages.dev/posts/mastering-git-cherry-pick/

Current config file

baseURL: "https://blog.triplez.cn/"
languageCode: "zh-cn"
defaultContentLanguage: "zh"
hasCJKLanguage: true
title: "TripleZ's Blog"
theme: "PaperMod"

disqusShortname: triplezs-blog
googleAnalytics: UA-xxxx-3

menu:
    main:
        # - identifier: categories
        #   name: Categories
        #   url: /categories/
        #   weight: 10
        - identifier: tags
          name: 标签 
          url: /tags/
          weight: 20
        - identifier: archives
          name: 归档
          url: /archives/
          weight: 30

params:
    env: production
    defaultTheme: auto # to switch between dark or light according to browser theme
    disableThemeToggle: false
    ShowBreadCrumbs: false
    ShowPostNavLinks: true
    TocSide: 'left'  # or 'right'
    EnableInstantClick: true
    author: ["TripleZ"]
    description: ""
    BeiAn: 粤ICP备xxxxx号
    comments: true
    ShowToc: true
    TocOpen: false
    ShowReadingTime: true
    ShowShareButtons: true
    ShowCodeCopyButtons: true
    fuseOpts: # for search
        isCaseSensitive: false
        shouldSort: true
        location: 0
        distance: 1000
        threshold: 0.4
        minMatchCharLength: 0
        keys: ["title", "permalink", "summary", "content"]
    assets:
        favicon: "/favicon.ico"
        favicon16x16:  "/favicon-16x16.png"
        favicon32x32:  "/favicon-32x32.png"
        apple_touch_icon:  "/apple-touch-icon.png"
        safari_pinned_tab:  "/safari-pinned-tab.svg"

# for search
outputs:
    home:
        - HTML
        - RSS
        - JSON # is necessary

markup:
  highlight:
    # anchorLineNos: true
    codeFences: true
    guessSyntax: true
    lineNos: true
    style: monokai
  goldmark:
    renderer:
      unsafe: true # enable raw html in markdown

[BUG]

Upon using the profile mode, when are prompted to the home / path but when we click on to other links we dont get redirected back to the home for some reason. This bug only a occurs after hosting it to the github and not locally. The home path gets changed to the current path. Even the key binding gets affected [Alt + H] doesnt takes us back to home.

bug-poc.2.mp4

[BUG] Unable to Add Theme as Hugo Module

[brandon@t4n wrestlingmob]$ hugo mod tidy go: no module dependencies to download go: github.com/reorx/[email protected]: parsing go.mod: module declares its path as: github.com/adityatelange/hugo-PaperMod but was required as: github.com/reorx/hugo-PaperModX go: no module dependencies to download hugo: collected modules in 627 ms Error: module "github.com/reorx/hugo-PaperModX" not found; either add it as a Hugo Module or store it in "/home/brandon/Documents/sites/wrestlingmob/themes".: module does not exist [brandon@t4n wrestlingmob]$ hugo mod get -u go: no module dependencies to download go: github.com/reorx/[email protected]: parsing go.mod: module declares its path as: github.com/adityatelange/hugo-PaperMod but was required as: github.com/reorx/hugo-PaperModX go: no module dependencies to download hugo: collected modules in 557 ms WARN 2022/05/23 20:53:24 module "github.com/reorx/hugo-PaperModX" not found; either add it as a Hugo Module or store it in "/home/brandon/Documents/sites/wrestlingmob/themes".: module does not exist go: github.com/reorx/[email protected]: parsing go.mod: module declares its path as: github.com/adityatelange/hugo-PaperMod but was required as: github.com/reorx/hugo-PaperModX

The above is the error I get when trying to add this as a module for Hugo. I cannot tell if it is me doing something wrong, or if it is the theme incorrectly marking it's dependencies.

Enhance code copy button

use my implementation in hugo-book

Tags页面不显示Tag

你好，不知道为什么没有显示Tags，是哪里没有设置好吗？
https://wananaiko.design/tags/

cli to share tweet for blog link and append to the bottom as comment entrance

automatically switch themes

on Firefox, it doesn't automatically switch themes but you have to reload the page.

would it be possible to automatically recognise when the user switches to dark mode and adjust the webpage?

Move exampleSite to master branch

Also:

• tidy the content, trim the useless ones

Use SCSS instead of CSS

benefits:

• better readability and easier to maintain
• easier theming, especially for chroma highlight

Theme variant does't work

Hi,
I have just installed PaperModX theme on my Hugo dev server but unfortunately theme switch doesn't work. I tried to force dark theme in config
defaultTheme: dark
Generated website is uses light theme. If I try to switch themes with toggle it works fine.
Any help?

[Feature Request] Mastodon-compatible social link for verification

According to the official Mastodon docs, you can verify a given website link is yours by adding the rel="me" flag to a link directly back to your Mastodon profile. I feel that this should be either the default or a toggleable option, since it seems rather straightforward to implement and would be a pretty nice thing to work out-of-the-box.

ToC gets cut on small screens

The floating ToC gets cut on long articles if read with smaller screens.
Scrolling the page doesn't scroll the ToC, so that doesn't help either.

Sample Screenshot

How to modify toc css

I want to change the style of TOC and don't know where to start

Date too close to to date icon in meta data

The date information is too close to the date icon. In the posts and in the listings.

Comment Section being cut off

Describe the bug
With comments enabled, the full comment section is not visible until a reload of the page (on Linux/Firefox browser).
On mobile, it is inconsistent. Sometimes the comment sections show up, sometimes it takes multiple reloads for it to show up properly.

• Device/Os: Arch Linux 6.0.8 zen / Chrome on android / Safari on iPhone
• Type: Both Desktop and Mobile
• Browser and version [e.g. Chrome 86.0]: Linux Firefox 106.0.5, Android Chrome v13.43.18.29.arm64, iPhone Safari 16.1
• Hugo Version [ >=0.83.0 expected]: hugo v0.105.0+extended
• Theme Version [e.g. v4.0, master, or commit-id ]: master

Steps to reproduce the behavior:

1. Set up remark42
2. Set remark 42 as default comment system and set up
3. Go to article w/ comments enabled
4. See comment section (sometimes) cut off - requiring reload (sometimes many)
5. Reload and see comment section in full

Expected behavior:
Comment section should not be cut off

Screenshots
Screenshot of the comment section being cut off

Proper size, after (one or many) reloads

Hide description on page depening on a parameter - but keep meta desc in head

I really like this theme 🚀

In my project I try to make good SEO results so I added a description to every page, tag / taxonomy. But after adding the description is added right under the H1. It is SEO optimized for the SERP itself but doesn't have any pro for the user. It would be excellent to have a possibility to keep the description in meta description field but hide it on the page itself.

I found a MR on papermod (Commit), but it was declined. Think the purpose wasn't clear on this. That's why I tried to make the why clearer here.

Any idea / discussions about this? Otherwise I could create a MR on here.

Enhance search page

• show matched content in search result
• export a function for disabling search, makes search page compatible with InstantClick

Responsive figures

I fused figure.html and cover.html into a new partial that should create better responsive figures

I can make a PR if you want

https://github.com/daviddavo/blog.ddavo.me/blob/main/layouts/shortcodes/figure.html

Problem with Image-Markdown definition in 'Content:' parameter

Bug description:

• a included image in content as markdown is reported as 'image not found' (see steps below)

Steps to reproduce the behaviour:

• hugo version : v0.110.0
• Theme "hugo-PaperModX' actual version master from 2023-02-15
• the image 'honeycomb.png' was stored in project root folder 'static'
• no WARN or ERROR with original 'PaperMod' theme

define parameter 'Content' in file 'config.yml':

params:
  homeInfoParams:
    Content: 'some text ![my-logo](honeycomb.png) some other text'

reported Error:

WARN 2023/02/15 12:33:56 No image found for honeycomb.png from {%!s(*helpers.DistinctLogger=&{0xc001dc0600 {{0 0} 0 0 0 0} map[]})}

Expected behaviour:
image is found and visible ...and no ERROR or WARN reported)

(successful tested with original 'PaperMod' theme)

Additional remark

• the same error if I include the image-tag in 'Title:' parameter

Provide compact style option for list layout

[BUG] Site logo does not show

Describe the bug
When the site logo is set like the below, it does not show when the site is rendered.

label:
  text: "site name"
  icon: "logo.svg"

• Device/Os: macOS
• Type:: Desktop
• Browser and version: Firefox 105.0.1 & Chromium 106.0.5249.61
• Hugo Version: v0.104.2+extended
• Theme Version: master

Steps to reproduce the behavior:

1. Set the label and icon as it is in the documentation.
2. hugo server
3. Logo does not show

Expected behavior:
The logo should show up left to the site's title.

Screenshots
N/A

Additional context
The header partial's logic is a bit different than the upstream PaperMod one.

Has this fork been abandoned?

I've been a user of this fork for a long time due to the side ToC, but it appears abandoned. Could you please let us know if there is any future planned maintenance or improvements here @reorx?

[Feature request] Allow to copy link to a particular anchor

PaperMod already somewhat has this feature (I can click on the # next to an anchor and then copy the URL)

I think it would be great if PaperModX also implemented that (and maybe also a direct "copy to clipboard" button if js is enabled ?)

Allow using icons from site's data dir

How to left align images by default

Images (Figures) are center aligned by default. How can we set images to be left aligned by default?

[BUG] The selected menu text color is the same as background in dark mode

Describe the bug

• Device/Os: [e.g. Android 10]
• Type: [e.g. Desktop/Mobile]
• Browser and version [e.g. Chrome 86.0]:
• Hugo Version [ >=0.83.0 expected]:
• Theme Version [e.g. v4.0, master, or commit-id ]:

Steps to reproduce the behavior:

Expected behavior:

Screenshots

Like the screenshot above, the "归档" menu tag has disappeared when selected.

Additional context

toc text wrap behaviour weird [BUG]

Not Support MKV Format?

Hello.
Actually this is not a complaint, this is just a question. Hugo or maybe this Theme doesn't support MKV videos format?

Shortcodes:

Result:

Is InstantClick a future-proof solution?

Hi there,

InstantClick provides nice features but:

• the Github repo is inactive for 6 years
• the SSL certificate is broken on the main site

Is it a future-proof piece of JS to embed in papermodX?

Menu link text too dark when active and in dark mode

The menu link text color is dark when active and the theme is in dark mode, which makes it illegible. Here are screenshots with the Tags link active.

Dark Mode:

Light Mode:

[BUG] The code in code block can't align with the line number in iOS mobile devices

Describe the bug

• Device/Os: iOS15.6
• Type: Mobile
• Browser and version [e.g. Chrome 86.0]: Safari, Firefox 103.1, Chrome 104.0
• Hugo Version [ >=0.83.0 expected]: v0.101.0+extended
• Theme Version [e.g. v4.0, master, or commit-id ]: 61452c1

Steps to reproduce the behavior:

Use a browser(no matter what: Safari, Firefox or Chrome) in an iOS mobile device to open a page that has a least one code block with line numbers.

Expected behavior:

The code lines should align with the line numbers.

Screenshots

Safari:

Firefox:

Chrome:

If you disable the markup.highlight.lineNos in config.yaml, the code is fine with line numbers:

Additional context

If you need further testing, feel free to use this example page: https://58bed0b1.my-hugo-blog.pages.dev/posts/chaosblade-specific-cpu-load/

Feature Request: Implement Optional Hamburger Menu

Implementing Optional Hamburger Menu could be a nice touch, if possible.

[Feature request] Add "Pinned" icon when a post is pinned using `weight` front-matter

Could use the simple-icon for "Pinboard" as the icon if desired, but would be great for pinned posts to clearly reflect that (as normally posts are sorted by publish date):

<svg role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><title>Pinboard</title><path d="M13.352 14.585l-4.509 4.614.72-4.062L3.428 7.57 0 7.753 7.58 0v2.953l7.214 6.646 4.513-1.105-4.689 4.982L24 24l-10.648-9.415z"/></svg>

Could also just add [pinned] similar to how it's done with draft posts ATM (I'll see if I can do this myself).