Theme Configuration Reference

Updated 2026-03-04
#reference #vaultex #config #settings

Every knob and toggle in themes/vaultex/_config.yml, explained with examples and the default value for each option.

The full config lives at themes/vaultex/_config.yml. Copy the block you need, tweak the value, and run hexo server to see it live. Settings are grouped below the same way they appear in the file.

Vault Identity

1
vault_name: vaultex

Sets the display name shown in the browser tab title and the vault header. Change this to match your site’s name.

1
homepage_subtitle: Recent Notes

The label shown in the tab bar and breadcrumb trail when on the homepage. Common alternatives: All Posts, Notes, Writing.

1
vault_title_position: 2

Controls where the vault title appears:

Value Position
1 Top — rendered inside the page header
2 Bottom — rendered in the footer (Obsidian-style)

Customize

1
2
3
4
5
customize:
  font_size: 15
  code_font_size: 14
  max_content_width: 720
  highlight: obsidian

font_size

Base font size in pixels for all body text. Default 15. Adjust between 13–18 depending on your preference.

code_font_size

Font size in pixels applied to code blocks and inline code. Default 14. Keep this slightly smaller than font_size for visual rhythm.

max_content_width

Maximum width of the post content area in pixels. Default 720. Wider values (860, 960) suit data-heavy or image-heavy posts; narrower values improve readability for long-form prose.

highlight

Syntax highlighting theme applied to all code blocks. Vaultex bundles 70+ themes from highlight.js. Popular choices:

Theme Character
obsidian Dark blue-grey (default)
github-dark GitHub dark mode
monokai Classic Monokai
nord Arctic Nord palette
dracula Purple/pink Dracula
tokyo-night-dark Tokyo Night
atom-one-dark Atom One Dark 
1
2
3
4
5
6
7
8
9
10
nav_items:
  - label: Home
    path: /
    icon: home
  - label: Archive
    path: /archives/
    icon: archive
  - label: RSS
    path: /atom.xml
    icon: rss

Defines the links shown in the Navigation section of the left sidebar. Each item takes three fields:

  • label — display text
  • path — the URL path or external URL
  • icon — icon name (see available icons in themes/vaultex/source/icons/)

Add, remove, or reorder entries freely. External links are supported.

1
2
3
nav_icons: true
category_icons: true
links_icons: true

Toggle icons on or off independently for each sidebar section:

Key Controls
nav_icons Icons next to Navigation links
category_icons Folder/file icons in the Categories tree
links_icons Icons next to Links section entries

Set any of these to false to show text-only labels in that section.

1
2
sidebar_explorer_style: 2
sidebar_explorer_numbers: false

Controls the visual style of the entire left sidebar explorer:

Value Style
1 Classic — NAVIGATION / CATEGORIES / LINKS, uppercase, bold, with dividers
2 Obsidian-style — Navigation / Categories / Links, mixed-case, no dividers

Only applies when sidebar_explorer_style: 2. When true, section labels are prefixed with zero-padded numbers (00 Navigation, 10 Categories, 20 Links, 30 …) to mimic Obsidian’s vault folder numbering convention.

Post List

1
2
3
4
5
6
7
posts_per_row: 1
show_date: true
show_tags: true
max_tags: 6
show_excerpt: true
show_thumbnail: true
thumbnail_style: left

posts_per_row

Value Layout
1 Single-column list
2 Two-column card grid

show_date

Show or hide the publication date on each post list item. Default true.

show_tags

Show or hide tags on each post list item. Default true.

max_tags

Maximum number of tags rendered per post list item. Default 6. Tags beyond this count are silently truncated.

show_excerpt

Show the post excerpt (text before <!-- more -->) in the list. Default true. Set to false for a compact title-only list.

show_thumbnail

When true, renders the post’s thumbnail front-matter image in the list card. Requires the thumbnail field to be set in each post’s front-matter.

thumbnail_style

Controls where the thumbnail appears within the card:

Value Position
left Left of the of post card
right Right of the post card
inline Inside the left of the card content

Post Page

1
show_post_thumbnail: true

When true, the post’s thumbnail image is rendered as a full-width hero image at the top of individual post pages. Set to false to suppress the hero and keep the post clean.

1
2
3
4
5
sidebar_right:
  toc: true
  toc_depth: 4
  show_related: true
  show_tags_panel: true

toc

Generate a Table of Contents from the post’s headings and display it in the right panel. Scrolling through the post highlights the active heading. Default true.

toc_depth

Maximum heading depth included in the TOC:

Value Headings included
1 H2 only
2 H2–H3
3 H2–H4
4 H2–H5 (default)

Show a Related Posts block in the right panel based on shared tags. Default true.

show_tags_panel

Show a Tag Cloud in the right panel. Default true.

1
2
3
4
social_links:
  - label: GitHub
    url: https://github.com/rashidmya/vaultex
    icon: github

Adds icon links to the activity bar (slim strip on the far left). Each entry takes:

  • label — tooltip text on hover
  • url — full URL including protocol
  • icon — icon name matching a file in themes/vaultex/source/icons/

Add as many entries as needed. Common icons: github, twitter, mastodon, linkedin, rss, mail.

Vercel Analytics

1
vercel_analytics: false

Set to true when the site is deployed on Vercel to inject the Vercel Analytics script automatically. Leave false for all other hosting providers or local development.

Complete Default Config

Here is the full _config.yml with every option at its default value, ready to copy:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
# ============================================================
# Vaultex Theme Configuration
# ============================================================

vault_name: vaultex

homepage_subtitle: Recent Notes

vault_title_position: 2

customize:
  font_size: 15
  code_font_size: 14
  max_content_width: 720
  highlight: obsidian

nav_items:
  - label: Home
    path: /
    icon: home
  - label: Archive
    path: /archives/
    icon: archive
  - label: RSS
    path: /atom.xml
    icon: rss

nav_icons: true
category_icons: true
links_icons: true

sidebar_explorer_style: 2
sidebar_explorer_numbers: false

posts_per_row: 1
show_date: true
show_tags: true
max_tags: 6
show_excerpt: true
show_thumbnail: true
thumbnail_style: left

show_post_thumbnail: true

sidebar_right:
  toc: true
  toc_depth: 4
  show_related: true
  show_tags_panel: true

social_links:
  - label: GitHub
    url: https://github.com/rashidmya/vaultex
    icon: github

vercel_analytics: false