Skip to content

Latest commit

 

History

History
1008 lines (714 loc) · 41.5 KB

CONTRIBUTING.md

File metadata and controls

1008 lines (714 loc) · 41.5 KB
Raw

Galaxy Community Hub Build Status

This is your guide to editing and contributing to the Galaxy Hub Website, the community and documentation hub for the Galaxy Project

The site content resides in the GitHub repository that you are in right now. Content is formatted using (mostly) GitHub Flavored Markdown (GFM) and the web site itself is rendered using the metalsmith static site generator.

Anyone can update and add content to the site using "standard" GitHub and Git practices, and contributions are strongly encouraged. If are already adept at Markdown, Git, and GitHub, you may want to skip to the Deploying the site locally section. If you are unfamiliar with any of those items, then start with the Basics

Table of Contents

Basics

Where's the source for the web site content?

The text that becomes the website at https://galaxyproject.org is in this GitHub repository (the repo you are looking at right now) under the /src directory.

One web page ≈ One directory in GitHub

Every page in the Galaxy Hub has a corresponding directory in GitHub. For example, the contents of the GitHub directory at /src/community/ become the web pages at https://galaxyproject.org/community/.

index.md files

Every directory contains an index.md file that contains the Markdown text for that directory. For example, the file in GitHub at /src/community/index.md becomes https://galaxyproject.org/community/.

When you update content on the Galaxy Hub you will mostly be updating index.md files.

Markdown

Markdown is a language for generating web content. It's meant to support the most common web page formatting (paragraphs of text, section headings, bold, italics, lists, and so on) without requiring you to learn the complications of HTML.

The Galaxy Hub uses a dialect of Markdown known as GitHub Flavored Markdown (GFM). GFM adds a few things, like table support, to the Markdown standard. GFM pages also render nicely in GitHub. GFM is limited (by design) in comparison to HTML. However, it is easy to learn and use, and if you ever need something more, GFM supports that too (see below).

Submitting your first edit through the GitHub web interface

If you aren't already familiar with Git and GitHub then the easiest way to update the site is using the GitHub web interface in your web browser.

If you don't already have a GitHub account, you will need to create one to contribute any edits. Once you are logged in to GitHub, navigate to the page you want to update within GitHub. There are two ways to do this.

1. Navigate to the page from within GitHub

Start at the root of the content tree (the /src directory) and navigate down to the page you want to edit. For example, if you want to edit the page at https://galaxyproject.org/community/ you would navigate:

/src → /src/community

Within the community directory you will see a few image files, and a file named index.md. Click on it.

2. Use the Edit link on any Galaxy Hub page.

You can jump from any page in the Galaxy Hub directly to its source index.md file in GitHub. Every Galaxy Hub web page has an Edit link in the upper right hand corner, that goes to that web page's index.md file in GitHub.

Edit the page in Github

To edit an index.md file in GitHub, click the pencil icon. (The icon only appears if you are logged in.) When you hover over the icon, GitHub displays

Fork this project and edit the file.

More on that in a bit. Clicking the pencil icon takes you to a web form where you can edit the page text. The top of the edit page says:

You’re editing a file in a project you don’t have write access to. We’ve created a fork of this project for you to commit your proposed changes to. Submitting a change to this file will write it to a new branch in your fork, so you can send a pull request.

GitHub has now given you your own copy of the galaxy-hub repository and you are now editing that copy under your account. Edit the text of the page in the web form. There is a Preview Changes tab you can use to review your edits before you commit them.

Once your edits are in good shape commit them by providing a short (and optionally, a longer) description of the change at the bottom of the form.

Click Propose file change at the bottom of the form. The commits the changes to your copy of the galaxy-hub repo. ("repo" = "repository" in GitSpeak).

What if I mess it up? Are there guidelines?

Thanks for your concern! But, we got this:

  1. Until you get the hang of this ( see What happens next and becoming an Editor below) all of your edits will be reviewed by an experienced editor before they go to the web site.
  2. There are guidelines below, but don't worry about them too much when you start. Just focus on the content you are fixing or adding. If you really want to "do the right thing" focus on the basic guidelines first, and then expand out as you need to.
  3. Be bold. We mean it.

You mentioned guidelines?

Guidelines are distributed throughout this document. Each is tagged with one of these icons:

Icon Level Guidance
🐣 A basic guideline. Try to follow these from the start.
🐥 A more than basic guideline. Once you get used to the basic guidelines, try to incorporate these into your edits.
🐔 An advanced guideline. Only worry about these if you are doing something, well, advanced.

The page doesn't look the same in GitHub

You may notice, even before you make any edits, that the page doesn't quite render correctly on the GitHub web site: images are in the wrong place or missing, some links don't work, and anything, well, fancy is rendered poorly.

This happens because the GitHub web site, and the galaxyproject.org web site use different tools to render the web site, and because galaxyproject.org uses tools that GitHub does not support.

Don't worry about these differences. Once you have become an experienced editor, you will switch to making edits in a locally installed copy and then you'll see the pages as they are actually rendered (and you can start making fancier edits).

In the meantime, there is one thing you can do to not make things worse for yourself and others using the GitHub web site to edits:

🐣 Format links to other pages within the Galaxy hub with a leading /src and a trailing index.md.

Links with both of these things will work in the GitHub web site. For example, links should be

/src/community/index.md

instead of just

/community

Create a pull request to add your changes to the hub web site

Clicking Propose file change takes you to a Comparing Changes page that highlights your changes to the file.

It also has a Create pull request button near the top of the page. If you are ready to submit your changes to be included in the hub web site then click this button.

If you have more changes you want to make before you submit, you can make more changes and then submit all the changes as a unit.

Clicking Create pull request (see What is a Pull Request?) takes you to the Open a Pull Request form.

Click Create pull request. You're ready.

This form has a space for comments that will be sent along with the pull request. The comments tell the pull request reviewers what these changes achieve.

Once you have added comments, click the Create pull request button. This sends your pull request to the @galaxyproject copy of the galaxy-hub repo, and then shows you the pull request you just submitted.

Congratulations. You have submitted your first web site edit.

What happens next and becoming an Editor

You can track the progress of the pull request here. When the pull request is approved it will be merged into the main repo and then appear on the Galaxy Hub shortly thereafter.

Furthermore, after a pull request or two, the reviewer will add you to the @galaxyproject galaxy-hub Editors group. From that point on you can edit pages directly in the root repo. That is, clicking the pencil icon on a page under https://github.com/galaxyproject/galaxy-hub/src will no longer fork the repo, and submitted changes will go directly to the repo and to the web site. (Our goal with this protocol is to encourage treating this like a wiki where folks are free to just edit. ( Galaxy is community )

In the meantime, you can continue to do edits in your copy of the repo and then submitting pull requests.

Doing more with the GitHub Web Editor

You can edit anything in the /src directory through the GitHub Web Editor and this is a good way to become more familiar with the process and how things are set up. Eventually you may want to switch to a local installation, but you don't need to.

There are only a few things that require special explanation

Create a new page

Every page in the Galaxy Hub is stored in a directory and matching index.md file. To create a new page, you need to create a new directory.

To create a new page, navigate to the directory you want to create the new page under. For example, if you want to create a /community/galaxy-south-africa/ page (just an idea!) then navigate to the the /src/community directory.

Click the Create new file button near the top and on the right of the directory listing page. This brings up an empty web form for naming the new file and providing the page content.

Remember "To create a new web page, you need to create a new directory." To do that, in the "Name your file..." box enter

your-page-name/index.md

When you save your new file, this will create a new directory under the current directory named your-page-name and your new file will be in that directory and named index.md.

Page path / naming conventions

When you specify a new page name / path there are two guidelines:

  1. 🐣 Use all lower case letters.
  2. 🐣 Separate words with hyphens.

In our example, the page name / path should be

/community/galaxy-south-africa/

not

/community/GalaxySouthAfrica/

Adding images / attachments through the GitHub editor

Note: You can upload images and attachments through the GitHub editor, but by the time you get to this level of editing you should consider editing a local install instead.

To add an image or attachment to the repo, navigate to the directory you want to place it in, and then click the Upload Files button, near the top and on the right. This launches a standard file upload form. Any uploaded files are added to the directory you are in and can now be referenced from pages within the hub.

Image and attachment guidelines.

There are standard image and attachment directories.

These are at /src/images/ and /src/document.

  1. 🐣 Before uploading a file, please make sure it is not already in one of these directories.
  2. 🐣 If it makes sense, please consider uploading the file to one of the standard directories. This encourages reuse.
  3. 🐥 If the file is bigger than 1 meg then don't upload it. Email it to [email protected] instead. We'll put it in the Galaxy Depot and then mail you a URL you can link to. (Keeping large files in GitHub is not a good use of GitHub.)
  4. 🐥 Consider renaming your files to be all lower case and hyphen separated before uploading them.

