Why Use GitHub for Arctos?

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?

Relevant Markdown links:

Tips & Cheats:

Github-flavored Markdown Cheatsheet ready for printing!

Live Markdown Editor - The online markdown reader will display a preview as you type.

Word to Markdown converter - Upload as Word doc, get back Markdown

Convert a Google Doc to Markdown - a little bit of setup via Google Script and then you’ll have a handy tool

How to Get the Most out of Arctos-Github!

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.

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.

How to handle 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

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.