Skip to content

Preview TNH Scholar Theme

Quick guide to preview the custom zen-inspired documentation theme.

Quick Preview

Build and serve the documentation locally:

# Build the documentation
poetry run mkdocs build

# Serve locally with live reload
poetry run mkdocs serve

Then open http://127.0.0.1:8000 in your browser.

Theme Features to Test

Visual Elements

  1. Color Palette
  2. Dark sumi ink background (#1a1a1a)
  3. Warm rice paper text (#e8e4d8)
  4. Bamboo green accents (#7a9b76)

  5. Check contrast and readability

  6. Typography

  7. Source Serif 4 headings (elegant, lightweight)
  8. Inter body text (clean, professional)

  9. JetBrains Mono code (developer-friendly)

  10. Spacing

  11. Generous breathing room between sections
  12. Comfortable reading width (48rem max)
  13. Organic padding and margins

Interactive Elements

  1. Navigation
  2. Hover effects on links (bamboo green underline)
  3. Active page highlighting

  4. Smooth page transitions

  5. Code Blocks

  6. Copy button functionality
  7. Syntax highlighting with zen gold

  8. Left border in bamboo green

  9. Search

  10. Dark theme integration
  11. Suggestion popups
  12. Result highlighting

Content Types

Test the theme with different content:

  1. Headers (h1-h6)
  2. Lists (bulleted, numbered, task lists)
  3. Tables (check hover effects)
  4. Blockquotes (lotus pink border)
  5. Admonitions (note, tip, warning, danger)
  6. Code (inline and blocks)
  7. Links (internal and external)

Sample Content

Visit these pages to see theme in action:

Customization

Adjust Colors

Edit docs/stylesheets/tnh-zen.css:

:root {
  /* Change any color variable */
  --tnh-bamboo-green: #7a9b76;  /* Primary accent */
  --tnh-meditation-blue: #6b8e9e; /* Links */
  --tnh-zen-gold: #c9a961;      /* Code */
}

Modify Spacing

:root {
  --tnh-space-breath: 2rem;   /* Section spacing */
  --tnh-space-pause: 1.5rem;  /* Element spacing */
  --tnh-space-moment: 1rem;   /* Internal padding */
}

Change Fonts

Edit mkdocs.yaml:

theme:
  font:
    text: Inter              # Body font
    code: JetBrains Mono     # Code font

For headings, edit docs/overrides/main.html Google Fonts import.

Browser Testing

Test across browsers for consistency:

  • Chrome/Edge (Chromium)
  • Firefox
  • Safari
  • Mobile browsers (responsive design)

Dark Mode

The theme is designed for dark mode by default. To add light mode support, you would need to create alternate color schemes in mkdocs.yaml:

theme:
  palette:
    # Dark mode (default)
    - scheme: slate
      toggle:
        icon: material/brightness-4
        name: Switch to light mode
    # Light mode (inverted palette)
    - scheme: default
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode

Performance

Check the theme performs well:

  1. Page Load: Should be fast with minimal CSS
  2. Smooth Scrolling: Anchor links scroll smoothly
  3. Transitions: Hover effects are smooth (0.3s)
  4. Font Loading: Web fonts load progressively

Accessibility

Verify accessibility features:

  1. Contrast Ratios: All text meets WCAG AA standards
  2. Focus Indicators: Bamboo green outline on focus
  3. Keyboard Navigation: Tab through all interactive elements
  4. Screen Readers: Semantic HTML structure

Troubleshooting

CSS Not Loading

# Clear the site directory and rebuild
rm -rf site/
poetry run mkdocs build

Fonts Not Showing

Check Google Fonts loaded in browser DevTools: 1. Open Network tab 2. Filter by "fonts.googleapis.com" 3. Verify Inter, Source Serif 4, and JetBrains Mono loaded

Colors Look Wrong

Verify Material theme version: 

poetry show mkdocs-material

Should be compatible with Material 9.x+

Production Deployment

Before deploying:

  1. Build with strict mode: poetry run mkdocs build --strict
  2. Test all links: Run lychee link checker
  3. Verify responsive: Test mobile layouts
  4. Check performance: Use Lighthouse audit

Feedback

The theme is designed to be minimal, peaceful, and functional. Adjust as needed while maintaining:

  • Dark backgrounds for reduced eye strain
  • Warm, organic color palette
  • Generous spacing for breathing room
  • Clear visual hierarchy
  • Professional yet approachable aesthetic

Walk mindfully through the documentation.