Frequently Asked Questions

Answers to the most common questions about using the ModernDuang theme.

1. How do I update the theme?

ModernDuang is distributed via npm, so updating is straightforward:

npm update hexo-theme-modernduang

After updating, run a clean build to ensure all changes take effect:

hexo clean && hexo server

Important: If you have customized any files inside themes/modernduang/ (CSS, JS, or layouts), those changes will be overwritten by the update. Always customize via your site's own files (see the Advanced Customization guide) rather than editing theme source files directly.

To check which version you are currently running:

npm list hexo-theme-modernduang

2. Dark mode isn't working. How do I fix it?

If the dark mode toggle seems broken or doesn't persist, go through this checklist:

Step 1: Check your config

Ensure dark mode is enabled in _config.modernduang.yml:

dark_mode:
  enable: true
  default: light

If enable is false, no dark mode toggle will appear and the site will stay in light mode.

Step 2: Clear localStorage

The theme stores the user's dark mode preference in the browser's localStorage. A stale or corrupted value can prevent the toggle from working. Open your browser's developer tools and run:

localStorage.removeItem('theme');

Then refresh the page.

Step 3: Check browser support

Dark mode requires prefers-color-scheme media query support. All modern browsers (Chrome 76+, Firefox 67+, Safari 12.1+, Edge 79+) support this. If you are using an older browser, update it.

Step 4: Check for CSS conflicts