General Guidelines, Structure, and The Details

This section describes the hub structure and guidelines. This section is useful if you are updating the site through the GitHub web editor, or in a local install.

Markup

The Galaxy Hub website (galaxyproject.org) supports GitHub Flavored Markdown, Bootstrap markup, the FontAwesome library, and a smattering of items from Metalsmith. That's a lot of ways to do things.

What's the preferred way?

Favor GitHub Flavored Markdown over HTML

Anything that can be rendered with Markdown can also be rendered with HTML, but don't.

🐣 Whenever possible use GFM, even if it means things are less pretty than they could be. Markdown is much easier to edit and to make site-wide changes to how it is rendered.

Note: We use "Markdown" and "GFM" interchangeably to mean "GitHub Flavored Markdown."

Favor Bootstrap over custom HTML styling

Anything can be rendered with custom HTML styling, but don't.

🐥 Whenever possible use Bootstrap HTML classes for styling. Bootstrap automatically handles rendering on small devices and it is much easier to make site-wide changes to how it is rendered.

Favor Font Awesome Icons over custom icons

Font Awesome is a standard collection of icons that cover a huge spectrum of what you need icons for on a web site. As of 2017, there are over 600 icons to choose from.

🐥 If there is a Font Awesome icon for your situation then use it.

Font Awesome icons can be rendered in multiple sizes, shown with or without borders, floated left or right, animated (spin them!), rotated, and integrated with Bootstrap. See the Font Awesome Examples page for how.

Page metadata

One advantage of using metalsmith is that the site can support predefined metadata tags on pages. These can then be rendered / processed in special ways when the final web site is generated.

Metadata appears at the top of the file in this format:

---
autotoc: false
title: "Galaxy Hub-Bub"
---

Tags are written using YAML syntax and have the form

tag: value or tag: "value" or tag: 'value'

There are general tags that can be used on any page, and there are also specific sets of tags that can be used on specific sets of pages.

If you add tags to a page, and the tags aren't reflected on the generated web site, then the most likely problem is one of these:

  • Special characters in unquoted tag value. A lot of things, including hyphens can cause problems. If in doubt, quote it
  • Missing a space after the colon. That space matters.

General metadata tags

These tags can be used on any page.

title

  • Optional
  • Meaning
    • Title of the page
  • Use
    • Becomes the value of <title> HTML tag in the page and first page heading
  • Format
    • Free text all on one line. Should be wrapped in quotes.

autotoc

  • Optional
    • Default is true on most pages, false on news and events items
  • Meaninig
    • Whether to include table of contents in the right side
  • Use
    • Causes a table of contents to be displayed on the right on not.
  • Format
    • Boolean: either true or false

Section specific metadata

Many sections of the web site use custom metadata tags that enable advanced handling of pages in those sections. Usually, these custom metadata tag sets are used to generate section indexes at the root of those sections. For example, the in News and Events directory hierarchies every news item and event item starts with custom metadata tags for news and events respectively. These are then used to generate the news item and events lists on the web site.

News item metadata

News items root:

News item indexes displayed:

Add a news item

To add a news item, you'll need to create a directory for the item under /src/news/ and then create an index.md file in the new directory. The index.md file should contain the news item text, and start with these metadata:

title

  • Required
  • Meaning
    • Short title for news item
  • Use
    • Becomes the news item page title
    • Shown in news indexes / lists as the name of the news item.
  • Format
    • Free text all on one line. Should be wrapped in quotes.

tease

  • Optional
  • Meaning
    • Short bit of additional text about the news item
    • Meant to complement title
  • Use
    • display with the event title, when space allows.
  • Format
    • free text all on one line. Should be wrapped in quotes.

date

  • Required
  • Meaning
    • Date the news item was posted, or last modified
  • Use
    • Determines where in the news list the item shows up.
  • Format
    • 'YYYY-MM-DD' - Must be wrapped in quotes

News item example metadata

From /src/news/2017-09-galaxy-update/index.md

---
title: 'September 2017 Galaxy News'
tease: 'New events, pubs, openings, tools, ...'
date: '2017-09-06'
---

Event metadata

