How to Configure This Website Template (Setup Guide)

Tutorial
Quarto
A detailed guide on how to configure your own personal academic website based on this project template.
Author

Perry

Published

December 23, 2025

1 Introduction

This is an academic personal website template built with Quarto, designed to help researchers quickly set up a personal website to share notes and blog posts. It has the following features:

  • Easy to Get Started: Just follow this tutorial and use modern AI tools for troubleshooting. No prior knowledge is required to easily complete website deployment.
  • Academic-Friendly: Supports LaTeX-style mathematical formulas, formula citations, and bibliography management, suitable for publishing academic content.
  • Lightweight and Clean: Primarily uses Quarto’s native features, minimizing custom CSS/HTML for easier understanding and secondary development.
  • AI Auto-Translation: Includes a built-in Python script that utilizes the DeepSeek API to achieve automatic synchronization of Chinese and English content.
  • Automated Deployment: Integrated with GitHub Actions for automatic, free building and publishing. No manual operations or personal server configuration is needed.
  • Responsive Design: Clean and aesthetically pleasing interface, adapted for both desktop and mobile devices.

1.1 Project Folder Structure and Function Explanation

Before starting the configuration, we need to understand the project’s folder structure and the functions of each part to facilitate comprehension of subsequent operations.

username.github.io/              # Your personal website project root directory
├─ _quarto.yml                   # Quarto website global configuration file
├─ index.qmd                     # Website homepage (source language version. Default is Chinese; the translation script automatically generates the other language version, see details later)
├─ requirements.txt              # Python dependency list
├─ README.md                     # Repository documentation
├─ references.bib                # Global bibliography database
├─ .gitignore                    # Git ignore file list
├─ .github/                      # GitHub configuration folder
│  └─ workflows/
│     └─ publish.yml             # GitHub Actions automation workflow, see details later
├─ content/                      # Main content folder, where you usually need to edit
│  ├─ en/                        # English content
│  │  ├─ _metadata.yml           # English folder metadata
│  │  ├─ index.qmd               # English homepage (if the source language is Chinese, this file is automatically generated by the translation script)
│  │  ├─ cv.qmd                  # English CV
│  │  ├─ blog/                   # English blog
│  │  ├─ notes/                  # English notes
│  │  │  ├─ _metadata.yml        # Notes folder metadata
│  │  │  └─ ...
│  │  └─ publications/           # English publications
│  └─ zh/                        # Chinese content
│     ├─ _metadata.yml           # Chinese folder metadata
│     ├─ cv.qmd                  # Chinese CV
│     ├─ blog/                   # Chinese blog
│     ├─ notes/                  # Chinese notes
│     └─ publications/           # Chinese publications
├─ assets/                       # Static resources
│  ├─ css/
│  │  └─ custom.css              # Custom styles
│  ├─ images/
│  │  └─ avatar.jpg              # Avatar and other images
│  └─ html/
│     ├─ footer.html             # Custom footer
│     └─ include_lang_switch.html # Language switcher
├─ scripts/                      # Automation scripts folder
│  ├─ README.md                  # Script documentation
│  ├─ sync_deepseek.py           # Auto-translation script
│  └─ tex2qmd.py                 # LaTeX to Quarto conversion script
└─ _site/                        # Generated static website (auto-generated, do not edit manually)

1.1.1 Supplementary Notes

  • Root directory index.qmd: The source file for the website homepage. It is written in Chinese by default (lang: zh). The translation script will automatically generate the English version to content/en/index.qmd. If you prefer writing in English, you can change lang to en, and the script will generate the Chinese version to content/zh/index.qmd.

  • _metadata.yml: Can be placed in any content subfolder (e.g., blog/, notes/) to define default metadata for all documents within that folder. See the later section “Configuration Hierarchy and Priority” for details.

  • _site/: The static website generated by Quarto after building. Do not edit manually.

2 Preparation

This tutorial assumes you already have a GitHub account. If you don’t, please visit the GitHub website to register for one. GitHub is the world’s largest code hosting platform, supporting version control, collaborative development, and automated deployment. You will use it to store your website source code, manage history, and implement automated building and publishing via GitHub Actions.