If you have added custom CSS, ensure you are not overriding the dark mode styles. Custom styles that use hardcoded colors (e.g., color: #333) will not adapt to dark mode. Use CSS variables like var(--text-color) instead.

3. How do I set up Twikoo comments?

Twikoo is the comment system integrated into ModernDuang. Here is a step-by-step setup guide:

Step 1: Get an environment ID (envId)

Twikoo requires a backend deployment. You have two options:

Option A: Tencent Cloud CloudBase (recommended for users in China)

Go to Tencent Cloud CloudBase and create an environment.
Once created, go to the environment dashboard and copy the Environment ID.
Deploy Twikoo to your CloudBase environment following the official guide.

Option B: Vercel + MongoDB (recommended for international users)

Create a free MongoDB Atlas database.
Deploy Twikoo to Vercel using the official template.
Your envId will be the Vercel deployment URL (e.g., https://my-twikoo.vercel.app).

Step 2: Configure the theme

Add your envId to _config.modernduang.yml:

comments:
  twikoo:
    envId: https://your-twikoo-envid  # Your CloudBase envId or Vercel URL
    region: ap-shanghai                # Only needed for CloudBase; ignore for Vercel

Step 3: Verify

Start your Hexo dev server and open a post. You should see the Twikoo comment section at the bottom of the page. Leave a test comment to confirm everything works.

Tip: To disable comments on a specific post, add comment: false to that post's frontmatter.

4. How do I add Google Analytics or other tracking?

ModernDuang does not have a dedicated analytics config field — you inject tracking scripts through the footer.custom option.

Google Analytics (GA4)

Add the following to your _config.modernduang.yml:

footer:
  custom: |
    <script async src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXXXXX"></script>
    <script>
      window.dataLayer = window.dataLayer || [];
      function gtag(){dataLayer.push(arguments);}
      gtag('js', new Date());
      gtag('config', 'G-XXXXXXXXXX');
    </script>

Replace G-XXXXXXXXXX with your actual Google Analytics measurement ID.

Other tracking tools

The same pattern works for any tracking script — Baidu Tongji, Umami, Plausible, Microsoft Clarity, etc. Simply paste the provided <script> tag into footer.custom.

Advanced: Inject into `<head>`

Some scripts (like verification meta tags) need to go in <head>. For these, override the layout/layout.ejs template. See the Advanced Customization guide for instructions on safely overriding layout templates.

5. Why aren't my friend links showing?

If your friend links page is empty or missing some links, check these common issues:

Issue 1: Group name mismatch

The group field on each friend entry must exactly match a key in friendGroups:

# ✅ Correct — group name matches
friendGroups:
  技术伙伴: 🌟
  朋友们: 🤝

friends:
  - name: Example Blog
    url: https://example.com
    desc: A great blog
    avatar: https://example.com/avatar.png
    group: 朋友们              # Matches a key in friendGroups

# ❌ Wrong — group name doesn't match
friendGroups:
  技术伙伴: 🌟

friends:
  - name: Example Blog
    group: 技术达人              # Does not match "技术伙伴"

Issue 2: YAML indentation errors

YAML is sensitive to indentation. Ensure each friend entry is properly indented under friends::

# ✅ Correct indentation
friends:
  - name: Blog A
    url: https://a.com
    desc: Description
    avatar: https://a.com/avatar.png
    group: 朋友们

  - name: Blog B
    url: https://b.com
    desc: Description
    avatar: https://b.com/avatar.png
    group: 朋友们

Each entry starts with - name: at the same indentation level (2 spaces under friends:).

Issue 3: Empty friends array

If friends is an empty array or comments them out entirely, no links will show:

# ❌ No links defined
friends: []

6. How do I use a custom domain?

Custom domains are configured at the Hexo level, not the theme level.

Step 1: Add a CNAME file

Create a file named CNAME (no extension) in your Hexo site's source/ directory:

source/CNAME

Inside the file, write your custom domain:

blog.yourdomain.com

Hexo will copy this file to the output root on build.

Step 2: Configure DNS

At your domain registrar or DNS provider, add a CNAME record pointing your custom domain to your hosting provider's domain (e.g., <username>.github.io for GitHub Pages, or your Vercel/Netlify deployment URL).

Step 3: Update Hexo config

In your Hexo _config.yml, update the url field:

url: https://blog.yourdomain.com

This ensures all generated links use your custom domain.

Step 4: Update siteInfo

For the friend link exchange page to show the correct URL:

# _config.modernduang.yml
siteInfo:
  url: https://blog.yourdomain.com
  avatar: https://blog.yourdomain.com/avatar.png
  atom: https://blog.yourdomain.com/atom.xml

7. How do I change the primary color?

ModernDuang uses CSS custom properties for theming. The primary color is controlled by the --primary variable. Override it by injecting a <style> block via footer.custom:

# _config.modernduang.yml
footer:
  custom: |
    <style>
      :root {
        --primary: #ff6b6b;
      }
    </style>

Replace #ff6b6b with your desired color. This overrides the primary accent color used for:

Links
Buttons
Active navigation indicators
Highlighted elements
Progress bars

If you also want to adjust the dark mode variant, add a second block:

footer:
  custom: |
    <style>
      :root {
        --primary: #ff6b6b;
      }
      [data-theme="dark"] {
        --primary: #ff8e8e;
      }
    </style>

Tip: For a full list of customizable CSS variables, refer to the Advanced Customization guide.

8. Mermaid diagrams aren't rendering. What should I check?

Mermaid diagram support is built into ModernDuang but requires a frontmatter flag per post.

Step 1: Enable Mermaid in frontmatter

Add mermaid: true to the frontmatter of any post that contains a Mermaid diagram:

---
title: My Post with Diagrams
date: 2024-01-15
mermaid: true
---

Without this flag, the Mermaid JavaScript library is not loaded on the page, and diagrams will appear as raw code blocks.

Step 2: Check your diagram syntax

Ensure your Mermaid code blocks use the correct language identifier:

```mermaid
graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Do Something]
    B -->|No| D[Do Something Else]


The language identifier must be exactly `mermaid` (lowercase). Using `Mermaid` or other casing will not work.

### Step 3: Check the browser console

Open your browser's developer tools (F12) and look at the Console tab. Mermaid errors typically show:

- `Syntax error in graph` — Your Mermaid syntax has a mistake
- `mermaid is not defined` — The Mermaid library failed to load (check your network connection or `font.host` mirror settings if in China)

### Step 4: Verify the scripts directory

The theme's `scripts/mermaid.js` handles loading the Mermaid library. If you have overridden any theme scripts, ensure this file is intact.

---

## 9. How do I migrate from another Hexo theme?

Migrating to ModernDuang from another theme involves backing up your config and porting your settings:

### Step 1: Back up your current configuration

```bash
cp _config.yml _config.yml.backup
cp _config.old-theme.yml _config.old-theme.yml.backup  # If applicable

Step 2: Install ModernDuang

npm install hexo-theme-modernduang --save

Step 3: Switch the theme

In your Hexo _config.yml, change the theme name:

theme: modernduang

Remove or rename any old theme-specific config file (like _config.landscape.yml) to avoid conflicts.

Step 4: Copy the ModernDuang default config

cp node_modules/hexo-theme-modernduang/_config.yml _config.modernduang.yml

Step 5: Port your settings

Open your old theme config and _config.modernduang.yml side by side. Map your old settings to the new config:

Menu items — Move to the menu section
Social links — Move to profile.social
Comment settings — Reconfigure for Twikoo
Analytics scripts — Move to footer.custom
Custom CSS/JS — Re-integrate via footer.custom or layout overrides

Step 6: Test

hexo clean && hexo server

Browse your site thoroughly — homepage, posts, archives, tags, categories, and any custom pages — to make sure everything looks correct.

Note: Post content, tags, and categories are handled by Hexo itself and do not need migration. Only theme-specific settings need attention.

10. How do I add a new page?

Step 1: Create the page

Use Hexo's built-in page generator:

hexo new page about

This creates source/about/index.md (or index.html depending on your Hexo config).

Step 2: Add content

Edit the generated file with your page content. You can use standard Markdown, and the page will use the theme's page.ejs layout automatically.

Add the page to your _config.modernduang.yml menu:

menu:
  首页: /
  归档: /archives
  关于: /about          # Links to your new page

The page will appear in the top navigation bar. If the menu label matches a built-in icon name (like 关于), the corresponding icon will display automatically.

Customizing page layout

If you need a completely custom layout for a specific page, create a custom EJS template in your site's layout/ directory and point to it via the page's frontmatter:

---
title: My Custom Page
layout: my-custom-layout
---

11. Fonts aren't loading in China. What can I do?

If Google Fonts is slow or blocked, switch to a mirror:

font:
  enable: true
  host: https://fonts.font.im        # Chinese mirror 1

Alternative mirrors:

Mirror URL	Provider
`https://fonts.font.im`	Geekzu fonts mirror
`https://fonts.loli.net`	Loli CDN mirror
`https://fonts.geekzu.org`	Geekzu (aliased)

If you prefer to self-host your fonts:

Download the font files (.woff2 format recommended) from Google Fonts.
Place them in your Hexo source/fonts/ directory.
Set font.enable: false to disable Google Fonts loading.
Add @font-face declarations via footer.custom:

font:
  enable: false

footer:
  custom: |
    <style>
      @font-face {
        font-family: 'Inter';
        src: url('/fonts/inter-regular.woff2') format('woff2');
        font-weight: 400;
      }
      @font-face {
        font-family: 'Inter';
        src: url('/fonts/inter-bold.woff2') format('woff2');
        font-weight: 700;
      }
      body {
        font-family: 'Inter', sans-serif;
      }
    </style>

12. My profile avatar isn't showing. How do I fix it?

Check 1: Use an absolute URL

The avatar image should be an absolute URL, not a relative path:

# ✅ Correct — absolute URL
profile:
  avatar: https://example.com/images/avatar.png

# ❌ Wrong — relative path (may not resolve correctly on all pages)
profile:
  avatar: /images/avatar.png

If you must use a relative path, ensure it is reachable from all pages — paths starting with / are relative to your site root and should work, but absolute URLs are more reliable.

Check 2: Verify the image exists

Open the avatar URL directly in your browser. If it returns a 404 or network error, the image is not accessible. Upload your avatar to your site's source/ directory or use an image hosting service.

Check 3: Check for CORS issues

If your avatar is hosted on a different domain, that server must allow cross-origin requests (CORS). Most image hosting services (GitHub, Imgur, etc.) support this by default. If you are self-hosting on a CDN, verify your CORS headers.

Check 4: Image format

Use common web formats: .png, .jpg, .jpeg, .webp, or .svg. Unusual formats may not render in all browsers. A square image (1:1 aspect ratio) works best with the circular avatar display.

Still Having Issues?

If your question is not covered here, try these resources:

ModernDuang GitHub Repository — Report issues or browse the source
Hexo Documentation — For questions about Hexo itself
Configuration Reference — Full list of all theme options
Advanced Customization — Deep dives into customizing the theme

#Frequently Asked Questions

#1. How do I update the theme?

#2. Dark mode isn't working. How do I fix it?

#Step 1: Check your config

#Step 2: Clear localStorage

#Step 3: Check browser support

#Step 4: Check for CSS conflicts

#3. How do I set up Twikoo comments?

#Step 1: Get an environment ID (envId)

#Step 2: Configure the theme

#Step 3: Verify

#4. How do I add Google Analytics or other tracking?

#Google Analytics (GA4)

#Other tracking tools

#Advanced: Inject into <head>

#5. Why aren't my friend links showing?

#Issue 1: Group name mismatch

#Issue 2: YAML indentation errors

#Issue 3: Empty friends array

#6. How do I use a custom domain?

#Step 1: Add a CNAME file

#Step 2: Configure DNS

#Step 3: Update Hexo config

#Step 4: Update siteInfo

#7. How do I change the primary color?

#8. Mermaid diagrams aren't rendering. What should I check?

#Step 1: Enable Mermaid in frontmatter

#Step 2: Check your diagram syntax

#Step 2: Install ModernDuang

#Step 3: Switch the theme

#Step 4: Copy the ModernDuang default config

#Step 5: Port your settings

#Step 6: Test

#10. How do I add a new page?

#Step 1: Create the page

#Step 2: Add content

#Step 3: Add it to the navigation menu

#Customizing page layout

#11. Fonts aren't loading in China. What can I do?

#12. My profile avatar isn't showing. How do I fix it?

#Check 1: Use an absolute URL

#Check 2: Verify the image exists

#Check 3: Check for CORS issues

#Check 4: Image format

#Still Having Issues?