Advanced Editing

More advanced tasks/files that you might be doing/using if you want to really customize the template further. Make sure you know what you're doing!

Table of Contents

• 💬 Blog Post Comments
• 🎨 Theme
• 🎞️ Layouts
• 🧱 Includes
• 🔌 Plugins
• 🚧 Build Site Locally
• 📇 Build Citations Locally
• ⬜ Whitespace Quirks
• ⚙️ Under the Hood

Blog Post Comments

Having comments on blog posts (or elsewhere) isn't a trivial feature to implement. There needs to be 1) a plugin on the page that lets users log in, read comments, and post new ones, and 2) a server running to receive, permanently store, and retrieve comments.

It's beyond the purview of this template to build in solution for this, but luckily there are many third party ones that can be easily integrated:

• Disqus
• Facebook Comments
• Hyvor Talk
• Staticman
• Schnack
• Remark42
• Isso

...to name a few. Research the options carefully.

Some are full services that take care of the plugin and server for you. Usually for these, you just create an account the paste the code snippet they give you anywhere you want a comment section to appear, e.g. at the bottom of /_layouts/post.html. If the code snippet requires a unique page identifier, use {{ page.url | absolute_url }}.

Others just give you a plugin and the tools you need to run your own server, giving you greater privacy and security, but requiring more work to set up.

Theme

/css

Style files that determine how the site and components look.

/css/theme.scss has a few overarching "theme" variables/settings you can change to make your site look a bit different from other sites made with the template.

If changing fonts, make sure to also update /includes/fonts.html if you're using online fonts like Google Fonts (recommended). The template makes use of font weights from regular to bold, so include every weight between Regular 400 and Bold 700 italic as long as loading time isn't an issue. Always include at least Regular 400.

Layouts

/_layouts

The HTML templates that all pages are built upon.

default.html is the default layout for all pages, and should never really be edited.

Team member pages and blog post pages have their own layouts in member.html and post.html, which inherit from default.html, and can be edited to add/remove/rearrange sections.

Includes

/_includes

Reusable, small snippets of HTML that can take parameters. This is where the code for components are, if you need to modify them.

Plugins

/js

JavaScript files that add interactive features to the site, such as tooltips. These plugins have some configuration options, but edit with care.

Build Site Locally

Normally your site is built automatically on GitHub if you're using one of the standard workflows. But if you want to preview changes to your site before pushing them to your GitHub repo for all to see, you can follow these steps to build and run the site on your computer. Most people wont need or want to do this.

1. Install Ruby v3+ (on Windows, use the installer and the recommended version with the Devkit).
2. Install Bundler by running gem install bundler.
3. Install Jekyll by running gem install jekyll.
4. Go to the folder where you cloned your site, e.g. cd your-lab-website.
5. Bundle the site by running bundle.
6. Start the site by running bundle exec jekyll serve --open-url --livereload --trace.

If you're on Windows and getting errors, see this thread.

The site should automatically open in a browser. Any changes you make should automatically rebuild the site and refresh the page, except for changes to _config.yaml which require re-running the start command.

Build Citations Locally

Normally your citations are built automatically on GitHub if you're using one of the standard workflows. But if you want to preview changes to your citations before pushing them to your GitHub repo for all to see, or GitHub is having problems generating the citations, you can follow these steps to run the automatic citation process on your computer. Most people wont need or want to do this.

1. Install Python (with PIP).
2. Go to the folder where you cloned your site, e.g. cd your-lab-website.
3. Install needed Python packages by running python -m pip install --upgrade --requirement ./auto-cite/requirements.txt.
4. Add or change the desired sources/papers in /_data/sources.yaml.
5. Generate citations by running python ./auto-cite/auto-cite.py.

Citations should be automatically generated and output to /_data/citations.yaml.

Whitespace Quirks

If you're customizing this template, you might run into whitespace quirks with Liquid and Markdown.

Liquid has special syntax to trim whitespace on either side of Liquid tags. Sometimes this matters, like when you have expressions on separate lines that might evaluate to blank, leading markdown to insert blank paragraphs, messing up layout. We recommend only adding the trim syntax when you observe unwanted whitespace/paragraphs in your resulting site.

When putting HTML in Markdown, prefer putting opening and closing tags on one line to avoid confusing the Markdown parser. Instead of this:

<a
  href="https://some-site.com/"
  data-tooltip="Some Site"
>
  Some Site
</a>

prefer this:

<a href="https://some-site.com/" data-tooltip="Some Site">
  Some Site
</a>

Under the Hood

Files and folders used internally by Jekyll or other tools in the setup. You probably won't ever need to edit these.

• 404.md - A fallback page for when a user goes to a page that doesn't exist on your site.
• .gitignore - Files to not be tracked/included in your site's repo.
• /_site - The "compiled" output of the entire Jekyll site. Changes to it will get overwritten every time the site is rebuilt. This folder is the actual content that GitHub Pages publishes as your live site.
• /.github - Files related to GitHub, including ones that execute automatic citations
• Gemfile and Gemfile.lock - Files that specify the package dependencies of the project. Similar to package.json and package-lock.json in npm.