If you are a student from a non-computer science background, you might find the following tools unfamiliar. Don’t worry, these tools are well worth learning, and the time invested will not be wasted.

Suggestion: When you encounter unfamiliar terms (e.g., “git commit”, “pull request”), ask an AI directly (like ChatGPT or DeepSeek). For example: “I am a non-computer science student. Please explain in simple terms what Git is and how to use it in VS Code?”

Feel free to ask questions by creating an Issue in the comments section. This can also help others who come later.

2.1 Core Tools

This project requires downloading and installing the following tools:

  • VS Code: A powerful text editor. We will use it to write code, write articles, manage the project, and operate Git.

  • Quarto CLI: The engine that converts your Markdown articles into web pages.

  • Git: A version control tool used to synchronize changes to GitHub.

  • Python (Optional): Used to run the translation script locally. Please check “Add Python to PATH” during installation.

Please search for the installation and configuration of the relevant tools yourself; they will not be detailed here.

2.1.1 About VS Code

VS Code is essentially a text editor, but it has a rich plugin ecosystem—these plugins enable VS Code to “understand” various languages (syntax highlighting, error checking, auto-completion) or “transform” into various tools (Git client, Quarto editor, etc.). It is called an “Integrated Development Environment” (IDE).

However, VS Code and its plugins are only responsible for editing. The execution of code is handled by external tools installed on your computer (e.g., Python interpreter, TeX compiler).

For example: To write Python in VS Code, you need to install both:

  • Python plugin: Makes the editor recognize .py files and provides intelligent suggestions.
  • Python interpreter: The program that actually runs the code.

This tutorial focuses on Quarto website configuration. The detailed usage of the aforementioned tools is too lengthy to be covered here. If needed, it is recommended to search on your own or ask an AI. Considering the importance of Git for this project’s configuration and that students from non-computer science backgrounds might be less familiar with it, the following section will briefly introduce its value and learning suggestions.

2.1.2 About Git and GitHub: A Skill Worth Investing In

The main point here is to emphasize: Git is a skill very much worth learning.

What is the relationship between Git and GitHub?

  • Git: A version control tool installed on your computer, responsible for recording every change history of files.
  • GitHub: A cloud-based code hosting platform that can synchronize your local Git repository online, enabling backup, collaboration, and automated deployment.

Simply put: Git manages local history, GitHub handles cloud synchronization. Used together, your code has a complete version history and cloud backup.

Why is it worth learning?

  • Version History: Each “commit” saves a snapshot, allowing you to revert to any past version at any time.
  • Cloud Backup: After pushing to GitHub, your code won’t be lost even if your computer breaks.
  • Multi-device Synchronization: Push from your lab computer, pull at your dorm, and continue seamlessly.
  • Collaboration and Automation: GitHub supports multi-person collaboration and automated builds (like the automatic translation and deployment in this project).

Good News: VS Code Makes Git Simple

You do not need to remember complex command lines. VS Code has a built-in graphical Git interface—the “Source Control” panel in the left sidebar can handle 90% of daily operations: viewing changes, committing, pushing, pulling, all achievable with just a few clicks.

Learning Suggestions:

  • When you encounter an unfamiliar concept, ask an AI directly: “Please explain in simple terms what a Git commit means?”
  • Search for tutorial videos or articles to learn the basic operational workflow.

Git and GitHub are fundamental infrastructure in modern research. Whether you will be writing code, performing data analysis, or managing experimental records in the future, this skill will benefit you for life. Investing a few hours to learn it yields long-term efficiency gains. VS Code is also worth the investment, as it can greatly enhance your writing and programming efficiency.

2.3 Verify Installation

After ensuring the above tools are installed, please verify that Quarto is correctly installed. Open VS Code, select Terminal -> New Terminal from the top menu bar, enter the following command, and press Enter:

quarto --version

If a version number (e.g., 1.8.xx) is displayed, the installation is successful.

