Edits by me (weiglemc) below. For original README see academicpages.github.io.

A Github Pages template for academic websites. This was forked (then detached) by Stuart Geiger from the Minimal Mistakes Jekyll Theme, which is © 2016 Michael Rose and released under the MIT License. See LICENSE.md.

Setup and Customization Guides

Much thanks to Rob Williams for his setup posts!

• Building an Academic Website
• Customizing an Academic Website
• Adding Content to an Academic Website
• Website GitHub repo

I used https://realfavicongenerator.net to generate the needed favicons (it's a lot more complicated than it used to be...).

Customizations

Some of my customizations:

• icons in the sidebar: _includes/author-profile.html
• follow icons (in footer): _includes/footer.html
• share icons (at bottom of individual pages): _includes/social-share.html
• colors and buttons:
  • _sass/_variables.scss - look for comments /* ODU colors: https://www.odu.edu/facultystaff/communication/toolkit/identity-standards/palette-fonts */ and /* brands */
  • _sass/_utilities.scss - look for comments // MCW
  • _sass/_buttons.scss - look for comment /* my button */

Personalization

• _config.yml - account info (site.author)
• _pages/about.md - main home page

Rob Williams (author of the guides above) had a couple of commits that replaced his Twitter icons and links with Mastodon, see 'we'll meet again' and 'bye bye birdie

Debugging

If the page doesn't regenerate automatically after a new commit, check for build or deployment errors. Check the pages-build-deployment log in the Actions tab.

Generating Publication Pages

I adapted code from PmWiki's BibtexRef Cookbook to read in a BibTeX file and generate various Markdown files for the website. The files are all in the markdown_generator folder in this repo (see README).

• bib2md.py - driver script to generate Markdown files with publication entries
  • update with input BibTeX file, years of publications to generate, type of publications, and definition of "recent"
  • current version writes files directly into _publications folder
• bib2md-students.py - driver script to generate Markdown file with student PhD dissertations and MS theses
  • update with bibtag for new students
  • I copy/paste lines into _pages/students.md
• bibtexref3_md.py - script adapted from PmWiki cookbook to generate Markdown
  • should only need updating to change appearance of reference line output

These have all been converted from PHP to Python.

To run locally on MacOS

Note: see below for installation on an M1 Mac

1. Install Git and Ruby via the Xcode Command Line Tools by running xcode-select --install
2. Install Bundler, a package manager for Ruby by running gem install bundler
3. Clone the repo and make updates
4. Move to the local cloned directory and run bundle install to install ruby dependencies. If you get errors, delete Gemfile.lock and try again.
5. Run bundle exec jekyll serve to generate the HTML and serve it from localhost:4000. The local server will automatically rebuild and refresh the pages on change.

Installing on M1

• Duplicate the /Applications/Terminal app and rename it Terminal-Rosetta
• Use "Get Info" and check "Open using Rosetta"
• Open this new Terminal app to install Bundler
• Install Bundler with arch -x86_64 sudo gem install bundle
• Move to the local cloned directory and install the gems with arch -x86_64 bundle install
• If there are errors, delete Gemfile.lock and try arch -x86_64 bundle install again
• If that doesn't work, uninstall the offending gem sudo gem uninstall package_name and try arch -x86_64 bundle install again.
• Make sure to use Terminal-Rosetta when starting the server with bundle exec jekyll serve

Instructions

1. Register a GitHub account if you don't have one and confirm your e-mail (required!)
2. Fork academicpages repo by clicking the "fork" button in the top right.
3. Go to the repository's settings (rightmost item in the tabs that start with "Code", should be below "Unwatch"). Rename the repository "[your GitHub username].github.io", which will also be your website's URL.
4. Set site-wide configuration and create content & metadata (see below -- also see this set of diffs showing what files were changed to set up an example site for a user with the username "getorg-testacct")
5. Upload any files (like PDFs, .zip files, etc.) to the files/ directory. They will appear at https://[your GitHub username].github.io/files/example.pdf.
6. Check status by going to the repository settings, in the "GitHub pages" section
7. (Optional) Use the Jupyter notebooks or python scripts in the markdown_generator folder to generate markdown files for publications and talks from a TSV file.

See more info at https://academicpages.github.io/

Changelog -- bugfixes and enhancements

To support this, all changes to the underlying code appear as a closed issue with the tag 'code change' -- get the list here. Each issue thread includes a comment linking to the single commit or a diff across multiple commits, so those with forked repositories can easily identify what they need to patch.