Overview

The source code to this website is publicly available as a template repository, so anyone can generate a new repository with the same directory structure and files, and quickly create their own academic website. The code might also be helpful to anyone who wishes to recreate specific features of this website.

The website is built with Hugo, which is a very fast, open-source static website generator. The website design is based on PaperMod, which is a minimalist, fast, and flexible Hugo theme. Finally, the website is hosted on GitHub Pages; but it could easily be hosted by other services.

The design has been customized for academic websites. The first goal was to obtain a minimalist website that is easy to navigate and easy to maintain. The second goal was to obtain a website that highlights the research and teaching material. The final goal was to have a website that performs well (fast to load, good SEO, good accessibility). The website performs very well on mobile and desktop devices—just like the original PaperMod theme.

Download

Installation

  • Clone the repository to your local machine
  • Install Hugo. On a Mac, this is easily done with Homebrew: simply run brew install hugo in the terminal.
  • Since the website is hosted on GitHub Pages, the website can conveniently be updated by GitHub Desktop.

Usage

Website development

To check that everything works, experiment with the code, and slowly develop your website, start by rebuilding the website locally. In the terminal, navigate to your website directory and run hugo server from there. The command builds the website with Hugo and starts a local web server. The website is then available at http://localhost:1313 in any web browser. Hugo automatically rebuilds the site and refreshes the web page in the browser as changes are made to the files (content, templates) in the repository. This allows you to see changes instantly as you are developing your website.

Website compilation

Once your website is ready to be made public, run hugo in the terminal from your website directory. This command will convert content files into HTML pages, handles static assets, generates URLs and organizes pages, and finally compile the website into the public folder for deployment.

Website deployment

With GitHub Desktop, you can just commit the changes and push them to the GitHub repository online. Then, GitHub Actions will build the website and deploy it to GitHub Pages. The workflow is in the hugo.yml file stored in the .github/workflows folder. It usually takes a few minutes for the website to be deployed and go live.

Configuration file

The config.yml file contains all the parameters to configure the website. Upon cloning the source code to your local machine, make sure to update them. Such parameters include:

  • baseURL – The website URL
  • title – Your name, to be used as title of the website
  • params:author - Your name, to be used in HTML meta tags to specify the author of the webpage’s content (this only adds a meta tag to the header of the homepage, it doesn’t have any direct impact on the appearance or functionality of the webpage itself)
  • params:description – A short description (less than 155 characters) of who you are, to be used in HTML meta tags to specify the content of the webpage (this description often appears in search engine results below the title of the webpage)
  • params:googleAnalyticsID – The website’s Google Analytics ID (the website supports Google Analytics 4)
  • params:profileMode:title – Your name, to be used as title on the homepage
  • params:profileMode:subtitle – A description of who you are, to be used as a subtitle on the homepage
  • params:profileMode:imageTitle – Your name, to be used as tag for your profile picture
  • params:socialIcons – The URLs to your social accounts

Content files

The content folder contains all the content files for the website. These files are written in Markdown, a simple markup language designed to make writing on the web fast and easy. Each file corresponds to one page of the website.

Most of the files organized in three categories, which are available from any page through the navigation menu and from the homepage through buttons:

  • Papers – Published and unpublished research papers, stored in the papers subfolder
  • Courses – Undergraduate and graduate courses, stored in the courses subfolder
  • Design – Design projects, stored in the design subfolder

The category pages include a list of the items in the category (papers, courses, design), with links to individual items. These lists are updated automatically as content files are added, deleted, or modified in the specific subfolder.

New items

To add a new paper to the website, for instance , add a file new_paper.md into the papers subfolder. That new paper will automatically be listed on the page with the other papers. It is convenient to use archetypes to generate new files easily.

By default, the URL of the new paper would be baseURL/papers/new_paper/. But the URL can be customized in the new_paper.md file with the url parameter. For instance, with url: /paperx/, the URL of the new paper is simplified to baseURL/paperx/.

New categories

It is also easy to add new categories to the website, for instance to list software, data, a blog, and so on. For instance to add a list of datasets, create a new data subfolder into the content folder. Then add a content file such as new_dataset.md into the data subfolder. That new category will be available at baseURL/data/.

You can for instance link to it with a button from the homepage. To do that, simply add the following snippet into the config.yml file, below profileMode:buttons:

- name: Datasets
  url: /data/