3 Configuration Steps

3.1 Fork the Project

First, you need to Fork this project template to your own GitHub account:

  1. Open the GitHub page of this project.
  2. Click the Fork button in the top right corner.
  3. Important: Change the repository name to your-username.github.io (e.g., zhangsan.github.io). This is necessary to enable the default GitHub Pages domain.
  4. (Recommended) Uncheck “Copy the main branch only” to copy the gh-pages branch (if it exists in the template repository).
  5. Click Create fork.

After forking, you will have your own independent copy that you can freely modify and configure.

Clone to Local: Open a terminal and run the following command (replace your-username with your GitHub username):

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

After cloning, open the folder with VS Code to start editing.

3.2 Configure AI Translation (DeepSeek)

This template uses the DeepSeek API for automatic translation. You need to configure an API Key to use this feature.

  1. Obtain a Key: Go to the DeepSeek Platform, register, and apply for an API Key (format: sk-xxxxx). New users typically have free credits.
  2. Configure GitHub Secrets:
  • Go to your GitHub repository page.
  • Click Settings -> Secrets and variables -> Actions.
  • Click New repository secret.
  • Name: DEEPSEEK_API_KEY
  • Secret: Paste your Key.

3.3 Key Initialization Steps

Before performing the first push, you must complete the following initialization configuration. Otherwise, the automation scripts may fail with errors.

Important Note: All the following commands must be run in the project’s root directory. If you have opened this project’s folder in VS Code, simply open the terminal (Terminal -> New Terminal) – it defaults to the project root directory.

3.3.1 Ensure Complete Directory Structure

Git has a characteristic: it does not track empty folders.

This means that if you create a new folder but haven’t placed any files in it, or if you delete all files from a folder, that folder will disappear when pushed to GitHub.

This can cause automation scripts (like the translation script) to fail with errors when running in the cloud because they cannot find the expected directory structure (e.g., content/en).

If you forked this project directly without deleting any files, then this should be fine, and you can skip this step.

Solution: Please ensure that the content/zh and content/en directories in this project, along with their subdirectories (e.g., blog, notes), contain at least one file. If they are empty, manually create an empty file named .gitkeep as a placeholder. You can use command-line operations:

# macOS / Linux / Git Bash:
touch content/en/.gitkeep

# Windows PowerShell:
New-Item -Path content/en/.gitkeep -ItemType File -Force

3.3.2 Initialize the Publishing Branch (gh-pages)

The project’s automation scripts will push the compiled HTML webpage files to the gh-pages branch. If this branch does not exist, the first deployment will fail.

Please run the following commands in the terminal to check and create it:

# 1. Check if the gh-pages branch already exists
git branch -a

# If the output already includes "remotes/origin/gh-pages", you can skip the following steps.
# Otherwise, continue executing the commands below to create the branch:

# 2. Create an empty orphan branch
git checkout --orphan gh-pages

# 3. Clear the staging area (the VS Code file list will become empty at this point—don't panic)
git rm -rf .

# 4. Create an empty commit
git commit --allow-empty -m "Initial gh-pages"

# 5. Push to remote
git push origin gh-pages

# 6. Switch back to the main branch
git checkout main

Tip: After executing step 3, the file list on the left side of VS Code will momentarily clear—this is normal. You have simply switched to an empty branch. After executing step 6 to switch back to main, all files will be restored.

3.3.3 Enable GitHub Permissions

New repositories have read-only permissions by default, which prevents writing back translation results (i.e., GitHub Actions cannot push the translated English files to your repository).

  1. Go to your project’s GitHub repository page -> Settings -> Actions -> General.
  2. Scroll to the bottom to Workflow permissions.
  3. Select Read and write permissions.
  4. Click Save.

3.3.4 Configure the GitHub Pages Branch

To ensure the website displays correctly, you need to tell GitHub which branch to deploy the pages from.

  1. Open your project’s GitHub repository page -> Settings -> Pages.
  2. Under Build and deployment:
    • Source: Select Deploy from a branch.
    • Branch: Select the gh-pages branch, keeping the folder as / (root).
  3. Click Save.

