Note on the AllFredHutch team. We want everyone included, but GitHub can be chatty. Go here to see how to set your personal settings to NOT automatically watch every team you are part of.
This curated Wiki relies upon the Fred Hutch research community itself to improve, expand and evolve over time. Because the wiki's content spans many research areas, we need and welcome contributions from a similarly wide range of researchers and Fred Hutch staff whether as novice reviewers for a topic outside of their expertise or as expert contributors for those topics of most interest to them. No contribution is too little (or too large).
Contributing Directly via GitHub
Contributing via an external editor
Building a copy of this wiki locally
We manage the content of this site via a set of markdown files that contain long article-style text with an emphasis on the use of outline structures to allow related content to show up near each other but with the ability to use the automatically rendered Table of Contents to jump around the documents.
To edit one of the content-containing markdowns (see below regarding Repo structure for more info about where these markdowns are) from GitHub, follow these steps:
- Create a branch off the master branch for your edits (do not fork the repo or create branches from other branches). Consider naming the branch in such a way that indicates what domain the edits will primarily be in (such as "generation-typos" or "intro-to-rhino"). Avoid making branches with uninformative names whenever possible. For your content to be merged into the master, it will need to be edited by others, and it is possible that others may have substantial content to add to your edits. If the branches are named according to content being added (generally) then others can contribute to that content too.
- Commit your edits to existing markdowns as you go, and update from the master branch before continuing to work on your branch. You will reduce future conflicts if you get in the habit of updating from the master and committing frequently.
- Publish/push your branch to GitHub to save your work and let us know you're working on something.
- When you are done editing, create a pull request from your branch. Suggest reviewers based on the content of the edits. Request admin assistance if your content may be new and need to be hooked up to the sidebar or other web-specific needs (this is currently done by tagging
vortexingorbmcgoughfor a review).
>Note: If you are editing existing content and the page has a listing for the Primary Reviewers like this:primary_reviewers: somegithubusernamethen when you submit the pull request please request a review from those usernames. - Reviewers will sign off on edits by approving or providing comments on a pull request, ideally one "expert" and one "novice" based on field of expertise. If there is a
primary_reviewerlisted for content then one of the reviews must be from one of those members. Others may move your content to combine it with other work, or make edits that you may want to review as well. Keep an eye on your pull requests and comments on it in order to check back in if someone's edits need your review as well. - Once reviews have been obtained, the pull request can be merged into the master and then any edits go live to the site here.
Afterwards: Please remember to make a markdown for yourself in our
_contributorsdirectory so that we can give you credit for your contributions publicly on the site.
You can also contribute to the wiki from external editors that can interoperate with GitHub. We have had good experience with Atom but other text editors have GitHub integration as well. Also there is a tutorial on how to use VSCode which is what you will want to use if you plan to contribute many screenshots or other images.
The content of this site is generated using GitHub "flavored" markdown. A cheat sheet for the code required to create things like headings and table is here. Our page TOC's are generated from these headings, so use ## H2 as your first level, and headings H2, H3 and H4 show up automatically in our TOC's).
Our goal is the generate article-style content (with the exception of the demo's/resource library pages), with the following general sections:
An introductory paragraph summarizing the page must be included and should be comprehensible for novices and experts alike. This paragraph is a good place to define domain-specific words that appear in your article. Also include a description or set of examples that might highlight why the reader might want to keep reading, whether they are novice or expert. Good introductions can use your own research project to give the reader some context.
The main content of the pages is up to you to structure. Keep in mind that the wiki's articles are meant to provide enough background for a variety of readers to know what sorts of questions related to their particular research to pose when looking for in-person help. Create headings that an advanced user could use the TOC links to go directly to the content they want while novices can also browse and slowly increase the complexity of the material throughout the page. This gradual increase in content complexity from basic to advanced will give a reader some basic understanding of the topic before heading directly to the particular web-based (Fred Hutch sponsored or otherwise), in-person training/office hours, or on-campus expert to discuss or learn about their project in more detail.
Since we are not intending to write comprehensive explanations, the Available Resources sections in our Wiki are really the intended endpoint for our readers. This section should focus on linking to comprehensive and established external educational resources of interest to the topic, online training tools from established entities, additional more detailed Fred Hutch documentation provided by Fred Hutch based experts/providers, in-person training opportunities at the Fred Hutch or locally, and if possible and approved by the expert, specific highlights of on-campus experts in a given field who are willing and able to provide consulting or advice on the topic. Please make sure all links to any other site are correct and tested!!!!
If a content section is relatively short and cohesive, there should be one Available Resources section at the bottom of the page. However, as content sections grow and perhaps themes evolve, consider having a specific Available Resources section after the end of a unified topic section for which the resources mentioned are thematically related.
If you would like to insert a link to another page in our site, please use:
[text you want to have highlighted](/page_name/)
If it is a link to an external site use:
[text you want to have highlighted](https://my.url.com)
If you'd like to add images to your entry, some text editors (eg. Atom or VSCode via their respective plugins) allow for copy-and-pasting of images. You can read some instructions on how to get set up with VSCode in one of the Computing Demo's.
One edit is that in order for Jekyll to correctly render the images in a page, the following text is the example format that that call to the image needs to be in for a markdown in the _compdemos folder:
If the markdown you are editing is in one of the other folders you'll need to change the compdemos string to whatever the text of your folder is.
Both Atom and VSCode will make a directory called assets in the directory where the markdown is, and then will copy your in-text image file there so you can commit it all to the repo.
When linking to videos like screencasts you typically want to show an image screenshot and clicking on that screenshot starts the video. Images of videos are stored at https://img.youtube.com/vi and they use the same video id you find in Youtube URLs, so The Gift of Time is https://youtu.be/rN7cmb1K2yA. To embed, insert this into markdown:
[](https://youtu.be/rN7cmb1K2yA "Click to see The Gift of Time")
It is also important to consider the following parameters for videos from outside sources:
rel=0- this restricts the related videos shown at the end of payback to videos from the same channel rather than account-based recommendationsiv_load-policy- set to 1 to display video annotations by default and 3 to disable annotations
So the above link modified would be:
[](https://youtu.be/rN7cmb1K2yA?rel=0&iv_load_policy=3 "Click to see the amazing kitten")
If you need to make screencasts, free software exist for Windows, Linux, and OSX.
Please if you need to reference a Fred Hutch username, do not write the entire email address out, just put the username in backticks like this:
`username`
NOTE: All draft content should be stored in the
draftfolder until it is ready for publication, and then an admin will move it to where it needs to go if it is new content, OR the writer can move demo's themselves when they are ready to go live.
For new content: https://github.com/FredHutch/wiki/blob/master/draft/contentTemplate.md
For new contributor entries: https://github.com/FredHutch/wiki/blob/master/draft/contributorTemplate.md
Data Generation Content, organized with filenames that start with xxx_ based on what section they are intended to show up in the sidebar: https://github.com/FredHutch/wiki/tree/master/_generation
Data Generation Resource Library (note all markdowns in this folder will be rendered): https://github.com/FredHutch/wiki/tree/master/_gendemos
Bioinformatics Content, organized with filenames that start with xxx_ based on what section they are intended to show up in the sidebar: https://github.com/FredHutch/wiki/tree/master/_bioinformatics
Bioinformatics Resource Library (note all markdowns in this folder will be rendered): https://github.com/FredHutch/wiki/tree/master/_infdemos
Computing Content, organized with filenames that start with xxx_ based on what section they are intended to show up in the sidebar: https://github.com/FredHutch/wiki/tree/master/_computing
Computing Resource Library (note all markdowns in this folder will be rendered): https://github.com/FredHutch/wiki/tree/master/_compdemos
Contributors List (note all markdowns in this folder will be rendered): https://github.com/FredHutch/wiki/tree/master/_contributors
You may want to build a copy of this wiki locally (on your own computer) to make sure that it looks the way you want before pushing your changes.
-
clone the repo somwhere
-
Install Ruby (version 1.9.2 or later). Note: most modern Mac computers already have Ruby installed. If you still need Ruby, it can be found here.
-
On Mac, install xcode commandline tools
xcode-select --install -
You may need to install
bundler. Typewhich bundlerto see if it is already installed. If nothing is returned, then installbundlerwithgem install bundler. If that fails, trysudo gem install bundler. -
To build and view the site locally, from the cloned repo directory run
bundle installthen runbundle exec jekyll serve. Once the site is built you can view it at http://localhost:4000.
To check for broken links, you can type
rake test. This will exit with an error if there
are any broken links, and list the broken
links and the files they are found in.
If you are inside the Fred Hutch network, you can type
rake testlocal and that will include internal URLs
in the check (these are normally excluded because CircleCI does
not have access to them).
You can also look at the most recent CircleCI build to see the list of broken links.
Computing: https://github.com/FredHutch/wiki/blob/master/computingdemos.md
Bioinformatics: https://github.com/FredHutch/wiki/blob/master/informaticsdemos.md
Contributors list: https://github.com/FredHutch/wiki/blob/master/contributorslist.md
Main website configuration file: https://github.com/FredHutch/wiki/blob/master/_config.yml
Navigation yml: https://github.com/FredHutch/wiki/tree/master/_data
Custom styling that overrides the remote theme: https://github.com/FredHutch/wiki/tree/master/assets/css
Header and footer configs: https://github.com/FredHutch/wiki/tree/master/_includes