-
Notifications
You must be signed in to change notification settings - Fork 296
Basic Editing
The tasks/files you'll most commonly be doing/using.
- 📃 Pages
- ⚙️ Config File
- 🖼️ Images
- 🎭 Favicons
- 🤖 Automatic Citations
- 👥 Team Members
- 🖊️ Blog Posts
- 📊 Data and Collections
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.
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 your site is being hosted from, e.g. some-domain.com/ vs some-domain.com/some-folder.
This is necessary for links between different pages on your site to work.
To start, you should set this to whatever you named your repo, because by default your site will be published at a url like https://your-lab.github.io/your-lab-website/.
If you're hooking up a custom domain or otherwise hosting your site from the root directory, set this to "".
links
Links to show in the footer of every page, without any prefixes like @, www., etc.
See the link component.
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.
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.
The template makes citing papers and other publications much easier. Just provide an id for the paper (and some additional metadata if you want), and the template will fill in the authors, publisher, date, etc. using Manubot.
Input the sources you want to cite in /_data/sources.yaml, push the new file to GitHub, and citations will be automatically generated and saved to /_data/citations.yaml.
The citations then can be displayed in a variety of ways.
Example:
# a source
- id: doi:10.12345
image: https://image-database.com/some-image
tags:
- biology
- big data
- medicine
repo: your-lab/some-repo
extra-links:
- type: source
link: https://github.com/your-lab/some-repo
- type: website
text: My Personal Website
link: http://some-website.com/
# another source
...id
Identifier that Manubot can understand and cite:
An identifier type (like doi, url, isbn, pmc, pmcid, pubmed, arxiv, etc.), then a :, then the id of the paper.
See here for a full list of identifier types that Manubot supports.
image
Url to a striking image for the source.
tags
List of tags for the source, along with any tags fetched from repo.
See the tags component.
repo
GitHub repo for the source to automatically fetch tags (aka "topics") from.
extra-links
List of additional links for the source, aside from the one Manubot generates for the citation.
See the link component.
date / authors / publisher / other
In rare cases, you may want to override information that Manubot generates for the citation.
Any field you manually put in the input will be passed through untouched to the output.
Dates should be YYYY-MM-DD.
If you have hundreds of sources, generating the citations for all of them can take a while.
To save time, when going through the list of source, the template skips ones that are already in /_data/citations.yaml (that have the same id field).
To clear this "cache", simply delete the output file.
Or if you want to re-generate the citation for a particular source, find its entry in citations.yaml and delete it.
Note: Even if a source is skipped, any field you manually put in the input will still be copied over.
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
description: Senior Programmer
role: 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.
description
Description to show under the team member's name and role. Usually you'd put the team member's job title/position here.
role
Role (e.g. "programmer", "undergrad", "phd", etc.) to assign to the team member.
See the role component.
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.
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.
There are two main ways to create and maintain large sets of items.
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
...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
✨ The documentation for v1.0.0 and above are now at https://greene-lab.gitbook.io/lab-website-template-docs.