Learning resources
Design type: Quick starts | Product area: Hybrid Cloud Console
Author: Mary Shakshober
Last edit: May 31, 2023
Creating and maintaining Learning Resources pages using the GitHub UI
If you’d rather use the CLI, refer to this documentation here
Video demo of going through initial setup and adding new cards:
Designing a learning resources page in Sketch
Step 1: Add the Console Dot design kit to your Sketch library
Step 2: Open the Sketch UI, then add the Learning Resources template page.
[ + ]
>Templates
>ConsoleDot-DesignTemplate
>Learning Resources page
Step 3: All Learning Resource pages should have all 4 content type areas displayed.
- Documentation
- Quick starts
- Learning paths
- Other content types
Step 4: Start adding cards based on what content type they are. If a given section does not have any cards that live inside it, the section should default to being collapsed. If there are cards in a given section, it should default to being expanded.
Your first contribution
Do this once to set up your local fork.
Step 1: Log into your GitHub account.
Step 2: Browse to the Insights Quickstarts repo. Doesn’t matter if you’re OpenShift, Anisble, or any other product -- this is where you will add ANY learning resources (even if it’s not a Quickstart).
Step 3: Click ‘Fork’ > ‘Create a new fork’
Step 4: Make sure you have your personal GitHub account selected in the dropdown (if I didn’t already have an existing fork, I would select ‘maryshak1996’
Step 5: Click ‘Create fork’.
You don’t need to do this ever again -- one and done baby!
For new cards you want to add
Create a folder for your learning source
Step 1: Find your fork of the Insights Quickstarts repo by browsing to the ‘Forks’ page in the repo. Find your account and click on the word ‘quickstarts’ next to your name.
Step 2: Now that you’re in your fork, Click ‘Docs’ > ‘Quickstarts’.
Step 3: Click ‘Add file’ > ‘Create new file’
Step 4: Make a folder by typing <bundlename-resource-name
>/ (should automatically create a new folder). Don’t click ‘Enter’.
Note: Replace <bundle-resource-name> with the filename for your quickstart, using the name of the bundle and a description of the content (like insights-configuring-access, or edge-manage-systems). Refer to the existing filenames for ideas.
Create the main yml file in that folder
Step 1: You should see that a directory was added to the breadcrumb string, and now you have another naming slot. (Fig. 4)
Step 2: Name the file the same name as your folder, ie. ‘<bundlename-resource-name>.yml
’
Step 3: Paste this code into the code editor.
apiVersion: console.openshift.io/v1 kind: QuickStarts metadata: name: bundlename-resource-name externalDocumentation: true spec: version: 0.1 type: text: Content type color: color displayName: Title of Learning Resource icon: description: Description of learning resource goes here and will get truncated automatically through css. link: href: URL to open in new tab text: Short action for a screen reader to announce
Step 4: Edit the fields accordingly
For ‘type:’ choose one of the following text/color pairs below” …
text: Quick start color: green
text: Documentation color: orange
text: Learning path color: cyan
text: Other resources color: purple
See this guide to editing learning resources YML
You can also use the YML preview tool created by the console ENG team
Step 5: Click ‘Commit changes …’
Step 6: Add more detail if needed
Step 7: Select ‘Create a new branch … start a pull request’.
Step 8: Click ‘Commit changes’.
Create the metadata.yml file
Step 1: Navigate to the folder you made (which now has the above yml file): bundlename-resource-name
Step 2: Once in there, click ‘Add file’ > ’Create new file’
Step 3: Since you already have the folder created, just type ‘metadata.yml
’ into the name field
Step 4: Paste this code into the code editor:
kind: QuickStarts # kind must always be “QuickStarts” name: bundlename-resource-name tags: # If you want to use more granular filtering add tags to the quickstart - kind: bundle
Step 5: Edit these fields:
name: bundlename-resource-name value: [select from the second column in the table below]
Bundle | Value tag |
---|---|
Application & Data Services | application-services |
OpenShift | OpenShift |
Ansible Automation Platform | ansible |
Red Hat Insights | insights |
Edge Management | edge |
Home | landing |
All Services | allservices |
Identity & Access Management | iam |
Internal | internal |
Settings | settings |
Step 6: Click ‘Commit changes …’
Step 7: Add more detail if neeed
Step 8: Select ‘Create a new branch … start a pull request’.
Step 9: Click ‘Commit changes’.
Step 10: Navigate to the folder you made (which now has the above yml file): bundlename-resource-name
Step 11: It may take a minute or two to update, but you should shortly see two items in the folder
Bundlename-resource-name.yml
metadata.yml
Create the pull request
Step 1: Once they are both in there, click ‘Contribute’ > ‘Open pull request’
Step 2: Click ‘View pull request’
Step 3: Add a short description of what you need to happen (ie. Add [name of learning resource] to these bundles]
Step 4: From here, ENG will approve the PR and merge it!
For editing existing cards
Step 1: Find your fork of the Insights Quickstarts repo by browsing to the ‘Forks’ page in the repo. Find your account and click on the word ‘quickstarts’ next to your name.
Step 2: Now that you’re in your fork, Click ‘Docs’ > ‘Quickstarts’
Step 3: Find the folder for the learning resource card you are looking for in the list view. Click on the title.
Step 4: Click into the content yml file.
Step 5: Click the ‘Edit’ pencil in the top right toolbar.
Step 6: Make your changes in the YML code, then click ‘Commit changes…’
Step 7: Create a PR requesting that the changes made to your fork be merged into main. Follow the instructions for ‘Create the pull request’ to do this part of the process.