Skip to content

Basic Editing

Vincent Rubinetti edited this page Jun 14, 2021 · 152 revisions

The tasks/files you'll most commonly be doing/using.

Table of contents

Pages

To create a new page on your site, simply create a new folder, create a file in it named index.md, and fill it with content. The folder name is what will appear in the url, and index.md will be the main page for that folder. For example, to create a page at yoursite.com/awards, create a folder named awards.

"Index" is a naming convention for referring to the "main" page of a particular folder. Navigating to yoursite.com/awards would actually take you to yoursite.com/awards/index.html (generated from /awards/index.md). Likewise, the index.md file in the root of the template is the landing/home page for your site.

The pages built into this template – /blog, /contact, etc – are just a side effect of this behavior. You can delete/change/add them at will to change what pages are on your site.

Example:

---
title: Awards
description: Description for this page
nav:
  order: 1
  tooltip: Praise and laurels

header: images/header-for-this-page.jpg
footer: images/footer-for-this-page.jpg
header-dark: false
footer-dark: false
---

Some text written in Markdown for the Awards page.

title

The title of the page. Shown in the tab name along with your site title, e.g. Your Lab Website - Awards.

description

Description of the page that will show under search engine results. Overrides the site-wide default in the config file.

nav

If this field is present, the page will appear in the header navigation bar, with the same name as the page's folder.

If your nav bar ends up being longer/wider than default one, make sure to check the @media lines in the header styles.

nav: order

How the page should be ordered in the nav bar. The nav bar links are sorted by this field, lowest to highest, and left to right.

nav: tooltip

Text to show when hovering over the page's nav bar link.

header / footer

Background image for the header/footer of the page. Can be set to none to display a solid color.

Overrides the site-wide default in the config file.

header-dark / footer-dark

Whether to make the header/footer solid background color dark or light. Defaults to true.

Overrides the site-wide default in the config file.

Config File

_config.yaml

The main configuration for your site. Contains important site-wide settings and variables.

Example:

### basic settings

# site properties and page defaults
title: Lab Website Template
description: An easy-to-use, flexible website template for labs, with automatic citations, GitHub tag imports, pre-built components, and more.
logo: images/logo.svg
logo-text: false
header: images/background.jpg
footer: images/background.jpg
baseurl: /lab-website-template

# site social media and other links
links:
  email: [email protected]
  google-scholar: Jane Smith
  github: your-lab
  twitter: YourLabHandle
  instagram: YourLabHandle
  youtube: YourLabChannel

# advanced settings to ignore
...

title

Title of your site. Appears in the tab title, in the header, and in metadata.

If your title is longer/wider than "Lab Website Template", make sure to check the @media lines in the header styles.

description

Default description of pages that will show under search engine results.

logo

Logo image for the site, in .svg, .png, or .jpg format.

logo-text

What text to put next to your logo in the header. Defaults to the title of your site.

If your logo already contains the title of your lab and you have no version of it without text, you can also set this field to false or "" to show no text.

header / footer

Default background image for the header/footer of pages. Can be set to none to display a solid color.

header-dark / footer-dark

Whether to make the default header/footer solid background color for pages dark or light. Defaults to true.

baseurl

Tells Jekyll what directory, relative to the root, your site is being hosted from. Basically, this is the part of the url that is after the domain but before the sub-pages on your site, like https://some-domain.com/BASEURL/about-page. This field needs to be set correctly for your website to appear correctly, and for links between different pages on your site to work.

Examples:

  • If you named your repo normally, set this to whatever you named your repo, with a preceding forward slash, like /your-lab-website.
  • If you are making a GitHub user site, set this to "", and make sure you've named your repo accordingly.
  • If your site has a custom domain, like https://your-lab.com/, set this to "".

links

Links to show in the footer of every page, without any prefixes like @, www., etc.

See the link component.

Images

/images

A default folder to hold all your site's images. You can organize and place your images however you want though. For example, you could put photos of your team in /team/photos/ and just refer to them like team/photos/anna-sun.jpg.

