GitHub Repository

Skillable Studio allows you to set GitHub as an instruction source, using an external GitHub repository. Choosing to leverage this feature means moving all of your content management (including editing) for a lab into GitHub. Once you have enabled this instruction source for a lab, the content in that lab will automatically be updated based on the content in the external repository.

External Management Benefits

1. Offline editing - With external instruction management, content is created/edited as part of a structured Markdown file, that can be edited offline using one of the many free or commercial Markdown editors that are available for all mainstream platforms/devices being used today, including Windows, macOS, Linux, iOS, and Android.

2. Revision control - GitHub natively supports revision control, which means you get revision control for your content in labs that leverage the integration feature. This allows you to compare revisions, roll back changes, view revision history, etc.

3. Multi-author support - By managing your content in a lab that leverages external instruction source, you can support multiple content authors contributing to the content for one lab at the same time.

External Management Disadvantages

1. Skillable Studio Custom Syntax Unavailable in External Repository - when using an external repository as an instruction source, custom Skillable Studio markdown syntax  will not render in the external system. These markdown elements can still be used and rendered in a lab.
   These include:

   • Knowledge block/link

   • Alert block/link

   • Help block/link

   • Hint block/link

   • Note block

   • Copyable text

   • Type text

   • code block modifiers

   • @lab replacement tokens Intellisense

Best Practices

When using an external instruction source, there are a few things to consider.

• The overall size of the repository cannot exceed 500MB.

• Keep your repository as small as possible. Large repositories can possibly present problems. For example, if your repository is approaching the size limit and then multiple commits are made very quickly, some of the commits may not be displayed in the lab instructions.

• We highly recommend using repositories dedicated to your lab content and not mixing other content within these repositories.

• You are able to host content for multiple lab profiles within the same repository, but keep in mind you could eventually need to break this up into multiple repositories if the lab content exceeds the maximum file size per repository. A good rule of thumb would be one repository per course or lab series.

Getting started

For external instruction sources, you will need to have an account in GitHub and will be prompted to login. If
you do not have one yet, you can create an account.

Your repository will need a markdown (.md) file that defines the lab content in Markdown. This file will contain the lab instructions for your lab.

When you configure a lab profile to use an external instruction source, you will be directed to a login page, where you will be asked to allow Skillable Studio permission to access your repositories. Skillable Studio will need access to your email address for push notifications, repository access, and admin permissions to modify web hooks.

GitHub Configuration

If you do not have a GitHub account set up yet, you can create an account here.

1. Create a new GitHub repository where you will manage your lab content.

2. Create a folder to store your lab instructions and any other files used in the lab.

3. Create a new file in the folder called content.md.

4. If you want to store screenshots for your lab in GitHub, create a media folder, inside of the folder created on step 2.

5. If you want to store videos for your lab in GitHub, these can be stored in the media folder as well.

If you are moving content for a lab that has content in GitHub, see the Copying Existing Lab Content section below to start that way instead.

Copying Existing Lab Content

If you have a lab that already has IDLx content in Skillable Studio, you can use GitHub to manage that content as well. To get this set up you must do the following:

1. In Skillable Studio, navigate to the lab profile that you want to
   manage in GitHub.

2. Select Export.

3. In the Export window, select Lab Metadata: Instructions Only and select
   OK.

4. In the Save dialog, navigate to the location where you want to save the archive file.

The archive file that is saved will contain a content.md file as well as folders for screenshots and videos if either of these were present in the original lab profile. Add these files to the GitHub repository that you want to use to manage your lab content, and then proceed to the configure the lab profile to use an external instruction source for GitHub.

Skillable Studio Configuration

To use the markdown document in your GitHub repository as the instruction source with a lab profile, navigate to the lab profile you want to configure, then follow these steps:

1. From your lab profile page, select Edit.

2. Select on the Advanced tab, then select Instruction Source.

3. Select GitHub Repository.

If you're not logged in already, you be will prompted to log in to the GitHub account that has a repository containing lab content you want to use as an instruction source in the lab profile.

1. Once you are logged into GitHub, you will be asked to authorize Skillable Studio to have access to your GitHub account. This access is only used to create a webhook so that Skillable Studio can be notified whenever the
   content in your GitHub repository changes. Select Authorize application to
   continue with the integration.

2. At this point you will be presented with a list of repositories that are associated with your GitHub account. Select select next the repository containing the markdown file to be used as the instructions source.

   When you complete the following step, any existing content in your lab profile will be overwritten, and anything lost will be unrecoverable. If you have content in the lab profile, you can export the lab instructions by selecting the export button at the top of the lab profile details page.

3. After choosing your repository, you need to identify the markdown file that defines the lab content within that repository. Select Select next to the markdown file to use as the source of your lab content.

4. Once you select the Markdown file that defines the lab content, Skillable Studio will process all lab content referenced by that markdown file and add it into the lab profile instructions. At any point that the GitHub content changes, the lab profile will be updated automatically.

5. Once the synchronization process is complete, you will have completed your
   integration. Select Close to finish the Integration wizard.

1.Your lab profile now shows that instructions are sourced from your GitHub repository. Select the Save button at the bottom of your lab profile window to exit the lab profile editor.

Activities

Automated and question activities can be used when using an external repository as an instruction source. Activities must be added to the Lab profile and then the Activity Replacement Token added to the lab instructions in the external repository.

To add an Activity to a Lab Profile that uses an external instruction source:

1. Navigate to the Lab profile.

2. Select Edit Instructions in the upper-right corner.

3. Select the Activities menu.

4. Select + New Question or + New Automated Activity.

5. After creating the Activity, copy the Token for the Activity.

6. Navigate to your external repository, and edit the file that is used for the lab instructions.

7. Paste the token in the file, where you want the Activity to be displayed.

The Activity is now part of your lab instructions. Repeat these steps to add additional Activities.