Tao

Tao is a content-first minimalist Jekyll theme for blogs, distributed as the Ruby gem jekyll-theme-tao and installable on GitHub Pages.

What is Tao?

Tao is a content-first minimalist Jekyll theme for blogs, built as a Ruby gem and designed to run in any standard Jekyll environment, including GitHub Pages via the jekyll-remote-theme plugin. It takes Markdown posts and pages as input and renders them into a clean, typography-focused blog layout with support for archives, comments, analytics, and math typesetting. The theme is maintained by vfvong and published on GitHub at vfvong/jekyll-theme-tao.

Key Features

• Light and dark mode — Automatically switches based on the visitor's prefers-color-scheme setting, with no JavaScript or configuration needed.
• MathJax support — Render LaTeX math in posts by setting math: true in the front matter of a page; disabled by default to keep pages fast.
• Disqus comments — Enable discussion on posts by setting a Disqus shortname in _config.yml.
• Google Analytics 4 — Add a Measurement ID in _config.yml to track site traffic.
• Pure-Liquid archive pages — Create archive pages grouped by year, category, or tag using the built-in archive layout and a type field.
• Font Awesome icons — Social links use Font Awesome classes, so no SVG files are needed for icons.
• Custom head injection — Drop a _includes/custom-head.html file into your repo to add extra scripts or meta tags without overriding the theme.
• Sass variable customization — Change colors and fonts by copying and editing _sass/tao/_variables.scss.

Who is it for?

• Bloggers who want a minimal, content-first layout that puts writing at the center.
• Developers hosting on GitHub Pages who need a theme that installs quickly via gem or remote theme.
• Technical writers who need MathJax for equations and archives for long-form content.
• Personal site owners who want a simple navigation and social links without a heavy theme.

What can you do with Tao?

• Publish a blog — Write posts in Markdown, and Tao renders them with a clean reading experience and automatic categories/tags archives.
• Add comments and analytics — Connect Disqus for reader engagement and Google Analytics 4 for traffic insights.
• Customize without forking — Override navigation and social links via _data files, inject custom head content, and adjust Sass variables.

How does Tao work?

Installation follows the standard Jekyll theme workflow: add gem "jekyll-theme-tao" to your Gemfile, set theme: jekyll-theme-tao in _config.yml, and run bundle install. For GitHub Pages, add jekyll-remote-theme and set remote_theme: vfvong/jekyll-theme-tao. Then configure navigation in _data/navigation.yml and social links in _data/social.yml.

FAQ

Is Tao free to use?

Yes. Tao is open source under the MIT License, so it is free to use for personal and commercial projects.

How do I install Tao on GitHub Pages?

Add jekyll-remote-theme to your Gemfile, then set remote_theme: vfvong/jekyll-theme-tao in your _config.yml. The theme will be fetched from GitHub when your site builds.

How do I turn on MathJax?

MathJax is off by default. On any page where you want math rendering, set math: true in the front matter. The theme then loads MathJax for that page.

Does Tao have built-in dark mode?

Yes. Tao supports light and dark mode automatically using the CSS prefers-color-scheme media query, so it follows the visitor's system setting with no manual toggle.

How do I customize the theme's colors?

Copy _sass/tao/_variables.scss into your own _sass directory and edit the variable values. The theme's Sass will pick up your overrides without requiring you to copy all the CSS.