Quarto Academic Website Template

Welcome! This is a simple and customizable template for building your own academic website using Quarto. You can easily fork, edit, and publish your site with just a few steps.

🚀 Quick Start

1. Star this repository to bookmark it for future reference.
2. Fork this repository and rename it to YourGitHubUserName.github.io.
3. Test to publish your site using GitHub Pages (make sure configuring your GitHub repository to publish from the docs directory, not the root folder).
4. Check if your website works or not. If successful, you should see exactly the same website as this one using your own Github Pages url:
   • https://YourGitHubUserName.github.io if your repository name is YourGitHubUserName.github.io
   • https://YourGitHubUserName.github.io/RepositoryName for other RepositoryName
   • Errors:
     • If 404, it is likely you haven't set up GitHub Pages
     • If it shows the README file, it is likely you've published from the root folder, not the docs directory

If you achieve this milestone, congratulations! You are now ready to start updating your website:

1. Update the _quarto.yml file to configure your site’s basic settings.
2. Add or edit content in the following files and folders:
   • /posts/ – posts about publications, news, events
   • teaching.qmd – teaching information
   • projects.yml – research or other projects
   • people.qmd and /people/ – team or collaborators
   • /files/ - profiles, images, pdfs, and includes
3. Render and preview your site locally.
4. Commit to publish your updates.
5. Refine and polish your content and design as needed.
6. ✅ Enjoy your new website!
7. Link your website on your official pages to let Google and AI bots include in their search results.

Automatically Generate a Neat Publication List

1. Prepare your publication source file:
   • Recommended: maintain publications.xlsx (already supported by this template, you can convert a bib file to Excel using online tools).
2. Fill publications.xlsx using the expected column names:
   • Section, Authors, Year, Date, Title, Paper Link, Journal, Volume, Issue, Pages, DOI
   • Optional links/metadata: PDF, Preprint, ShareIt, Supplemental Information, GitHub, Code, Data
   • Optional flags/info: Highly Cited, Hot Paper, Awards, Media Coverage, Invited Presentation, Categories
3. Install Python dependency (one-time):
   • pip install openpyxl
   • Optional validation support: pip install pyyaml
4. Convert Excel to YAML:
   • python xlsx_to_yml.py
   • Or with custom files: python xlsx_to_yml.py input.xlsx output.yml
   • Force conversion: python xlsx_to_yml.py --force
5. Render your site:
   • quarto render
   • The project is already configured with pre-render: python xlsx_to_yml.py in _quarto.yml, so conversion will run automatically before rendering if there is any update in publications.xlsx.
6. Check publication page output:
   • Main auto-generated page: pub-listing.qmd
   • Listing template: pub-listing.ejs
   • Styling: pub-listing.css
   • Filter: The remove-stray-divfence.lua filter is added to remove excessive ::: in html after rendering.
7. Categorize records correctly:
   • Use Section as either Selected Work or Peer-reviewed Journal Paper to place entries into corresponding sections. You can add other Section as needed.
   • Use Categories with separators like ,, ;, or | for listing filters.
8. Publish changes:
   • Enjoy your neat automatically generated publication list. You can customize style and template if you need to add new links and flags.

🛠 Requirements

• Install Quarto
• Learn the basics from the official Quarto documentation

📚 More Examples & Tips

• Quarto Academic Site Examples and Tips