Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/academicpages/academicpages.github.io/llms.txt

Use this file to discover all available pages before exploring further.

The _config.yml file in the root of your repository is the master control file for your Academic Pages site. Almost every site-wide behavior — your title, URL, analytics provider, comment system, and the structure of your content collections — is driven by a single edit to this file. Jekyll reads it at build time, so you must restart the local server (jekyll serve) after making any changes.
_config.yml is not hot-reloaded during jekyll serve -l. Stop and restart the server after every edit to this file.

​
Basic Site Settings

These fields appear at the very top of _config.yml and define the fundamental identity of your site.
_config.yml
locale                   : "en-US"
site_theme               : "default"
title                    : "Your Name / Site Title"
title_separator          : "-"
name                     : &name "Your Name"
description              : &description "Your Name's academic portfolio"
url                      : https://academicpages.github.io
baseurl                  : ""
repository               : "academicpages/academicpages.github.io"
​
locale
string
default:"en-US"
BCP 47 language tag used to select the correct UI text translations from _data/ui-text.yml. Common values: "en-US", "en-GB", "fr", "de", "es".
​
site_theme
string
default:"default"
Visual theme for the site. Available options: "default", "air", "sunrise", "mint", "dirt", "contrast". Each theme ships with both a light and dark variant. See the Themes guide for details.
​
title
string
required
The site title shown in the browser tab, the masthead, and in social-sharing metadata. Typically set to your name or “Firstname Lastname”.
​
title_separator
string
default:"-"
Character placed between the page title and the site title in the <title> tag, for example Page Title - Site Title.
​
name
string
required
Your name as a YAML anchor (&name). Referenced elsewhere as *name to avoid repetition.
​
description
string
Default meta description for the site used when a page does not specify its own. Also declared as a YAML anchor (&description).
​
url
string
required
The full base URL including protocol: https://[your GitHub username].github.io. If your site lives under a project path rather than a user/org page, include the path here or use baseurl.
​
baseurl
string
default:"\"\""
The subpath of your site relative to url. Leave blank for a user/org GitHub Pages site (username.github.io). Set to "/repo-name" when hosting from a project repository.
​
repository
string
The GitHub repository in owner/repo format. Used by the github-metadata plugin and various GitHub-related template features.

​
Site Settings (Miscellaneous)

_config.yml
teaser                   :  # filename in /images/ used as fallback social preview
breadcrumbs              : false
words_per_minute         : 160
future                   : true
read_more                : "disabled"
talkmap_link             : false
​
teaser
string
Filename of a fallback image in /images/ used as the Open Graph / social media preview when a page has no image of its own.
​
breadcrumbs
boolean
default:"false"
Set to true to enable breadcrumb navigation above page content.
​
words_per_minute
integer
default:"160"
Used to calculate the estimated reading time displayed on posts.
​
future
boolean
default:"true"
When true, Jekyll will publish posts with a future date. Set to false to hide them until their date arrives.
​
read_more
string
default:"disabled"
Set to "enabled" to add “Read more” links to post excerpts on archive pages.
​
talkmap_link
boolean
default:"false"
Set to true to add a link to the generated talkmap on the Talks page.

​
Analytics

_config.yml
analytics:
  provider               : "false"  # "google", "google-universal", "google-analytics-4", "custom"
  google:
    tracking_id          :
​
analytics.provider
string
default:"\"false\""
Analytics backend to use. Supported values: "false" (disabled), "google", "google-universal", "google-analytics-4", "custom".
​
analytics.google.tracking_id
string
Your Google Analytics property ID (e.g. G-XXXXXXXXXX for GA4, or UA-XXXXXXXX-X for Universal Analytics).

​
Comments

Academic Pages supports several comment providers. Only one should be active at a time.
_config.yml
comments:
  provider               : # "disqus", "discourse", "facebook", "staticman", "custom"
  disqus:
    shortname            :
  discourse:
    server               : # e.g.: meta.discourse.org
  facebook:
    appid                :
    num_posts            : # 5 (default)
    colorscheme          : # "light" (default), "dark"
staticman:
  allowedFields          : ['name', 'email', 'url', 'message']
  branch                 : "gh-pages"
  commitMessage          : "New comment."
  filename               : comment-{@timestamp}
  format                 : "yml"
  moderation             : true
  path                   : "_data/comments/{options.slug}"
  requiredFields         : ['name', 'email', 'message']
  transforms:
    email                : "md5"
  generatedFields:
    date:
      type               : "date"
      options:
        format           : "iso8601"
​
comments.provider
string
default:"false"
Comment system to enable. Options: "disqus", "discourse", "facebook", "staticman", "custom", or leave blank to disable comments.
​
comments.disqus.shortname
string
Your Disqus site shortname. Required when provider is "disqus".
​
comments.discourse.server
string
Domain of your Discourse forum (e.g. meta.discourse.org). Required when provider is "discourse".
​
comments.facebook.appid
string
Facebook App ID for the Facebook Comments plugin.
​
comments.facebook.num_posts
integer
default:"5"
Number of Facebook comments to display initially.
​
comments.facebook.colorscheme
string
default:"light"
Facebook comments widget color scheme: "light" or "dark".
The staticman block configures the Staticman service for Git-based comment storage. Key options include branch, moderation (requires manual approval of each comment), and the path where comment YAML files are written.

​
Atom Feed

_config.yml
atom_feed:
  hide                   : false
  path                   :
