How To Github: Contribute to the Arctos Handbook

Documentation: Github

Why Use Github for the Arctos Handbook?

We’ve covered that before. Here, we’ve assumed you have a Github account, have already edited and written documentation in markdown, understand how the Handbook is configured (at least how to contribute without breaking the website!) and now want a little more control and tools at your disposal. We’re also assuming you are not a programmer, so nothing complicated, but rather tools so you can edit quickly! Ready for the next level?

There are four kinds of content on the Arctos Handbook:

Arctos Handbook content can be created or edited by anyone who is a member of the ArctosDB “Users” team on Github (see “How to Github: Getting Started with GitHub for Arctos”). That team has “write” access to the ArctosDB/documentation-wiki repository in GitHub. Anyone can view the content, but you need to be added to the “Users” team by an Arctos administrator in order to make changes. Arctos users who want the ability to create or edit the Handbook or create or Edit Documentation and “How-to Guides” should email arctos-working-group-officers@googlegroups.com with your Arctos login name and Github login to request to be added to the Github Users group.

We encourage Curators/Collection Managers to engage students in writing “How-to Guides.” However, students will not be able to post them to the wiki site; instead, they will need to submit the content to a member of the ArctosDB “Users” team (e.g., their supervisor) who can then post the content.

Pro Tips

Documentation pages are written in Markdown, which is dead simple to learn. Here’s a cheatsheet.

How To Edit Existing Content

File Names

DO NOT EDIT an existing file name because that will change the URL and thus affect linked pages.

How To Create New Content

Majority of users will be adding to the How-to pages since Documentation is usually reserved for the Arctos Programmers to define the data tables. Below will cover editing and creating content online within your browser (we’re using Chrome).

To edit offline and more advanced editing, consult How to Get the Most Out of Arctos-Github Editing

---
title: How To Do Anything in Arctos
layout: default_toc
---

The Arctos Handbook supports a few other Front Matter attributes. We also support author and date as an attribute, that, when present, show on the rendered page. An example that (as of this writing) is live on the Handbook site is:

---
title: Agents
layout: default_toc
author: ArctosDB
date: 2016-12-01
---

As an important note, if you do not include front matter on your page, the page will fail to compile, and will return a 404 Page Not Found error. The title you provide is what shows up on the index pages.

Relevant Markdown links:

Tips & Cheats:

When creating relative links, Github Markdown will recognize the following:

Link to [this here page](/how_to/page.html)

and form a URL relative to the site’s base url. Ours is ‘https://handbook.arctosdb.org’

How To Add a Table

In the page where you want to insert a table, follow the guide for Organizing Data into Tables in Github

How To Add Images

Embedding images in a markdown document can be a little tricky as it’s not always intuitive in my view. The markdown is straightforward however. It’s the same format as hyperlinking text (use square brackets for visible text, use parenthesis for url) with an additional “!” at the beginning:

![alternative text](image url)

So how to add images to your markdown page? Two methods work:
1) Editing on Github document. If you’re using the online Github editor, then simply drag the image from your desktop to the online editor and it will simulateously upload the image and render the markdown.

2) Working in a Text Editor & Github Desktop. You can add the image to the local folder of your repo directly. For images place theme here: /images/uploads/your_image.jpg

In your markdown document where the image will be added, use the standard markdown format for embedding images but here we can use the base URL (https://handbook.arctosdb.org) to define the image path.

 ![new image](https://handbook.arctosdb.org/images/uploads/your_image.jpg)

How to resize images

Without editing the image itself, you can resize the image as you would any image in regular html– adding the parameters for width and height.

Example in Markdown:

![Arctos logo](https://handbook.arctosdb.org/images/favicon256.png)

Arctos logo

This may be too large for your page so we can reduce the width by 50% using the actual HTML that the markdown is rendering so you can adjust the parameters exactly the way you want.

Example in HTML:

<img alt="Arctos logo" width="128" src="https://handbook.arctosdb.org/images/favicon256.png"/>

Arctos logo

How To Add Videos

Arctos-specific Markdown Code You Can Copy!

Copy the code below the image and paste into any other document to use the image.

Pro Tip
![](https://raw.Githubusercontent.com/ArctosDB/documentation-wiki/gh-pages/tutorial_images/Bear%20Pro.jpg) **Pro Tip**

Caution
![](https://raw.Githubusercontent.com/ArctosDB/documentation-wiki/gh-pages/tutorial_images/Bear%20Caution.jpg) **Caution**


Video Tutorial
![](https://raw.Githubusercontent.com/ArctosDB/documentation-wiki/gh-pages/tutorial_images/Bear%20play.png) **Video Tutorial**

![](https://raw.Githubusercontent.com/ArctosDB/documentation-wiki/gh-pages/tutorial_images/Bear%20Work%20in%20Progress.JPG)

FAQ goes here? <img src="https://raw.Githubusercontent.com/ArctosDB/documentation-wiki/gh-pages/tutorial_images/Bear%20FAQ.jpg" width="50"> **Add FAQ text here?**

How To Edit the Arctos Handbook Locally

Pro Tip

Text editors

Editing and creating pages for the Arctos Handbook in the online Github interface is easy and straightforward. However, at some point, you may need to do more, such as move and edit more than one file at a time. Or perhaps a new page needs more time to complete. This is a step-by-step introduction to working with the Arctos Handbook Github repository.

First, let’s download and install a desktop tool that allows a local folder to communicate with Github– Github Desktop (PC or Mac)

Second, let’s make sure you have a text editor that works well for the task. Most text editors for editing code would work. This can be an intensely personal decision so we’re not going to do any comparisons here but if you do not have a preference, I suggest trying out Brackets. It’s a free, open-source code editor (Adobe) that works well for this task on either Mac or PC.

If you want to work on markdown content offline or just not in a browser, there are a number of great text editors to use. Here are some FREE favorites:

Try using Github Desktop if you want to sync your work with the documentation-wiki repository locally.

Now you’re ready to get started.

Clone a Github Repo for offline editing

Open and edit in a Text Editor

For first time user of Brackets, let’s make life a little easier with a plugin. Plugins are typically third-party contributions to extend Brackets’ functionality.
We will install one to preview your Markdown code as you type- fun and useful!

Now you’re ready to start editing or creating a new markdown page in your cloned repo. These changes are on your LOCAL directory only until you are ready to have it “committed” to the online master repository.

markdown preview

Try it out! As you type and add formatting, the preview will show how the rendered page will look. Caveats: it will NOT show you the final rendering on the Handbook site as Bracket cannot render the entire website’s framework such as the author and date that are added at the bottom of each page based on the front matter fields.

Also note that Brackets (like the other suggested text editors) helps you code with visual cues, auto-finishing braces, and you can add other bells and whistles with other plugins.

Save edits and sync with Github repo

Once you are ready to post your changes to the Github repo and thus have it compiled and rendered for the website, you are ready to use Github Desktop.

Open Github Desktop and you will see your changes in the cloned repo under the Changes tab brackets Green highlights are additions and red are deletions.

If you are ready to push your changes to the repo, then type a short summary of your modifications in the ‘Summary’ box with optional descriptive text in ‘Description’, and click on Commit to gh-page.

TIP: If you only want some but not all your changes committed, you can select which ones by checking off/on the changes on the left.

Search Terms

create documentation
edit documentation
create How To
edit How To

Video Tutorials

Make a quick edit to a How To

Edit this Documentation

If you see something that needs to be edited in this document, you can create an issue using the link under the search widget at the top left side of this page, or you can edit directly here.