After configuration, wait a few minutes, and your website will be accessible at https://your-username.github.io! 🎉

Note: If the website does not display properly, you can check the deployment status under the Actions tab in your GitHub repository. Click on the most recent run record. If there is a red cross, click into it to view the specific error message and troubleshoot accordingly.

3.4 Configure the Comment System Giscus (Optional)

This template integrates the Giscus comment system. If you do not need comment functionality, please disable it following the tutorial below and skip this step.

How to completely disable comments? Open the _quarto.yml file, find the comments section, and delete or comment out that part of the code.

To configure comments, follow these steps:

  1. Enable Discussions:
    • Go to your project’s GitHub repository page -> Settings -> General.
    • Scroll down to the Features section.
    • Check the box for Discussions.
  2. Install the Giscus App:
    • Visit Giscus App.
    • Click Install and authorize it for this repository.
  3. Obtain Configuration Information:
    • Visit giscus.app.
    • Enter your repository address (e.g., username/username.github.io).
    • Under Discussion Category, select General.
    • Scroll to the bottom, where you will see the generated configuration code.
  4. Update the Configuration File:
    • Open the _quarto.yml file in the project root directory.
    • Find the comments -> giscus section.
    • Fill in the data-repo-id and data-category-id you obtained in the previous step into the corresponding positions:
    comments:
  giscus:
    repo: username/username.github.io  # Your repository name
    repo-id: R_kgDO...                 # Fill in data-repo-id
    category: General
    category-id: DIC_kwDO...           # Fill in data-category-id
  5. Personalization:
    • If you want to disable comments on certain pages (e.g., the homepage), simply add comments: false to the YAML frontmatter of that page.

3.5 Personalization

You need to modify the following files to change the information on this website to your own:

3.5.1 Modify Basic Information (_quarto.yml)

Open the _quarto.yml file in the root directory and modify the website title, description, and URL:

website:
  title: "Your Name"              # Title displayed in the top-left corner of the website
  site-url: "https://yourusername.github.io" # Your website address
  description: "Your personal introduction"

3.5.2 Modify the Homepage (index.qmd)

Open index.qmd in the root directory. This is your website’s landing page. Modify the title, avatar path, and contact information:

---
title: "Your Name"
lang: zh  # Source language: zh for Chinese, en for English
image: assets/images/avatar.jpg  # Replace with your avatar
about:
  template: trestles  # Template style, options: jolla, trestles, solana, marquee, broadside
  links:
    - icon: github
      text: GitHub
      href: https://github.com/yourusername
    - icon: envelope
      text: Email
      href: mailto:youremail@example.com
---

About the lang field:

  • lang: zh (default): Indicates you are writing this file in Chinese. The translation script will automatically generate an English version at content/en/index.qmd.
  • lang: en: If you want to write the homepage in English, change lang to en. The script will automatically generate a Chinese version at content/zh/index.qmd.

Note: This template defaults to lang: zh, so content/en/index.qmd is auto-generated. If you want to switch to writing the homepage in English (lang: en), it is recommended to first delete content/en/index.qmd to avoid confusion.

4 Advanced Principles

If you are interested in the principles behind the website or want to perform deep customization, please read the official documentation. This chapter provides some targeted explanations; reading it alongside the project directory structure is recommended.

4.1 How Does the Automatic Translation Scheme Work?