Events root:

News item indexes displayed:

Add an Event

To add an event, you'll need to create a directory for the item under /src/events/ and then create an index.md file in the new directory.

The index.md file needs to have at least the event metadata. Optionally, it can also have additional text about the event in the body of the page. How an event page is indexed depends of several things:

  1. If the metadata includes an external_url tag then the main event link in the index will point to that URL.
  2. If the metadata does not include an external_url tag then the main event link in the index will point to the event's hub page.
  3. If the metadata includes an external_url tag and has additional text in the body of the event page, then main event link in the index will point to the external URL, but it will be followed by an additional link to the event's hub page.

Thus you can control what links are used by setting or not setting external_url and by providing or not providing additional text in the body of the event page.

title

  • Required
  • Meaning
    • Name of the event or presentation.
  • Use
    • Becomes the event page title
    • Shown in the event list as the name of the event.
  • Format
    • Free text all on one line, and should be wrapped in quotes

external_url

  • Optional
    • If it is not present, the title text in the index will link to the event's Hub page.
  • Meaning
    • Where the title text links to when it is displayed in an index
  • Use
    • If present then title in the index links to this location.
  • Format
    • URL
      • Should be an external URL.

tease

  • Optional
  • Meaning
    • Short bit of additional text about the event.
    • Meant to complement title
  • Use
    • display with the event title, when space allows.
  • Format
    • Free text all on one line, and should be wrapped in quotes.

date

  • Required
  • Meaning
    • Date the event starts
  • Use
    • Determines where in events lists the item shows up.
    • Displayed as start date for the event.
  • Format
    • 'YYYY-MM-DD' - Needs to be wrapped in quotes.

days

  • Optional
    • If not provided then event is assumed to be one day long.
  • Meaning
    • How many days does this event last?
  • Use
    • Displayed end date for the event.
  • Format
    • an integer

location

  • Required
    • but can be "online" or "to be determined" or ...
  • Meaning
    • Where in the world is this event being held.
  • Use
    • Displayed wherever location is displayed
  • Format
    • A location in however much detail you want to provide.
      • There should be enough information that someday we could feed the location to a mapping service and have a reasonable expectation of it guessing at least the right city.
    • 🐥 Prefer longer region and national names to shorter ones. For example, California over CA, and United States over USA.
    • It's easier for people not from that country to read.
    • If the event's title refers to a specific event within a larger event, then include larger event's name in the location.
  • Examples
    • Iowa City, Iowa, United States
    • University of Iowa, Iowa City, Iowa, United States
    • Plant and Animal Genome XXV, San Diego, California, United States

location_url

  • Optional
  • Meaning
    • URL to link location to.
    • This can be a conference URL, or a host UR, or a facility URL, or ...
  • Use
    • If provided then the location text (all of it) will link to this URL.
  • Format
    • A URL

continent

  • Required
  • Meaning
    • What continent this event is being held on.
  • Use
    • An icon showing the continent is typically displayed with the event.
  • Format
    • Must be one of the following two letter values:
      • AF, AS, AU, EU, GL, NA, SA
      • GL stands for global and is typically used for online events.

image

  • Optional
  • Meaning
    • image / logo for this event
  • Use
    • Displayed on the event's hub page.
    • Display this image anywhere that events are summarized and images are included.
  • Format
    • a URL, preferably an internal hub path, usually point into to the /src/images/ directory.

contact

  • Optional
  • Meaning
    • Name or email address of who to contact about this event
  • Use
    • Display in events index.
  • Format
    • All on one line, and wrapped in quotes. Can be a list of names.

gtn

  • Optional
    • If not present then defaults to false
  • Meaning
    • Is this a training event presented by a GTN member?
  • Use
    • Display a GTN icon (that links to the GTN trainer directory page) in the index
  • Format
    • true|false

Event example metadata

---
title: "RNA-Seq analysis using Galaxy"
tease:
date: '2017-09-13'
days: 2
continent: AU
location: "QFAB, St Lucia, Queensland, Australia"
location_url: "http://qfab.org/"
external_url: "http://qfab.org/workshops/rna-seq-analysis-using-galaxy-13-14-sep-2017"
contact: '[email protected]'
gtn: true
---

Blog metadata

The Galactic Blog includes anything that is related to Galaxy and is longer than a news item.

Blog root:

There are two types of blog entries:

  • External: These blog entries were created outside the Hub, on some other platform. Typically, hub pages for external blog posts contain only enough information to populate the blog index page and link to the blog post. Everything is in the metadata.
  • Native: The content of these blog posts exists in the Hub. That is, the blog posts were first created in the Galaxy Community Hub. These posts have metadata, but also content below the metadata. The index points to the post's hub page.

Add a blog post

To add a blog post, you'll need to create a directory for the post under /src/blog/ and then create an index.md file in the new directory.

🐔 New directories (and thus blog post URLs) are named with this convention:

YYYY-MM-topic-in-one-or-more-words

Blog posts have this metadata:

title

  • Required
  • Meaning
    • Title of the blog post
  • Use
    • Becomes the blog page title
    • Shown in the blog post list as the name of the entry.
  • Format
    • Free text all on one line, and should be wrapped in quotes

tease

  • Optional
  • Meaning
    • Short bit of additional text about the blog post.
    • Meant to complement title
  • Use
    • display with the event title, when space allows.
  • Format
    • Free text all on one line, and should be wrapped in quotes.

date

  • Required
  • Meaning
    • Date the blog post was posted
  • Use
    • Determines where in blog index the item shows up.
  • Format
    • 'YYYY-MM-DD' - Needs to be wrapped in quotes.

authors

  • Required
  • Meaning
    • Who wrote the blog post
  • Use
    • Displayed in blog index and on blog post.
  • Format
    • Free text all on one line, and should be wrapped in quotes.

external_url

  • Optional
    • If present, the title text in the index will link to the external_url
  • Meaning
    • If a post has an external_url it means the post was created outside the Hub.
  • Use
    • If present then title in the index links to this location.
  • Format
    • URL
      • Should be an external URL.

source_blog

  • Optional
    • Only present if the post is external
  • Meaning
    • The name of the blog / place where it was posted.
  • Use
    • Displayed in blog index and in blog entry.
  • Format
    • Free text all on one line, and should be wrapped in quotes.

source_blog_url

  • Optional
    • Only present if the post is external
  • Meaning
    • The URL of the blog / place where it was posted
  • Use
    • Whenever source_blog is shown, it links to here.
  • Format
    • An external URL.

Blog post example metadata

---
date: '2017-07-25'
title: "Elixir, CLIMB, Sanger and the Galaxy Community Conference"
tease: "UK, UK, UK, and France"
authors: "Simon Gladman"
external_url: "https://www.melbournebioinformatics.org.au/projects-blog/uk-tour-2017-blog2/"
source_blog_url: "https://www.melbournebioinformatics.org.au/projects-blog/"
source_blog: "Melbourne Bioinformatics Projects Blog"
---

Use Galaxy Resource Directory metadata

Use Galaxy Resource Directory:

The Use Galaxy resource directory lists

  • all know Galaxy servers that are publicly accessible.
  • cloud services that support ready to launch Galaxy instances
  • Galaxy containers and virtual machines.

Add a resource

To add a new resource, you'll need to create a directory for the resource under /src/use/ and then create an index.md file in the new directory.

Resource entries have this metadata:

title

  • Required
  • Meaning
    • Name of the resource
  • Use
    • Becomes the resource page title
    • Shown in the directory as the name of the resource.
  • Format
    • Free text all on one line, and should be wrapped in quotes
    • Short is good.

url

  • Required
  • Meaning
    • URL of the project the resource is for. If the resource is available on only one platform, then this can be a link to the resource itself.
  • Use
    • Displayed on the resource page as the title
  • Format
    • URL

scope

  • Required
  • Meaning
    • Why does the resource exist? See Format below for options.
  • Use
    • Becomes a keyword for the resource
  • Format
    • Must be one of these three values:
      • "general"
        • This a general purpose genomics server providing tools useful across a wide range of domains
      • "domain"
        • The server specializes in a particular domain, often a methodology (e.g. RNA-Seq), or a branch of the tree of life.
      • "tool-publishing"
        • Primary purpose of the server is to make a group's tools easy to use by publishing them here.

platforms

  • Required
  • Meaning
    • an array that describes each platform the resource is available on. This array must have at least one entry
  • Use
    • Just brackets the list of platforms.
  • Format
    • Nothing on platforms line. Array following it must be well-formed.

Each platforms array entry has 3 items in it.

