Tufted Blog Template

简体中文 | English

This is a static website building template based on Typst and Tufted, providing step-by-step guidance to build a clean and beautiful personal website, blog, and resume.

If you want to quickly experience the website style, you can visit Demo Website. Update log available at Changelog .

If you are a complete beginner, you may encounter some new concepts and might be using the terminal and command line for the first time. Don't be afraid, this project requires no prior knowledge and is very beginner-friendly.
When you encounter unfamiliar concepts or operations, read the documentation, ask AI, and search online.
If you encounter any issues, you can: check the Wiki Documentation, ask questions and discuss in Discussions, or submit feedback in Issues.

✨ Features

🚀 Write content using Typst, simple and powerful, with extremely fast compilation
🎨 Design based on Tufte CSS, minimalist and content-first, providing a clear and immersive reading experience
📦 Built-in cross-platform build script based on Python, supporting incremental compilation
📝 Support for generating both HTML pages and PDF documents, with support for linking to PDFs
🌐 Built-in GitHub Actions workflow for one-click website deployment
🌙 Support light/dark mode automatic selection and one-click switching
📄 Rich examples and documentation, no prior knowledge required, start writing after learning Typst basics

📦 Environment Setup (One-time Only)

This project only depends on Typst and Python (using uv for Python is recommended). Typst is used to compile web pages, and the Python script is used to automate the build process.

0. Prerequisites

To enable version control, automated builds, and a better writing experience, it's recommended to prepare the following:

Have a GitHub account
Understand what a terminal is and be able to run commands in the terminal (see Wiki page)
Install Git for code management and remote pushing (see Wiki page)
Use VS Code or your preferred code editor, and install the Tinymist plugin for Typst language support (see Wiki page)

1. Install Typst

If your system already has Typst CLI installed, you can skip this step.

Typst is an emerging modern markup language typesetting system designed to be a modern alternative to LaTeX, while being simpler to learn, faster to compile, and more user-friendly. This project uses Typst's experimental HTML export feature to compile .typ plain text source files into web pages.

Method 1: Download the executable directly from the Typst download page. You need to download the archive and extract it to a folder that is in your PATH environment variable.
- Windows users (recommended) can extract it to a path of your choice, then add that path to the PATH environment variable, see Wiki page for details.
- macOS / Linux users can extract it to /usr/local/bin or another directory already added to PATH, see Wiki page for details.
Method 2: Install using a package manager.
- Windows:
  - Using winget: winget install typst
  - Using Scoop: scoop install typst
  - Using Chocolatey: choco install typst
- macOS (recommended):
  - Using Homebrew: brew install typst
- Linux: Use your usual package manager to install (recommended).

After installation, open a terminal and run typst --version. If it displays the version number, the installation was successful.

2. Install Python

If your system already has Python >= 3.6 installed, you can skip this step.

This project uses a Python script build.py to automate the build process. Theoretically, you only need to have Python installed to run it, but to avoid various Python environment issues, it's recommended to use uv to run the script. uv is an extremely fast Python package and project manager that simplifies Python installation, dependency management, and script execution.

You can install uv following the instructions below:

Windows: Open a terminal and run the following command:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

macOS/Linux: Open a terminal and run the following command:
```
curl -LsSf https://astral.sh/uv/install.sh | sh
```
Or use other methods mentioned in the official documentation.

After installation, you can run uv --version in the terminal to verify the installation was successful. Once uv is installed, you no longer need to manually install Python or worry about environment issues—uv will handle everything.

🚀 Quick Start

The entire template workflow is as follows:

Create your GitHub repository using this template
  ↓
Clone your repository locally
  ↓
Modify .typ files
  ↓
Run build.py
  ↓
Local preview
  ↓
When satisfied, git push to your GitHub repository
  ↓
GitHub Actions automatically deploys
  ↓
Visit username.github.io

1. Clone the Project

Click the green button [Use this template] -> Create a new repository in the upper right corner of this page to copy this template to your own repository, and (very important) name the repository <your-github-username>.github.io.
Clone your own repository code to your computer. First, you need to choose a folder as your working directory, then open a terminal in that path and run the following command (replace <your-github-username> with your GitHub username):

git clone https://github.com/<your-github-username>/<your-github-username>.github.io.git

For example, if I want to store the website project in the D:\My-Website\ directory, first navigate to D:\, open a terminal in that path, and then run:

git clone https://github.com/Yousa-Mirage/Yousa-Mirage.github.io.git