Traditional bilingual websites often require complex i18n configuration or maintaining two completely independent sets of code. This template implements automated mirroring through a Python script (scripts/sync_deepseek.py):

  1. Mirror Structure: The .qmd files in content/zh and content/en correspond one-to-one and are automatically translated. Only .qmd files participate in synchronization; other files (such as images, PDFs, _metadata.yml configuration files, etc.) are not processed.
    • Exception: The homepage in the language root directory (content/zh/index.qmd or content/en/index.qmd) also does not participate in synchronization because it is unidirectionally generated from the root index.qmd based on the lang field.

    Note: The script does not actively create empty folders. It only creates corresponding translated files and folder structures in the target language folder (e.g., content/en/blog) when .qmd files exist in the source language folder (e.g., content/zh/blog).

  2. Automatic Completion:
    • When you write content/zh/blog/post1.qmd, the script automatically generates the corresponding content/en/blog/post1.qmd.
    • And vice versa.
  3. Script Markers: Files automatically generated by the script will have an <!-- Auto-generated ... --> marker at the end of their code, which is part of the implementation of the automated workflow.
  4. Automatic Translation: You only need to focus on writing in one language; the content in the other language is automatically generated and filled by AI.
  5. Independence and Unification: Although the content is auto-generated, the generated files are independent. If you are not satisfied with the AI’s translation, you can directly modify the generated file, and the script will respect your changes (unless you delete it).

This design makes website maintenance extremely simple: Write a bilingual website as if you were writing a single-language blog.

4.1.1 How Does the Script Know Which Files Need Translation?

You might wonder how the script knows which file I modified. It determines this through the following logic:

  1. File Does Not Exist: If there is no corresponding file in content/en, it means it’s a new article, translate it.
  2. Manual File Protection: If the target file exists, the script first checks for the <!-- Auto-generated ... --> marker. No marker = a manually created/maintained file. The script will skip it to prevent overwriting your hard work.
  3. Hash Verification: For files with the marker (i.e., those generated by the script), the script calculates the content Hash of the source file and compares it with the Hash recorded in the target file. If they don’t match, it means the source file has been updated, re-translate it. If the target file has no Hash record, it will also be re-translated.

4.1.2 Warning: How to Protect Your Modifications?

Scenario: You modified the English version (corrected an AI error), and later updated the Chinese version.

  • Case A (Dangerous): You only modified the English body text but kept the <!-- Auto-generated ... --> marker at the end of the file.
    • Result: When the source file content changes (Hash mismatch), the script will think it needs updating and forcefully overwrite it. Your English modifications will be lost!
  • Case B (Safe): When you modified the English body text, you deleted the auto-generated marker at the end of the file.
    • Result: The script cannot detect the marker, considers this a “manually maintained file,” and thus skips translation. Your modifications are preserved.

Note: Once you decide to manually intervene and modify a translation draft, be sure to delete the auto-generated marker at the end of the file immediately! The automated translation synchronization for this document stops here, and you can manually maintain the bilingual version from now on.

4.2 How Listing Pages Work

The list pages for “Blog,” “Notes,” and “Papers” on the homepage of this template are all automatically generated using Quarto’s Listing feature. You don’t need to manually maintain article lists; you just need to configure the index.qmd for the corresponding folders.

4.2.1 How to Create a New Listing Page?

Suppose you want to create a new section called “Projects.” The steps are as follows:

  1. Create a Folder: Create a new folder named projects under content/zh/.
  2. Create an Index File: Create index.qmd inside it and write the following configuration:
---
title: "My Projects"
listing:
  contents: "*.qmd"        # Grabs all .qmd files in the current directory
  sort: "date desc"        # Sorts in descending order by date
  type: default            # Display style: default (list), grid (grid), table (table)
  categories: true         # Show category tags
  sort-ui: true            # Show sort buttons
  filter-ui: true          # Show search box
page-layout: full
---

Here are all my projects.
  1. Add Content: Create specific project introduction files (e.g., project-a.qmd) under the projects folder, and they will automatically appear in the list.

4.2.2 Common Listing Styles (type)

  • default: The classic blog list view, showing thumbnails, titles, summaries, and metadata. Suitable for blogs.
  • grid: A visually appealing card grid view. Suitable for showcasing portfolios or image-heavy content.
  • table: A compact table view. Suitable for displaying large lists of papers or data.

You can change the type field in index.qmd at any time to switch styles.

4.3 Configuration Hierarchy and Priority

A Quarto website is like a simply furnished house. Although the default style is already quite minimalist and aesthetically pleasing, we all desire more options: for example, changing the layout, display options, or styles of one or several web pages. These needs can be achieved through YAML (.yml) configuration files.