To actually insert images into your site, use components like the figure component or the gallery component.

Note: placeholder.svg is a default fallback for any image that isn't specified or can't be loaded.

Favicons

/favicons

A special folder for icons for when your site is bookmarked in a browser, added as an app shortcut on a phone, and shared on social media. These are important for your branding! Replace these images with variations of your own logo, taking care to match the size and cropping. They can be transparent, but make sure they can be distinguished on any background, dark or light.

realfavicongenerator.net can help you generate all the necessary icon variations, but it goes overboard with its support for unused legacy browsers like Internet Explorer. What's included in this template is a simplified subset that should work fine on all modern browsers.

Note: /_includes/favicons.html and /favicons/site.webmanifest assume this folder is called /favicons.

Team Members

/_members

Where your team member bios go. Each file will automatically generate its own page according to its filename. For example, a file with the name tim-member.md will generate a page at yoursite.com/members/tim-member.

You can also list all of your team members in one spot with the list component.

Example:

---
name: Tim Member
image: images/team/some-image.jpg
role: programmer
description: Senior Programmer
aliases:
  - T Member
  - T. Member
  - Timothy Member
links:
  home-page: https://tims-website.com/
  email: [email protected]
  twitter: tims_twitter
---

A bio for Tim, written in Markdown.
A descriptions of his academic studies, his recent accomplishments, his goals for the future, his likes/dislikes, etc.
One or two paragraphs is probably best.

name

Name to show on the team member's page.

image

Url to a portrait photo of the team member.

role

Team member's general role (e.g. "programmer", "undergrad", "phd", etc.) in your organization.

See the role component.

description

Team member's job title/position.

aliases

Team member pages have a link at the bottom that goes to the "Research" page and searches for any papers with the team member's name. This field is a list of aliases or variations of the team member's name to search for that might be cited in papers.

links

Social media links/handles for the team member, without any prefixes like @, www., etc.

See the link component.

Blog Posts

/_posts

Where your blog posts go. Each file will automatically generate its own page according to its filename. Name your post files in the format YYYY-MM-DD-your-post-title.md, and pages will be generated at urls in the format yoursite.com/YYYY/MM/DD/your-post-title.

You can also list all of your blog posts in one spot with the list component.

Example:

---
title: An ordinary day in the life of me
author: Tim Member
member: tim-member
tags:
  - biology
  - big data
  - medicine
---

A blog post written in Markdown.

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

title

Title for the blog post.

author

Author for the blog post.

member

Filename of the author's team member page (without .md) to link to.

tags

List of topics/themes for the blog post.

See the tags component.

Data and Collections

There are two main ways to create and maintain large sets of items.

Data

If you want to have a large set of structured or nested items in a single file, use data files. Put a .yaml file in the /_data folder with any name, and fill it with data. The structure of the data can be arbitrary, except that the top level must be a list/array so it can be looped through.

These items can then be displayed in one spot with flexible formatting with the list component.

Example:

# some item
- title: Some name
  tags:
    - tag A
    - tag B
  description: Some description

# another item
...

Collections

If you want to have a large set of items in separate files, that can also generate their own separate pages on your site, use collections. The template already includes two collections: /_members and /_posts.

Any sub-folder prefixed with a _ will become a collection. To also generate a page for each item in the collection, set output: true as described here.

These items can then be displayed in one spot with flexible formatting with the list component.

Example:

---
title: Some item in one file
---

Some Markdown content
---
title: Another item in a different file
---

Some Markdown content

⚠️ This wiki is legacy documentation for the pre-release version(s) of the template, and will eventually go away!
✨ The documentation for v1.0.0 and above are now at https://greene-lab.gitbook.io/lab-website-template-docs.

🏠 Docs Home

🖼️ Gallery

▶️ Get Started

🗚 Basic Formatting

📝 Basic Editing

🤖 Citations

⚙️ Advanced Editing

🧱 Components

🧠 Background Knowledge

💡 Tips

❓ Support

Clone this wiki locally