<p align="center"> <a href="CONTRIBUTING.md#pull-requests"> <img src="https://img.shields.io/badge/PRs-welcome-0?style=flat-square&labelColor=202b2d&color=087e96" alt="PRs welcome"></a> <a href="https://github.com/welpo/tabi/graphs/contributors"> <img src="https://img.shields.io/github/contributors/welpo/tabi?style=flat-square&labelColor=202b2d&color=087e96" alt="Contributors"></a> <a href="https://github.com/welpo/tabi/forks"> <img src="https://img.shields.io/github/forks/welpo/tabi?style=flat-square&labelColor=202b2d&color=087e96" alt="Forks"></a> <a href="https://github.com/welpo/tabi/commits/main/"> <img src="https://img.shields.io/github/last-commit/welpo/tabi?style=flat-square&labelColor=202b2d&color=087e96" alt="Last commit"></a> <br> <a href="https://github.com/welpo/tabi/releases"> <img src="https://img.shields.io/github/v/release/welpo/tabi?style=flat-square&labelColor=202b2d&color=087e96" alt="Latest release"></a> <a href="https://welpo.github.io/tabi/blog/mastering-tabi-settings/"> <img src="https://img.shields.io/website?url=https%3A%2F%2Fwelpo.github.io%2Ftabi&style=flat-square&label=docs&labelColor=202b2d" alt="Documentation"></a> <a href="https://github.com/welpo/tabi/blob/main/LICENSE"> <img src="https://img.shields.io/github/license/welpo/tabi?style=flat-square&labelColor=202b2d&color=087e96" alt="License"></a> <a href="https://github.com/welpo/git-sumi"> <img src="https://img.shields.io/badge/clean_commits-git--sumi-0?style=flat-square&labelColor=202b2d&color=087e96" alt="Clean commits"></a> <a href="https://isitmaintained.com/project/welpo/tabi"> <img src="https://isitmaintained.com/badge/resolution/welpo/tabi.svg" alt="Average time to resolve an issue"></a> <a href="https://isitmaintained.com/project/welpo/tabi"> <img src="https://isitmaintained.com/badge/open/welpo/tabi.svg" alt="Percentage of issues still open"></a> </p>

🌱 tabi

An accessible Zola theme with search, multi-language support, optional JavaScript, a perfect Lighthouse score, and comprehensive documentation. Crafted for personal websites and blogs.

[!TIP] Want to start blogging right away? Use the tabi-start template to get a complete site up and running in minutes.

See a live preview (and the theme's documentation) here.

Explore the Sites Using tabi section to see real-world applications.

tabi (旅, /<span title="/t/: 't' in 'sty'">t</span><span title="/ɐ/: a sound between 'a' in 'sofa' and 'u' in 'nut'">ɐ</span><span title="/ˈ/: primary stress mark, indicating that the following syllable is pronounced with greater emphasis">ˈ</span><span title="/b/: 'b' in 'cab'">b</span><span title="/i/: 'i' in 'fleece'">i</span>/): Journey.

tabi has a perfect score on Google's Lighthouse audit:

Features

• [X] Set any language as default. Set your base site to Chinese, Spanish, French, Hindi… or any other supported language. The theme's interface will be translated accordingly.
• [X] Integration with remote repositories on GitHub, GitLab, Gitea & Codeberg for commit history and showing the site source.
• [X] Series support for creating sequential content like tutorials, courses, and multi-part stories.
• [X] Dark and light themes. Defaults to the OS setting, with a switcher in the navigation bar.
• [X] Thorough documentation. See Mastering tabi Settings: A Comprehensive Guide.
• [X] Perfect Lighthouse score (Performance, Accessibility, Best Practices and SEO).
• [X] Comprehensive multi-language support. Add as many languages as you wish.
• [X] Support for comments using giscus, utterances, Hyvor Talk, or Isso.
• [X] Indieweb ready with microformats, hcard and webmentions support.
• [X] Code syntax highlighting with colours based on Catppuccin Frappé.
• [X] Mermaid support to create diagrams and charts with text.
• [X] Local search with an accessible, multi-lingual interface.
• [X] Custom Twitter card and automatic Open Graph tags.
• [X] Anonymous like buttons powered by iine.
• [X] KaTeX support for mathematical notation.
• [X] Stylized and human readable Atom feed.
• [X] Stylized and human readable sitemap.
• [X] Mail encoding for spam protection.
• [X] All JavaScript can be fully disabled.
• [X] Customizable Table of Contents.
• [X] Customizable secure headers.
• [X] Copy button for code blocks.
• [X] Quick navigation buttons.
• [X] Custom copyright notice.
• [X] Custom canonical URLs.
• [X] Custom shortcodes.
• [X] Customizable skins.
• [X] Social media cards.
• [X] Responsive design.
• [X] Projects page.
• [X] Archive page.
• [X] Pinned posts.
• [X] Social links.
• [X] Tags.

Installation

[!NOTE] The fastest way to create a new site is to use the tabi-start template. This gives you a complete blog setup with all the essential configuration ready to go.

Manual installation

To add tabi to you existing Zola site:

0. Initialize a Git repository in your project directory (if you haven't already):

git init

1. Add the theme as a git submodule:

git submodule add https://github.com/welpo/tabi.git themes/tabi

Or clone the theme into your themes directory:

git clone https://github.com/welpo/tabi.git themes/tabi

Required configuration

2. Enable the theme in your config.toml:

theme = "tabi"

3. Set a title in your config.toml:

title = "Your Site Title"

4. Configure code block highlighting in your config.toml:

[markdown.highlighting]
theme = "catppuccin-frappe"
style = "class"

5. Create a content/_index.md file. This file controls how your home page looks and behaves. Choose one of the following options:

   Option A: Serve posts from /:

   +++
   title = "Home"
   paginate_by = 5  # Show 5 posts per page.
   +++
   

   • This will display posts in content/ with pagination.

   Option B: Serve posts from a different path (e.g., blog/):

   +++
   title = "Home"
   # Note we're not setting `paginate_by` here.
   
   [extra]
   section_path = "blog/_index.md"  # Where to find your posts.
   max_posts = 5  # Show 5 posts on the home page.
   +++
   

   • This will display the latest 5 posts from the blog/ section.
   • Do not set paginate_by if you choose this option.
   • Use the full path to the section's _index.md file. Using section_path = "blog/" will not work.

[!WARNING] Do not set both paginate_by and section_path in content/_index.md.

These settings are mutually exclusive and using both may result in no posts being displayed.

6. If you want an introduction section (see screenshot above), add these lines to content/_index.md:

[extra]
header = {title = "Hello! I'm tabi~", img = "img/main.webp", img_alt = "Your Name" }

The content outside the front matter will be rendered between the header title and the posts listing. In the screenshot above, it's the text that reads "tabi is a fast, lightweight, and modern Zola theme…".

7. If you want a multilingual site, you will need to set up each language. In config.toml, set the title and taxonomies for each language, like:

[languages.es]
title = "~/tabi"
taxonomies = [{name = "tags", feed = true}]

You will need an _index.{language_code}.md per language for each section (e.g. /blog or /projects) that you want