4.3.1 What is a YAML (.yml) File?

In this project, you will frequently see files with the .yml suffix, such as _quarto.yml and _metadata.yml. These are configuration files in YAML format.

YAML (YAML Ain’t Markup Language) is a format specifically designed for writing configuration files. Its hallmark is being extremely readable—writing it is like writing an outline, using indentation to represent hierarchical relationships.

About Filenames: YAML itself is just a data format; filenames can be arbitrary (e.g., config.yml, settings.yaml). However, Quarto specifies particular filenames: _quarto.yml is for global configuration, and _metadata.yml is for directory-level configuration. Only by using these conventional names will Quarto automatically recognize and apply the configurations.

Core Syntax Rules:

  1. Indentation Indicates Hierarchy: Just like in Python, indentation is crucial.
  2. Space After Colon: key: value is the standard format; a space must follow the colon.

Special Note: YAML at the Document Head (Front Matter)

Besides standalone .yml configuration files, you’ll notice that each .qmd document begins with a section wrapped by three dashes ---. This is also YAML, called Front Matter, specifically used to describe the properties of that article (such as title, author, date, tags, etc.). The syntax for both types of YAML is the same. The difference between YAML (.yml) files and Front Matter is that the former are standalone configuration files, while the latter is embedded within the document; the former does not need to be wrapped in ---.

Quarto’s configuration system is very flexible and follows a “Cascading” principle. Understanding this is crucial for customizing the website.

Quarto supports three levels of configuration files, each with a different scope and priority. They are:

4.3.2 1. Global Configuration (_quarto.yml)

  • Location: Project root directory.
  • Scope: Entire website.
  • Purpose: Defines the website’s theme, navigation bar, language, and default settings for all pages.
  • Example: Setting author: "Perry" here makes Perry the default author for all articles across the entire site.

4.3.3 2. Directory-Level Configuration (_metadata.yml)

  • Location: Any subfolder (e.g., content/zh/blog/).
  • Scope: All documents within that folder and its subfolders.
  • Purpose: Customizes styles for a specific section, overriding global settings or adding new properties.
  • Example: If lightbox effects are not enabled globally, but you want images in the blog section to be clickable for enlargement, set lightbox: true in blog/_metadata.yml.

4.3.4 3. Document-Level Configuration (YAML Front Matter)

  • Location: Top of a specific .qmd file (between ---).
  • Scope: Only the current document.
  • Purpose: Defines article-specific properties, such as title, publication date, tags, or overrides higher-level settings.
  • Example: If a blog post is a reprint, write author: "Guest" in the header of that file.

4.3.5 Priority Rule: Proximity Principle

When conflicts arise between configurations at multiple levels, the rule is simple: the closer to the document, the higher the priority.

4.3.5.1 About Nested Folders

If your directory structure has multiple nested layers (e.g., content/zh/notes/math/), each layer can have its own _metadata.yml. Configuration follows an “Inheritance and Override” mechanism:

  • Inheritance: Subfolders automatically inherit configurations from parent folders. For example, documents under math/ will automatically apply general settings from notes/_metadata.yml.
  • Override: If a property is redefined in a subfolder, it overrides the same property in the parent folder. For example, you can disable the table of contents specifically for math notes in math/_metadata.yml.

Final Priority Chain (from highest to lowest): **Document-Level (YAML) > Document’s Folder (_metadata.yml) > Parent Folder (_metadata.yml) > Global (_quarto.yml)**

4.3.5.2 Example (Hypothetical Scenario)

The following is a hypothetical example to illustrate how configuration priority works (not the actual configuration of this template):

  1. _quarto.yml (Global):

    author: "Site Owner"
toc: false # Disable table of contents globally by default

  2. blog/_metadata.yml (Directory):

    # No author specified, inherits global
toc: true  # Enable table of contents for the blog section (overrides global)
lightbox: true  # Enable click-to-enlarge for images

  3. blog/post-1.qmd (Document):

    title: "My First Blog Post"
