📘
Lab Website Template docs
  • Introduction
    • Overview
    • Is this right for me?
    • Gallery
    • Support
  • Getting Started
    • Set up your site
    • Set up your URL
    • Tidy up your repo
    • Change your site
    • Preview your site
  • Basics
    • Repo structure
    • Configure your site
    • Edit pages
    • Write basic content
    • Use your logo
    • Customize your theme
    • Team members
    • Blog posts
    • Citations
    • Components
      • Section
      • Figure
      • Button
      • Icon
      • Feature
      • List
      • Citation
      • Card
      • Portrait
      • Post Excerpt
      • Alert
      • Tags
      • Float
      • Grid
      • Cols
      • Search
      • Site Search
  • Advanced
    • Update your template
    • Embeds
    • Math, diagrams, videos, etc.
    • Analytics
    • Data and collections
    • Jekyll plugins
    • Custom components
    • Background knowledge
Powered by GitBook
On this page
  • Template vs. user content
  • Template repo only content
  • Images and other assets
  • Data and components
  • Full accounting
  1. Basics

Repo structure

A brief explanation of the folders and files in the template

PreviousPreview your siteNextConfigure your site

Last updated 8 months ago

Most of this structure is enforced by Jekyll. See more thorough explanation of some of the items here.

Template vs. user content

The most important distinction to make is between template content ("under-the-hood" stuff needed for the general functioning of the template) and user content (stuff for your specific website).

In general, here's how the files and folders in the template fall into these two categories. We've tried to keep these as separated as possible, within the limitations of Jekyll.

User content
Template content

Folders

/blog /images /team etc. (starting with letters) /_data

/_members

/_posts (_ exceptions)

.github

.docker

etc. (starting with .)

_cite

_includes

_plugins

etc. (starting with _, except a few 👈)

Files

_config.yaml (top portion of file)

/_styles/-theme.scss 404.md index.md README.md

_config.yaml (bottom portion of file) .gitignore CITATION.cff

Gemfile

Gemfile.lock LICENSE.md

Template repo only content

There are a few files and folders that are needed for the lab-website-template repo itself, but don't belong in your generated/forked repo at all:

  • CHANGELOG.md

  • testbed.md

  • .github/ISSUE_TEMPLATE

  • .github/workflows/versioning.yaml

  • .github/pull_request_template.md (rename user_pull_request_template.md in its place)

Keeping these files in your repo wont break anything per se, but they do increase clutter and confusion. The process automatically removes and renames these for you, but when be sure not to accidentally re-add them to your repo.

Images and other assets

The template comes with a default /images folder to hold all your site's images, but you can organize your images however you'd like. For example, you could put photos of your team in /team/photos/ and just refer to them like team/photos/anna-sun.jpg.

You could also create /videos or any other folders you need for static assets and refer to them in the same way.

Data and components

Data/collection
Matching component

citation

card

portrait

post-excerpt

Full accounting

Folder or file
Description

/_cite

/_data /_members /_posts

/_includes

/_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.

/_plugins

/_scripts

Script files that add interactive features to the website like search, GitHub tag import, tooltips, etc. These scripts have some configuration options, but edit with care. Any JavaScript file you add here will automatically be included in your site.

/_site

The "compiled" output from Jekyll, i.e. the actual content that gets published as your live site. You'll only see this if you've built/previewed your site locally. Changes to it will get overwritten every time the site is rebuilt, so don't edit it directly.

/_styles

/.docker

/.github

Files related to GitHub, mostly Actions workflows that perform automated tasks when you make changes to your repo.

/blog /contact /research etc.

/images

_config.yaml

.gitignore

Files to not be tracked/included in your site's repo.

404.md

When a visitor goes to a page on your site that doesn't exist, this page gets loaded instead.

citation.cff LICENSE.md

Metadata about the template itself.

Gemfile Gemfile.lock

Files that specify Ruby package dependencies for Jekyll and its plugins.

index.md

The homepage of your site!

README.md

What people see when they go to your repo on GitHub.

The only exception to this is your and , which the template expects to be in /images.

The template comes with a few placeholder and matching for common needs:

(/_data/citations.yaml)

(/_data/projects.yaml)

(/_members)

(/_posts)

A piece-by-piece breakdown of the folders and files in the template. You don't have to , but it helps to know generally what each piece is for.

Python code, plugins, and cache that perform the .

on your site for things like your team and blog.

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

Special Ruby files that extend the functionality of Jekyll and Liquid. These are essentially custom Jekyll plugins, where no could be found.

Style files that determine how the site and look. Any Sass or CSS files you add here will automatically be included in your site. Sass files must contain a to be processed by Jekyll.

Files needed for .

The of your site.

The default folder for your site's .

, along with some advanced Jekyll settings.

this page of the Jekyll documentation
first time setup
updating your template version
logo files
fallback image
data lists
components
understand the inner workings of all of this
Citations
Projects
Team members
Blog posts
cite process
Data and collections for large lists of items
components
existing plugins
pages
Basic settings and configuration for your site
images
components
previewing your site locally
front matter