The template produces a personal 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 on 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
Features
- Webpages are organized in three categories, which are available from any page through the menu and from the homepage through buttons: papers, courses, and data.
- A list of tags (keywords) used in papers and courses is automatically generated so visitors can easily see the topics covered in research and teaching.
- An archive page is automatically generated so visitors can easily see the most recent material added to the website.
- The template provides social icons specific to academia: office hours, Zoom, Substack, and Google Scholar.
- The metadata for webpages, which appear below the webpage title, are tailored to the academic context.
- Color scheme, font, spacing, buttons, and general appearance have been streamlined and made as minimalist as possible.
- The template provides new archetypes for paper pages, course pages, and a search page.
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 inconfig.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 URLtitle
– Your name, to be used as title of the websiteparams: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 homepageparams:profileMode:subtitle
– A description of who you are, to be used as a subtitle on the homepageparams:profileMode:imageTitle
– Your name, to be used as tag for your profile pictureparams:socialIcons
– The URLs to your social accounts
The config.yml
file contains many other options that can be adjusted:
cover:hiddenInList
– Set totrue
to hide cover images in paper, course, and data listspaginate
– 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 universityofficehours.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
belowparams:socialIcons:
inconfig.yml
- Address – Use
name: Location
belowparams:socialIcons:
inconfig.yml
- Zoom – Use
name: Zoom
belowparams:socialIcons:
inconfig.yml
- Substack – Use
name: Substack
belowparams:socialIcons:
inconfig.yml
- Google Scholar – Use
name: Google Scholar
belowparams:socialIcons:
inconfig.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/
.
Search
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/
.
Footer
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 hideFooter
to 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 Squarespace
. 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.