# No author specified, inherits global -> "Site Owner"
# No toc specified, inherits from parent -> true

  4. blog/guest-post.qmd (Document):

    title: "Guest Post"
author: "Guest Contributor"  # <--- Overrides global!
toc: false     # <--- Overrides directory! (Disable TOC for this post)

Final Result:

  • Post 1: Author is “Site Owner”, table of contents is enabled, lightbox effect is enabled.
  • Guest Post: Author is “Guest Contributor”, table of contents is disabled, lightbox effect is enabled.

5 Core Concepts and Writing

After configuration, this is the part you will use most frequently in daily work.

5.1 What is a .qmd File?

.qmd (Quarto Markdown) is the core file format used by this website.

Why use it?

  1. Simple and Easy to Learn: It is based on Markdown, a minimalist markup language. You don’t need to adjust formatting like in Word; you can write well-structured articles using simple symbols (e.g., # for headings).
  2. Powerful: It natively supports LaTeX mathematical formulas (e.g., $E=mc^2$) and code blocks, making it ideal for academic writing and data presentation.
  3. Automatic Web Conversion: Your written text is automatically rendered into beautiful HTML web pages.

Quick Start Markdown Example:

# This is a Level 1 Heading
## This is a Level 2 Heading

This is a paragraph of plain text. You can make it **bold** or *italic*.

- This is a list item
- Supports math formulas: $f(x) = \int x dx$
- Supports inserting images: `![](image.jpg)`

5.2 Formula Referencing

Quarto supports numbering and referencing mathematical formulas, making it very suitable for academic writing.

Defining a Numbered Formula:

$$
E = mc^2
$$ {#eq-einstein}

Referencing a Formula:

According to Einstein's mass-energy equation @eq-einstein, we can conclude...

After rendering, the formula will be automatically numbered (e.g., “(1)”), and the reference will appear as a clickable link (e.g., “Equation 1”).

Tip: Formula labels must start with #eq-, followed by a custom identifier (e.g., einstein).

5.3 Literature Citation

This template has already configured the literature citation management function. You only need to:

  1. Add Literature Entries: Add BibTeX format literature entries to the references.bib file in the project root directory. For example:

    @article{Shannon1948,
    author = {Claude E. Shannon},
    title = {A Mathematical Theory of Communication},
    journal = {Bell System Technical Journal},
    year = {1948}
}

  2. Cite in the Main Text: Use the @ symbol followed by the literature’s key for citation.

    Information theory was founded by Shannon [@Shannon1948].

As pointed out by @Shannon1948...
    • [@Shannon1948] renders as: (Shannon 1948)
    • @Shannon1948 renders as: Shannon (1948)

  3. Bibliography List: Quarto will automatically generate a bibliography list at the end of the article, no additional configuration is needed. If you want to customize the location of the bibliography (e.g., place it in the middle of the article or under a specific section), you can add the following at the desired location:

    ## References

::: {#refs}
:::

Tip:

  • You can use tools like Google Scholar, Zotero, etc., to export BibTeX format literature entries and directly paste them into references.bib.
  • When typing @ in VS Code, the Quarto extension will automatically pop up the literature list from references.bib for you to choose from.

5.4 Publishing Workflow

After writing the article, you can publish it in just three steps:

  1. Create Article: Create a new .qmd file in the corresponding subdirectory (e.g., blog/, notes/) under content/zh/ or content/en/. Write the content in your preferred language (Chinese or English).

  2. Commit Changes: You can choose either of the following methods.

    Method A: Using VS Code Git (Recommended)

    In the VS Code Source Control panel on the left, enter a commit message, click “Commit”, and then click “Sync Changes”.

    Note: This method does not run translation locally. Translation will be automatically completed in the cloud after pushing to GitHub.

    Method B: Using Command Line

    If you are accustomed to using the terminal, you can run standard Git commands:

    git add .
git commit -m "Commit message"
git push

  3. Wait for Deployment: After pushing, GitHub Actions will automatically complete translation, building, and publishing. Refresh the website after a few minutes to see the updates.

5.4.1 Local Translation (Optional)

If you wish to preview the translation results locally instead of waiting for automatic cloud translation, you can follow the steps below.

The following commands are all run in the VS Code terminal (Terminal -> New Terminal). Ensure the current directory is the project root.

Step 1: Install Dependencies (Only needs to be done once)

pip install -r requirements.txt

Step 2: Set Environment Variables

Windows PowerShell:

$env:DEEPSEEK_API_KEY = "sk-your-key"

macOS / Linux:

export DEEPSEEK_API_KEY="sk-your-key"

Step 3: Run the Translation Script

python scripts/sync_deepseek.py

Note: Environment variables become invalid after the terminal is closed and need to be set again next time.

5.5 Automated Workflow

After you push your code, GitHub Actions will automatically take over the subsequent tasks:

  1. Detect Changes: Identifies which .qmd files you have added or modified.
  2. AI Translation:
    • If you wrote in Chinese, it will automatically translate it to English.
    • If you wrote in English, it will automatically translate it to Chinese.
    • The translation results will be automatically committed back to your repository (you will see a new commit from DeepSeek Bot).
  3. Build Website: Runs quarto render to generate static web pages.
  4. Publish Online: Pushes the web pages to the gh-pages branch. Your website will be updated within a few minutes.

You can view the real-time logs of the entire process on the Actions tab of your GitHub repository.

5.6 Local Preview

Run the following command in the VS Code terminal to preview the website locally in real-time:

quarto preview --render html

This will start a local server, and your browser will automatically open the preview page. After you modify and save a file, the page will refresh automatically.

6 FAQ

General Troubleshooting Method: When encountering deployment issues, the first step is to check the run logs on the Actions tab of your GitHub repository. Click on the most recent run record; a red cross indicates failure. Click into it to see specific error messages. If you encounter an error you don’t understand, you can copy the error message and ask an AI to help you analyze it.

6.1 Why isn’t my translation taking effect?

  1. Check the GitHub Actions logs: On your repository page, click “Actions” and view the details of the most recent run.
  2. Check the API Key: Ensure you have correctly configured DEEPSEEK_API_KEY in Secrets and that the key still has a balance.
  3. Local Debugging: If you are running the script locally and the translation is not taking effect, make sure the environment variable is set.

6.2 Getting a 404 error after deployment?

Please check the settings in Settings -> Pages. Ensure the Source branch is set to gh-pages, not main.

6.3 What if I only want to use a single language (e.g., only Chinese) and don’t want the bilingual feature?

This template is designed flexibly and can be switched to single-language mode.

Steps:

  1. Disable the translation feature:
    • Go to your GitHub repository -> Settings -> Secrets and variables -> Actions, and delete DEEPSEEK_API_KEY.
    • When the script detects no API Key, it will automatically skip translation without affecting deployment.
  2. Clean up unnecessary files:
    • Delete the language folder you don’t need (e.g., content/en).
    • Also check _quarto.yml and remove all links pointing to that folder (e.g., paths like content/en/... in the navbar or sidebar).
  3. Remove the language switcher:
    • Open _quarto.yml, find the include-after-body section, and delete the line assets/html/include_lang_switch.html.
    • In the navbar settings, delete the navigation item related to icon: translate.
  4. Verify the configuration:
    • Run quarto preview locally to confirm there are no errors.
    • After pushing, check if the GitHub Actions run is successful.

This way, your website becomes a single-language site.

7 Additional Tool: Automatic Conversion from LaTeX to Quarto Markdown

If you already have a large number of LaTeX (.tex) documents, this project also provides an automatic conversion script that can batch convert .tex files into Quarto Markdown (.qmd) format, facilitating migration and publishing.

You can view detailed usage instructions and examples in scripts/README.md. You are welcome to refer to and use this tool to improve content migration efficiency. However, please note that this script is still being continuously improved, so it is recommended to test it on a small scale first.

We hope this template helps you build an outstanding personal homepage! If you have any questions, feel free to leave a comment below or create an Issue on GitHub.