This will create the D:\Yousa-Mirage.github.io\ folder and download the project files to that directory. You can then rename the folder to your preferred name, such as D:\My-Website\. This will be our local website project directory going forward, where we'll edit documents, run build scripts, and interact with the GitHub remote repository.

2. Build the Website

Navigate to your website project directory, open a terminal in the current path, and run the following command:

uv run build.py build

If you don't have uv installed, you can run the script directly with Python:

python build.py build

This command will compile the .typ files in content/ to HTML files and output them to the _site/ directory. The _site/ directory is what your website looks like locally. After modifying files, run this command again for incremental compilation.

3. Local Preview

The HTTP server will occupy the current terminal window, so it's recommended to open a new terminal window in that path to run the preview command.

💡 Quick workflow tip: You can run uv run build.py preview in one terminal and then run uv run build.py build in another terminal to compile your changes. The web page will automatically refresh, allowing for real-time preview without the need to repeatedly run the preview command to restart the server.

You can run the following command to start a local preview server:

uv run build.py preview

# Or run directly with Python
python build.py preview

Preview Command Explanation

preview will first try to run uvx livereload _site. This command uses uv to run a tool called livereload, which uses the _site/ directory as the website root and starts an HTTP live server on local port 8000. If you don't have uv installed, it will fall back to using Python's built-in HTTP server: python -m http.server 8000 --directory _site.

The preview server uses port 8000 by default, but you can specify a different port using the -p/--port parameter, for example:

uv run build.py preview -p 12345

The browser should open automatically, or you can manually open a browser and visit http://localhost:8000 to view the default web page. I've written more documentation and example content in the default web page (i.e., the content in content/), which you can explore and modify on your own.

The local website content you see should be identical to the Demo Website.

You can refer to the content and resources on the Wiki page to learn about Typst.

4. Write Web Pages with Typst and Deploy the Website

After understanding the web page structure and how to write, you can replace the content in content/ with your own content to build your own website.

Modify Configuration: Edit config.typ to set the website title and navigation bar. You can also place a favicon.ico file in assets/ as your website's tab icon.
Add Articles: Create new .typ files in content/. You can refer to the current content/ for examples.
Generate PDFs: If the filename contains PDF (e.g., CV-PDF.typ), the build script will automatically compile it into a PDF file, and you can add links in the web page pointing to that PDF.
Deploy Website: Configure Pages in your GitHub repository, push the modified content to GitHub, and GitHub Actions will automatically build, deploy, and update the website. For details, see the Wiki page.

5. Project Updates

This template provides an Update GitHub Actions workflow for importing feature updates from the upstream template repository (which is this repository). For details, please refer to the Wiki page.

📂 Project Structure

Tufted-Blog-Template/
├── .github/workflows      # GitHub Actions for automated build and deployment
├── _site/                 # Build output directory (auto-generated)
├── assets/                # Static resources (CSS, JS, fonts, icons, etc.)
│   ├── tufted.css             # Main stylesheet
│   ├── custom.css             # Custom stylesheet (user-editable)
│   ├── copy-code.js           # Code block copy functionality
│   ├── line-numbers.js        # Code line number display
│   └── format-headings.js     # Heading formatting
├── content/               # Website content source files (.typ)
│   ├── index.typ              # Website homepage
│   ├── Blog/                  # Blog pages
│   ├── CV/                    # Resume pages
│   ├── Docs/                  # Documentation pages
│   └── .../                   # Add or modify other pages as needed
├── tufted-lib/            # Typst style library and feature modules
│   ├── tufted.typ             # Main template and configuration
│   ├── layout.typ             # Page layout definitions
│   ├── math.typ               # Mathematics formula handling
│   ├── figures.typ            # Image and chart handling
│   ├── refs.typ               # Reference and bibliography handling
│   └── notes.typ              # Footnotes and margin notes handling
├── build.py               # Python build script
└── config.typ             # Website global configuration

🔗 Notes

This template is based on the Typst package Tufted developed by Vsevolod Shegolev, with some style and functionality modifications to better support Chinese content, including:

Modified some text styles to adapt to Chinese typesetting conventions
Fine-tuned a large number of style details, enhanced dark mode, and optimized the display effects of various elements
Added directory jump support
Optimized code block styles, added line numbers and copy functionality
Added Python build script for cross-platform build support
Added PDF build support, allowing compilation of PDF documents and linking to web pages
Added website favicon support
Added detailed usage instructions and code comments to help users quickly develop
...

This template project is open source under the MIT License.

FilesExpand file tree

README_en.md

Latest commit

History