​
atom_feed.hide
boolean
default:"false"
Set to true to remove the RSS/Atom feed link from the site footer.
​
atom_feed.path
string
Custom path for the feed file. Leave blank to use the default feed.xml.

​
SEO Settings

_config.yml
google_site_verification :
bing_site_verification   :
alexa_site_verification  :
yandex_site_verification :
Paste the verification token (not the full meta tag) provided by each search console. These fields are rendered into <meta> tags in the page <head> by the jekyll-seo-tag plugin.
_config.yml
twitter:
  username               : &twitter
facebook:
  username               :
  app_id                 :
  publisher              :
og_image                 :   # default Open Graph image filename
og_description           :   # default Open Graph description
social:
  type                   :   # "Person" or "Organization"
  name                   :
  links:                     # array of social profile URLs
​
og_image
string
Default Open Graph image file (placed in /images/) used when sharing your site on social media.
​
social.type
string
default:"Person"
Schema.org type for structured data. Use "Person" for an individual academic, "Organization" for a lab or group site.

​
Reading Files

_config.yml
include:
  - .htaccess
  - _pages
  - files
exclude:
  - "*.sublime-project"
  - "*.sublime-workspace"
  - .asset-cache
  - .bundle
  - .github
  - .jekyll-assets-cache
  - .sass-cache
  - assets/js/_main.js
  - assets/js/plugins
  - assets/js/vendor
  - CHANGELOG
  - Capfile
  - config
  - Dockerfile
  - Gemfile
  - Gruntfile.js
  - gulpfile.js
  - LICENSE
  - local
  - log
  - node_modules
  - package.json*
  - Rakefile
  - README
  - tmp
  - vendor
keep_files:
  - .git
  - .svn
encoding: "utf-8"
markdown_ext: "markdown,mkdown,mkdn,mkd,md"
include forces Jekyll to process directories it would normally ignore (such as _pages, which starts with an underscore). exclude prevents build artifacts, editor files, and server-only files from being copied into _site. Add any additional files or folders you want excluded from the built site to this list.

​
Outputting

_config.yml
permalink: /:categories/:title/
timezone: Etc/UTC
​
permalink
string
default:"/:categories/:title/"
URL pattern for posts. Jekyll supports several named patterns such as /:year/:month/:day/:title/ in addition to custom patterns.
​
timezone
string
default:"Etc/UTC"
IANA timezone name used when generating dates. See the tz database for valid values.

​
Plugins

_config.yml
plugins:
  - jekyll-feed
  - jekyll-gist
  - jekyll-paginate
  - jekyll-sitemap
  - jekyll-redirect-from
  - jemoji

whitelist:
  - jekyll-feed
  - jekyll-gist
  - jekyll-paginate
  - jekyll-sitemap
  - jekyll-redirect-from
  - jemoji
All six plugins are whitelisted for GitHub Pages safe mode. Brief descriptions:

jekyll-feed

Generates feed.xml — the Atom feed linked in the site footer.

jekyll-gist

Renders GitHub Gists inline via the {% gist %} Liquid tag.

jekyll-paginate

Adds pagination support for post listing pages (/page2/, etc.).

jekyll-sitemap

Automatically generates sitemap.xml for search engine crawlers.

jekyll-redirect-from

Enables the redirect_from front matter key so old URLs keep working.

jemoji

Converts :emoji_name: syntax into emoji characters.

​
Collections

Collections define the custom content types beyond standard pages and posts.
_config.yml
collections:
  teaching:
    output: true
    permalink: /:collection/:path/
  publications:
    output: true
    permalink: /:collection/:path/
  portfolio:
    output: true
    permalink: /:collection/:path/
  talks:
    output: true
    permalink: /:collection/:path/
Each collection has output: true, meaning Jekyll generates an individual HTML page for every Markdown file in its corresponding _teaching/, _publications/, _portfolio/, or _talks/ directory. The permalink pattern /:collection/:path/ produces URLs like /publications/2024-paper-title/.

​
Publication Categories

_config.yml
publication_category:
  books:
    title: 'Books'
  manuscripts:
    title: 'Journal Articles'
  conferences:
    title: 'Conference Papers'
These keys map the category field in individual publication front matter to display headings on the Publications page. You can rename the titles or add new categories to match your field’s conventions.

​
Defaults

The defaults block sets front matter values automatically for every item in a collection or page type, so you don’t have to repeat them in every file.
_config.yml
defaults:
  # _posts
  - scope:
      path: ""
      type: posts
    values:
      layout: single
      author_profile: true
      read_time: true
      comments: true
      share: true
      related: true
  # _pages
  - scope:
      path: ""
      type: pages
    values:
      layout: single
      author_profile: true
  # _teaching
  - scope:
      path: ""
      type: teaching
    values:
      layout: single
      author_profile: true
      share: true
      comments: true
  # _publications
  - scope:
      path: ""
      type: publications
    values:
      layout: single
      author_profile: true
      share: true
      comments: true
  # _portfolio
  - scope:
      path: ""
      type: portfolio
    values:
      layout: single
      author_profile: true
      share: true
      comment: true
  # _talks
  - scope:
      path: ""
      type: talks
    values:
      layout: talk
      author_profile: true
      share: true
You can override any default on a per-file basis by adding the same key to a file’s own front matter. For example, add author_profile: false to a specific page’s front matter to hide the sidebar on just that page.
The layout: talk used for the talks collection is distinct from layout: single — it renders a specialized talk template including venue and date information.

Build docs developers (and LLMs) love

Get started for freeTalk to us