platform-group
  • Required
  • Meaning
    • What type of platform is this.
  • Use
    • Used to group resource with other resources of same type.
  • Format
    • Options are public-server, academic-cloud, commercial-cloud, container and vm.
platform-url
  • Required
  • Meaning
    • Link to this resource for this platform. This can link to a page that describes the resource, or directly to the resource.
  • Use
    • Used with platform-text to link to resource on this platform.
  • Format
    • URL, should be quoted.
platform-text
  • Required
  • Meaning
    • Name of this resource on this platform.
  • Use
    • Will appear in the link to the resource on this platform.
  • Format
    • Text, quoted.

summary

  • Required
  • Meaning
    • A brief description of the resource
  • Use
    • Displayed in resource directory index page, and on the resource's page.
  • Format
    • Free text all on one line, and wrapped in quotes. Can contain Markdown.

image

  • Optional
    • Path to an image for this resource
  • Meaning
    • The single image most likely to succinctly communicate what this resource is about.
    • At some point in the future a thumbnail of this image might be displayed in the server index too.
  • Use
    • If present then this is displayed in the upper right of the resource page.
  • Format
    • URL
      • an internal hub path is prefered, as those images don't disappear
    • Small images, around 300px wide or less work best.

user_support, quotas, citations and sponsors

  • Optional
    • All are optional.
  • Meaning
    • user_support: options for getting help; can include tutorials.
    • quotas: any limitations on using the system: disk, execution, is an account required, ...
    • citations: One or two publications that are about this resource.
    • sponsors: Who is behind this resource?
  • Use
    • Displayed on the resource page, each in it's own section.
  • Format
    • Each is a YAML bullet list with 0, 1, or more entries.
    • Each bullet item is quoted and can contain markdown.

pub_libraries

  • Optional
  • Meaning
    • This is the tag used to identify papers in the Galaxy Publication Library that use/reference/implement this resource.
  • Use
    • Causes a link to those papers to be displayed in the Citations section.
  • Format
    • Bullet list (some resources have more than one tag).
    • Each bullet item is quoted plain text.

Resource entry example metadata

---
title: "A-Game"
url: "http://beaconlab.it/agame"
scope: "domain"
platforms:
  - platform_group: "public-server"
    platform_url: "http://beaconlab.it/agame"
    platform_text: "A-Game server"
summary: "A Galaxy suite for tArgeted MEtagenomics"
image: "/src/use/a-game/agame-logo.png"
comments:
  - "A web service incorporating state of the art tools and workflows for the analysis of eDNA sequence data."
user_support:
  - "[A-Game Manual](http://159.149.160.68/galaxy/static/manual/)"
  - "[Example workflows](http://159.149.160.68/galaxy/workflow/list_published)"
quotas:
citations:
  - "[A-GAME: improving the assembly of pooled functional metagenomics sequence data](https://doi.org/10.1186/s12864-017-4369-z), Matteo Chiara, Antonio Placido, Ernesto Picardi, Luigi Ruggiero Ceci, David Stephen Horner and Graziano Pesole. *BMC Genomics* 201819:44, doi:10.1186/s12864-017-4369-z"
pub_libraries:
  - "A-Game"
sponsors:
  - "[BEACON](https://bioscienzebio.unimi.it/gruppo.php?id=26), [Dipartimento di Bioscienze](https://bioscienzebio.unimi.it/), [University of Milan](http://www.unimi.it/ENG/)"
---

Redirects

  • 🐣 To automatically redirect an existing hub page to another URL,

    • replace the header with

      ---
redirect: "new-url"
---

      • new-url can be either an internal relative URL ("/admin/config/tool-dependencies/", note the missing src at the front and the missing index.md at the end.) or point outside the hub.

      • You are encouraged to also drop all text from the page. Optionally, you can include something like:

        This tutorials index page has been merged with the new [Learn Galaxy](/learn/)
hub page, please check there for up-to-date references to tutorials.

  • 🐔 When deleting, consolidating, or renaming pages please save the urls by adding redirects to the rewrite file in the infrastructure playbook.

Edit a local copy on your laptop

Using the GitHub web editor either edits your local copy of the Galaxy Hub repo, or edits the Galaxy Hub repo directly (once you are an editor). The GitHub web editor is fine for "one page at a time" edits, but you as you start doing more advanced editing or using page metadata, Bootstrap, and Font Awesome, you'll want to move towards editing and then previewing a copy of the Galaxy Hub repo on your laptop. Unlike viewing in GitHub (which approximates the view), previewing your edits locally will show your edits as they will be rendered on the actual Galaxy Hub web site. Once you are happy with your edits, you'll submit them to the repo at GitHub from your laptop.

