GitHub tips

Last Updated: November 14, 2024

GitHub is a code hosting platform for version control and collaboration. It’s typically used for code, but can also be used to document our work so that it's publicly available. GitHub can be challenging if you're new to it. This page provides tips for managing research documents in GitHub.

If you’ve learned new ways of using GitHub for research, we invite you to share so others can learn. To share your idea or link, click the Suggest content changes to this page link in the Help and feedback footer at the bottom.

Jump to:

Move files and folders

Preview your work

Markdown cheatsheet

Move files and folders

Looking for a quick and easy way to rename files, create folders, and move things around? The GitHub editor can help make these things more manageable. This video introduces the built-in editor.

Preview your work

To make writing in markdown easier, you can preview your document as you write markdown code.

To preview your document:

Hold down the “shift” + “.” keys (make sure it’s not in edit mode).
Click on the split pane with magnifying glass icon in the upper right corner of the screen.

Screenshot of the toolbar found in the top right corner of the screen. The options shown in this toolbar are open preview to the side, split editor right and a menu with more options. — The toolbar in the top right corner

A screenshot of the markdown editor with markdown code in a panel on the left and a preview of what it would look like published on the right. — Markdown editor with markdown code on the left and preview on the right

Markdown cheatsheet

Once the editor is open, refer to these common markdown syntaxes to format your document. See the full markdown cheatsheet.

Headings

CODE

# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5

A screenshot of how five different heading levels are displayed in markdown. — Example headings

Text Styles

CODE

Bold
**The quick brown fox jumps over the lazy dog.**
__The quick brown fox jumps over the lazy dog.__
<strong>The quick brown fox jumps over the lazy dog.</strong>
Italic
*The quick brown fox jumps over the lazy dog.*
_The quick brown fox jumps over the lazy dog._
<em>The quick brown fox jumps over the lazy dog.</em>
Bold and Italic
**_The quick brown fox jumps over the lazy dog._**
<strong><em>The quick brown fox jumps over the lazy dog.</em></strong>

A screenshot of examples of text styles. There is a sentence displayed as bold, italic and bold and italic formats. — Example text styles

Link

CODE

[text](url)
Example: [Research plan](https://github.com/department-of-veterans-affairs/va.gov-team/blob/master/products/public-websites/home-page/research/redesign-usability/research-plan.md)

A screenshot of a blue text as an example of how a link is rendered in markdown. — Example link

Jump link

CODE

[text](url.md#page-heading)
Example: [Hypotheses and Conclusions](https://github.com/department-of-veterans-affairs/va.gov-team/blob/master/products/public-websites/home-page/research/redesign-usability/research-findings.md#hypotheses-and-conclusions)

A screenshot of examples of a jump link. There is jump to text with a blue link below it. — Example jump link

Image

CODE

![file name](image url)
![all-tasks-no-hc-chart](https://github.com/department-of-veterans-affairs/va.gov-team/blob/master/teams/vsa/teams/public-websites/research/Veteran-tasks/unmoderated/images/all-tasks-no-hc-chart.png)

To get an image URL:

Create a folder named images within your research folder (watch the video above).
Save your image to that folder.
Click on the image file to open it in a window.
Copy the url.

A screenshot of an example of an embedded image. The image show part of a table of data showing tasks in one column, number of participants marked important and number of all participants marked important. — Example image placed in a research finding report

Blockquote

CODE

> The quick brown fox jumps over the lazy dog.
> *"Makes you read a lot of stuff you shouldn't have to read" (p14).*

Screenshot of Blockquote without a background. — Example blockquote (line 1)

Screenshot of Blockquote with a background. — Example blockquote with background (line 2)

Table

CODE

|Header |Header|
|-------|------|
|Item   |      |


Example:
Team Availability | Time Slots (ET--all pm)
------------------|--------------
Oct 24, 2022 | 12-1, 1:30-2:30, 4-5, 5:30-6:30, 7-8 pm
Oct 25, 2022 | 12-1, 1:30-2:30, 4-5, 5:30-6:30, 7-8 pm
Oct 26, 2022 | 12-1, 1:30-2:30, 4-5, 5:30-6:30, 7-8 pm
Oct 27, 2022 | 12-1, 1:30-2:30, 4-5, 5:30-6:30, 7-8 pm

Screenshot of a table with 2 columns and alternating background colors. — Example table

Help and feedback

Suggest content changes to this page.
Submit new Platform Website content.
Get help from the Platform Support Team in Slack.
Submit a feature idea to the Platform.