How to use academicpages.github.io: setup, editing and local preview

What you need before you start

You need a GitHub account. The README says to register one if you don't have one and confirm your e-mail, and notes that confirmation is required.

Editing the site means changing a configuration file and Markdown content files, so you should be comfortable working with text files. Local preview has its own prerequisites, covered in a later section.

• A GitHub account with a confirmed e-mail address
• Comfort editing YAML and Markdown files
• Git, Ruby with ruby-dev and bundler, and Node.js if you want to preview locally (optional)

Create your site from the template

Click the "Use this template" button in the top right of the repository page. On the "New repository" page, name the public repository "[your GitHub username].github.io". The README states this name also becomes your website's URL.

Check the site's status by going to the repository settings and opening Settings -> Pages -> Source: GitHub Actions.

• Click "Use this template"
• Name the new public repository [your GitHub username].github.io
• Confirm Settings -> Pages -> Source is set to GitHub Actions

Configure the site in _config.yml

Edit the site-wide settings in `_config.yml`. The README asks you to check two values in particular: the `url` must match the repository name you chose, and `repository` must reflect the correct path for your repository.

• Set url to the address you selected in the previous step
• Check that repository shows the correct path

Add your content and files

Write your site content in the Markdown files. To publish documents such as PDFs or .zip files, place them in the `files/` directory. The README says they will then appear at https://[your GitHub username].github.io/files/example.pdf, so you can link to them from your pages.

For publications and talks, the optional `markdown_generator` folder contains Jupyter notebooks and Python scripts that generate Markdown files from a TSV file.

• Put PDFs, zip files and similar documents in files/
• Use the markdown_generator folder (optional) to create publication and talk pages from a TSV file

Preview the site on your computer

Local preview lets you see changes before you push them to GitHub. Clone the repository first and make your updates. The README gives install commands for Debian, Ubuntu and WSL, and for macOS you install Ruby and Node with Homebrew and then run gem install bundler.

Run bundle install to install the Ruby dependencies. If you get errors, the README says to delete Gemfile.lock and try again. If you hit a file permission error, set the gems to install locally in vendor/bundle. Then start the server. Jekyll serves the site at localhost:4000 and rebuilds pages when Markdown or HTML files change. Changes to the core template or to _config.yml require you to stop and restart Jekyll.

• Debian, Ubuntu or WSL: sudo apt install ruby-dev ruby-bundler nodejs
• Install gems: bundle install
• Permission errors: bundle config set --local path 'vendor/bundle'
• Start the preview: jekyll serve -l -H localhost, then open localhost:4000
• Linux may also need: sudo apt install build-essential gcc make

Use Docker or the VS Code Dev Container instead

If you are on a different operating system or want to avoid installing dependencies, the README describes a Docker route. You need Docker installed. Run the commands from inside the repository, then open localhost:4000. The README also describes a Dev Container for Visual Studio Code: use F1 and then DevContainer: Reopen in Container, and the site is hosted locally at http://localhost:4000.

• Docker: run the commands in the repository folder, then open localhost:4000
• VS Code: use F1 -> DevContainer: Reopen in Container

Keep up with template updates

If you only edit configuration and content, you can use the "Use this template" copy directly. If you plan to submit bug fixes or enhancements as pull requests, fork the repository instead. The README warns that if you customize the template, synchronizing with upstream updates will probably cause merge conflicts. Rebasing and cherry-picking can help, and the README says that if you are not comfortable with Git, you can save your .yml and Markdown files, delete the repository and fork it again.

• Template copy: suited to editing content and configuration
• Fork: needed for pull requests and syncing upstream changes
• Heavy customization can cause merge conflicts when you sync