The template produces an academic website 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. The second goal was to obtain a website that highlights the research and teaching material. The third 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. The final goal was to design a website that is easy to maintain and expand.


View


Installation

On your local machine

  • Clone the repository to your local machine
  • Install Hugo . On a Mac, this is easily done with Homebrew . Simply run the following command in the terminal: brew install hugo.
  • Since the website is hosted on GitHub Pages, it is convenient to install GitHub Desktop . The website can conveniently be updated from your local machine via GitHub Desktop without going to GitHub.
  • Update the baseURL parameter in config.yml with the website URL that you plan to use.

On your GitHub account

  • The first time that you push your repository to GitHub, you need to allow GitHub Actions and GitHub Pages so the website can be built and deployed to GitHub Pages.
  • The first step is to ask GitHub to publish the website with a GitHub Action. GitHub offers a ready-made action to publish a Hugo website, called Deploy Hugo site to Pages. This action must be enabled in the Pages Settings of your GitHub repository. You can view the workflow triggered by the action in the .github/workflows/hugo.yml file.
  • Once the GitHub Actions are enabled, GitHub will build and publish the website as soon as the repository is updated.

Usage

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.

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.

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 used by GitHub Actions 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

The config.yml file contains many other options that can be adjusted:

  • cover:hiddenInList – Set to true to hide cover images in paper, course, and data lists
  • paginate – The number of entries to show on each list page

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
  • Data – Data projects, stored in the data subfolder

The category pages include a list of the items in the category (papers, courses, data), 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, a blog, and so on. For instance to add a list of software, create a new software subfolder into the content folder. Then add a content file such as new_software.md into the software subfolder. That new category will be available at baseURL/software/.

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: Software
  url: /software/

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: Software
  url: /software/
  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 the static files (files not processed or rendered by Hugo) for the website. 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 .

The static folder could also include the PDF files and images to which the website links. It could contain:

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

This is for instance how I organized the static files on my website . But in the template, to be more flexible and portable, these files are located directly in the folder for the individual page where there are used: content/papers/paper1/, content/papers/paper2/, content/courses/course1/, and so on.


Keywords

A list of all the keywords used in papers and courses is automatically generated and added to the website. The tag list is accessible from the homepage. THe list can also be added to the menu bar. To do that, simply add the following snippet into the config.yml file, below menu:main:

- name: Keywords
  url: /tags/
  weight: 5

Specific tags can be added to any webpage with the tags parameter. Such tags appear at the bottom of the page in small gray buttons.

The tag list is generated by default, but it can be customized through the file _index.md placed in the content/tags/ 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
  • Address – Use name: Location 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

The website also features an archive . The archive displays a chronological list of all papers, courses, and data projects. It is accessible from the homepage. 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 is available at baseURL/archive/.


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 has a footer. The footer contains a copyright notice and a “Powered by” notice. The footer can be customized by modifying the file layouts/partials/footer.html. It is possible to hide the footer by setting hideFooterto true in the config.yml file.


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

It is easy to use a custom domain name for the website. For instance, the domain name https://pascalmichaillat.org/ is registered with Google Domains , which offered simple way to register your domain name. Unfortunately Google Domains has been sold to Squarespace — which will hopefully remain as easy to use as Google Domains.

Once you have registered a domain, you need to link it to your website. Make sure that the baseURL parameter in config.yml reflects the custom domain name. Make sure that the page setting on GitHub also includes the domain name.