🐔 To edit and preview the site on your laptop, you will need a much better understanding of Git, GitHub, and know how to use the Linux / Unix shell. You will also need to install software.

Note: Git, GitHub, and the shell (a.k.a. command line interface) are valuable things to know, and as a working bioinformatician or researcher you'll want to learn them. If now is a good time to learn this then set aside a couple of days and dig in. However, if you don't have time now, then you may want to use the GitHub web interface until you do. If you want to learn these things in a short, intense workshop then we recommend Software Carpentry which teaches these items to scientists.

Setup

To edit and run the site locally, start by creating a fork of this repository. Before you clone your fork locally, make sure to install git- lfs because that's what we use for managing images. To install git lfs use linuxbrew on Linux systems or homebrew on OS X. Once you have installed brew simply run brew install git-lfs command.

Note that you should use the authenticated github URL (ie, [email protected]:galaxyproject/galaxy-hub.git) because otherwise you may get API rate limit exceeded error.

An example clone command, using the authenticated URL would be:

git clone [email protected]:galaxyproject/galaxy-hub.git

The only other dependency you should need is node.js. Most modern versions should work fine, but follow the instructions on nodejs.org if you would like to update.

Generate local website

Direct your terminal to the newly cloned galaxy-hub directory

cd galaxy-hub

To build and serve the site locally on port 8080, run:

make serve

Alternatively, to build the website into the build directory, without serving (for example, if you had an external web server configured to serve these files), run:

make build

Please see the Makefile for more information and options, including the ability to use a Docker-based node binary identical to what we use to build and publish the final build artifacts. If you would like to learn more about how it all goes together, feel free to browse the build targets in the Makefile, or the metalsmith build process, which is defined in build.js.

If you are having trouble building the site, your node_modules may not have been installed correctly and the first thing to try is to remove the directory and/or execute the following command to have them reinstalled:

touch package.json; make node_modules

If you are using MacOS and see a error: xcrun message, you will need to install Command Line Tools. Enter the command:

xcode-select --install

Handling of images

Handling of image files is done using git-lfs. If you want to add new images, make sure you have installed git-lfs and run

git lfs install

From here, everything else should work as expected with standard git commands. You add and commit your changes and images, while git-lfs handles everything automatically. Currently, png and jpg are recognized by git-lfs. To track other types of images, edit .gitattributes file.

Image files that are local to a page should be placed in the directory with the page content. Image files that are likely to be reused by multiple pages can be placed in an appropriate directory under /src/images.

Note: Please do not upload images using the GitHub web interface -- there's a feature request open with GitHub, but currently this does not support LFS.

Git lfs clone Troubles?

If you encounter an authentication error where permission is denied upon executing git lfs clone, you may need to generate a SSH key and add that SSH key to your git hub account. Follow the instructions provided at the links below.

Generation of SSH key

Adding new SSH key to your GitHub account

LFS Troubles?

If you cloned the repository prior to installing git-lfs and you're observing that site images have no content, you may be able to fetch all images by running git lfs pull.

If you've been having issues with LFS they may be due to an outdated version of LFS. To determine your version enter

git lfs version

This should show at least

git-lfs/1.5.6 ...

If your version is older than that, you may benefit from upgrading.

Advanced Topics

Update Slide Carousel on Landing Page

The slide carousel on the hub landing page is populated from the /src/splash/ directory. This has a standard hub source structure with a directory and index.md file for each "slide" in the rotation.

To add a slide, add a directory to /src/splash/ and add an index.md file to the new directory.

Every index.md starts with page metadata containing title and date tags. The title is displayed in large font at the top of the slide frame. The date is used for ....

After the metadata there is page content, which is sometimes text (in Markdown) and sometimes just an image that links somewhere.

When creating a new slide, please test how it looks in as many browsers and window widths as possible. The content has to fit in the splash-box div on the home page. /src/css/styles.less defines splash-box. The splash-boxuses the Bootstrap @jumbotron and carousel components.

To drop a slide, use git mv to move the slide's directory from /src/splash/ to /src/splash-archive/.

The code that renders slides is in the /layouts/homepage.pug file.