Assets
Overview of assets and how to use them.
Overview
Assets are images or video files referenced in assignment files or notes. For example, you might add a screenshot of your software to show a learner where to click. Or you might show a video before your learner starts a challenge.
Assets can only be managed from Instruqt CLI, or directly via the API.
Insert assets
Place all your assets in a directory called assets located in the track root directory like in the following example:
↳ Here the assets directory contains a png image file and an mp4 video file.
Refer to assets
Refer to assets by using the relative paths. For example, refer to ../assets/img.png if you want to use the img.png file within the assignment.md file. The ../ part of the path tells to go up one directory and from there the assets/ part tells to go to the assets subdirectory.
You can also create nested folders inside the assets directory to keep them organized.
Windows file paths
When working from a Windows machine, use the backslash as the directory separator in your relative path— for example, ..\assets\img.png. Otherwise, you will get an error stating that your asset does not exist when pushing your track to the Instruqt platform.
Local and remote assets
Push
Your assets are also pushed when you push a track to the Instruqt platform. And the relative paths to images and videos are converted to fully qualified URLs. So they can be viewed in the sandbox by your learners.
For example, if your local track has this code in an assignment.md file:
The instruqt track push command automatically converts this to:
Pull
When you pull a track to your machine, the fully qualified URLs are converted into relative paths to images and videos so you can preview your files locally.
Work with assets from your code editor
You can install a Markdown plugin in your code editor to make it easy to insert videos and images. The Markdown All in One plugin works well with VS Code. Point the completion.root setting to your assets directory and VS Code will show a handy autocomplete menu when you start to insert image code in your markdown.
Examples
Embed an image into the assignment text
This example embeds an image in the assignment.md sidebar text. This is useful for showing a screenshot or other image to your learner as part of the challenge instructions:
Embed a video in a challenge note
This example embeds a video in a challenge note. Notice the relative path format on line 12 of the assignment.md file:
Embed an image in the track description
This example embeds an image in the track description. Notice how there is only a single dot before the slash ./ which means the assets directory is in the current directory:
Assets API
Then assets API is HTTP based and in order to consume it you must have a valid authentication token (will be referred as token). The API supports uploading, fetching and getting information about your asset.
Uploading asset
Request
HTTP Method: POST
https://play.instruqt.com/assets/tracks/<track_id>
↳ Replace <track_id>
Request headers
Authorization
Bearer <token>
Response
Asset MD5 hash value encoded to string will be returned in response body.
Fetching asset
Request
HTTP Method: GET
https://play.instruqt.com/assets/tracks/<track_id>/<asset_hash>
Request headers
Authorization
Bearer token
Response
Asset will be returned in response body as a binary stream.
Response headers
Content-Length
Size of a requested asset in bytes
Content-Type
Content-type of an asset, f.e. image/png
Asset info
Request
HTTP Method: HEAD
https://play.instruqt.com/assets/tracks/<track_id>/<asset_hash>
Response
Empty
Response headers
Content-Length
Size of a requested asset in bytes
HTTP status codes
200
Request was successful
404
Requested asset not found
500
Internal Instruqt error or error in the underlying storage.
Use assets in assignments
You can refer to an uploaded asset inside a markdown using the same URL which is used to fetch an uploaded asset
https://play.instruqt.com/assets/tracks/<track_id>/<asset_hash>
Embed an image into the assignment text
This example embeds an image in the assignment.md sidebar text. This is useful for showing a screenshot or other image to your learner as part of the challenge instructions:
Last updated