Visual Studio Code and GitHub setup guide for Knowledge Lab and CreatorCon Workshop speakers.
Knowledge and CreatorCon no longer use printed lab guides for our attendees. Since 2018, we have moved to electronic lab guides powered by Markdown syntax.
The objectives of this guide are to help our speakers properly configure the tools that are required to create and publish guides.
Please pay special attention to the notes and tips provided.
Topics Covered in this Guide:
- GitHub Configuration
- Visual Studio Code Configuration
- SnagIt Configuration
- Org and Guide Template Access
- Cloning Guide Locally
- Save and Upload Changes
Follow these steps to create and share your GitHub account:
- If you don't have a GitHub account already, navigate to https://github.com/join to create an account. The email address you submit should be your ServiceNow email address. The user name can be whatever you wish.
- Fill in your GitHub username (noet email address) in the SRC. An invitation will be sent to your email that you must accept.
The following steps and terminal window commands need to be run on each machine to ensure GitHub is configured correctly to run with VS Studio and to properly access the GitHub repository.
-
Load a terminal session from your computer
-
From the prompt type: Git
- On a Mac, this may or may not initiate an installation process. If it does, follow the prompts to install. If it doesn't, then it should return a set of potential commands accessible to GIT.
-
Set your user name with this command. Replace "Mona Lisa" with your name
- git config --global user.name "Mona Lisa"
- Set your email address with this command.
- git config --global user.email "email@example.com"
Visual Studio Code will be used as the front-end editor for the guide. A template will be provided to you as a framework and will be discussed later in this guide. Follow these steps to install Visual Studio Code
- Load Self Service from your computer
- Select Featured from the categories
- Run the "Grant Temporary Admin Rights" option. This will ensure the application can be installed on your computer.
- Select Applications from the Categories list
- Install the option named Visual Studio Code
If you aren't an employee, you'll need to install VS Code and the PasteImage plugin.
-
Download and run the VS Code installer from https://code.visualstudio.com/
-
Open VS Code and click the Extensions icon
-
Search for
Paste Image
-
Click
SnagIt is a Mac and Windows software package that offers the ability to easily capture and annotate images used in your guidebook. While other tools exist that do many of the same features, SnagIt offers some very nice capabilities to make the process of inserting professional looking images easily. If you are already familiar with another package (e.g. Skitch), ensure it has the following features:
- Annotate the image with boxes, arrows, and text
- Place 1 point borders around the image
- Export images to a specific size
- Place numeric markers (1, 2, 3) on a single image
- Crop the image
- Pixelate secure/private information
SnagIt is a licensed product. ServiceNow employees can use a Surf request to get a license and install.
- To ensure images appear at the appropriate size, in Snagit preferences, set the option to Scale down retina images when sharing.
As a K19 Lab or CC Workshop speaker, you will require access to the GitHub org set up as the repository for our guides. In addition, you will also need permission to download the guide template you are assigned to. Follow these steps to gain access to the org.
- If you haven't already, enter your GitHub username in the SRC. An invitation will be sent to your email that you must accept.
- Open the invitation email from "GitHub" or "jasontmckeesn" to join the ServiceNow Events organization.
- Click the "Join ServiceNowEvents" button
- Repeat these steps for each GitHub invitation you receive. The second invitation should grant you access to your guide repository.
Now that you have access to the org and repository by accepting the invitation, it's time to start working on your guide. But first, you need to download the guide from the repository to your local computer. Follow these steps to download. This step is only required once.
-
Log into your GitHub account.
-
Under the "Your Repositories" tile on the left, click the lab guide repository for your specific lab. This will open a new window with the files associated with this lab. ][[mmm ]]
-
Once loaded, click the green "Clone or Download" button.
-
From the small dialog that opens, copy\paste the URL. (Note: You can also click the clipboard icon in the dialog)
-
Switch back to VS Studio Code
-
Select the "View|Command Palette" menu option
-
From the sub menu that opens, select "Git:Clone"
-
Paste in the URL into the dialog and press enter
-
Type in a local directory path to store the file and press Enter. A sub folder is recommended.
-
Select "Open Repository"
-
It may prompt you for an ID and Password. Plug in your GitHub ID and Password.
Like any document, it's important to save your changes regularly. To do this follow these steps.
- From the File Menu select "Save". That's it!
Saving the file from the menu only saves it locally. You also need to push it up to the GitHub site, but it's not necessary to do this every time. Just remember to upload after a major change to the doc and final changes of course. Follow these steps to properly upload your guide back to GitHub
-
Select the icon in the left that looks like a "Y". This is your source control access.
-
Type in a short description of the recent changes made. For example: "Added new lab 3 to guide". Press the check mark. (Note: You must do this every time you want to upload.)
-
It may prompt you with a dialog to "Stage" your changes. Press "Yes"
-
Select the "..." more option to the right of the check mark.
-
Select "Push". An indicator should load that it is uploading. ]
-
To verify success, switch over to GitHub an load up the guide repository. Ensure that your changes are there.
For additional setup assistance, please look at the wiki for the Troubleshooting FAQ.