You can also add a link to the new category in the menu bar. To do that, simply add the following snippet into the config.yml file, below menu:main:

- name: Datasets
  url: /data/
  weight: 4

Other content files

The content folder contains a few additional files, which are not part of categories.

  • location.md – Mailing and office addresses, including a map of the university
  • officehours.md – Schedule and location for office hours

It is possible to add any number of files in the content folder. By default, any new_file.md file will be available at baseURL/new_file/.

Static files

The static folder contains all the static files (files not processed or rendered by Hugo) for the website. These include all the PDF files and images to which the website links. For the most part, the static folder contains:

  • Papers and online appendices in PDF format
  • Presentations in PDF format
  • Lecture notes in PDF format
  • Figures from the papers in PNG format

In addition, the static folder contains a few files used in the homepage:

  • picture.jpeg – Headshot appearing on the homepage.
  • cv.pdf – Curriculum vitae linked to the CV icon on the homepage.
  • favicon.io, favicon-32x32.png, favicon-16x16.png, apple-touch-icon.png – Favicon appearing in the menu bar next to the website title, and in the browser next to the URL. It is easy to produce new favicons.

Tags

A list of all the tags (or keywords) used in papers and courses is automatically generated and added to the website. The tags are accessible from the menu bar. Tags can be added to any webpage with the tags parameter. Tags also appear at the bottom of the page in small gray buttons.

The tag page is generated by default, but it can be customized through the file _index.md placed in the content/tag/ folder. The file defines for instance the description of the page for search engines (description:) as well as the title of the page (title:).

Social icons

The website includes new social icons specific to academia:

  • Office hours – Use name: Office Hours below params:socialIcons: in config.yml
  • Zoom – Use name: Zoom below params:socialIcons: in config.yml
  • Substack – Use name: Substack below params:socialIcons: in config.yml
  • Google Scholar – Use name: Google Scholar below params:socialIcons: in config.yml
  • All the icons are defined in the file layouts/partials/svg.html; additional icons can be added there

Archetypes

The template comes with archetypes, stored in the archetypes folder. In Hugo, an archetype is a predefined content template that serves as a blueprint for creating new pages. Archetypes help streamline content creation by providing a consistent starting point with predefined metadata and content structure. There is an archetype for paper pages (paper.md) and an archetype for course pages (course.md)

To create a new webpage from an archetype, simply use the hugo new command in the terminal from the website directory. For example, to create a page for a new course, you can run:

hugo new content/courses/my-new-teaching-material.md --kind course

Hugo will generate a new content file called my-new-teaching-material.md and place it the directory content/courses/, where all the courses are stored. Furthermore, Hugo will use the archetype course.md. Then, you can edit the content of the page by modifying the newly created file my-new-teaching-material.md.

Similarly, to create a page for a new paper, you can run:

hugo new content/papers/my-new-research-material.md --kind paper

Hugo will generate a new content file called my-new-research-material.md and place it the directory content/papers/, where all the papers are stored. Furthermore, Hugo will use the archetype paper.md.

Archive

An archive can be added to the website. The archive displays a chronological list of all papers, courses, and design projects.

To add an archive page, move the archive.md file from the archetypes folder into the content folder. Then, add the following snippet below menu:main: in the config.yml file to make the archive available from the menu:

- name: Archive  
  url: /archive/  
  weight: 7

The archive will be available at baseURL/archive/.

Search page

A search page can also be added to the website. To add a search page, move the search.md file from the archetypes folder into the content folder. Then, add the following snippet at the end of the config.yml file so that search works properly:

outputs:
     home:
         - HTML
         - RSS
         - JSON

Finally, add the following snippet below menu:main: in the config.yml file to make the search page available from the menu:

- name: Search  
  url: /search/  
  weight: 6

The search page will be available at baseURL/search/.

The website does not have a footer, but it is possible to add one by setting hideFooterto false in the config.yml file. The footer contains a copyright notice and a “powered by” notice. The footer can be customized by modifying the file layouts/partials/footer.html.

Public folder

The public folder contains the fully generated static website files that are ready to be deployed to GitHub Pages. When you run the hugo command, Hugo processes your content, templates, and other project files and generates a static website. The resulting output is placed in the public folder by default.

The public folder can always be safely deleted. A new version of the public folder will be created when you run the hugo command in the terminal.

Domain name

The website’s domain name https://pascalmichaillat.org/ is registered with Google Domains, which offers simple way to register your domain name and link it to your website.