diff --git a/sample-livelabs-templates/create-labs/labs/4-labs-markdown-develop-content/4-labs-markdown-develop-content.md b/sample-livelabs-templates/create-labs/labs/4-labs-markdown-develop-content/4-labs-markdown-develop-content.md index 0f5f82d9..614832c1 100644 --- a/sample-livelabs-templates/create-labs/labs/4-labs-markdown-develop-content/4-labs-markdown-develop-content.md +++ b/sample-livelabs-templates/create-labs/labs/4-labs-markdown-develop-content/4-labs-markdown-develop-content.md @@ -88,7 +88,7 @@ Leverage LiveLabs [Markdown Cheat Sheet](https://c4u04.objectstorage.us-ashburn- 1. Mandatory requirements (Check links, code snippets, help email address, grammar issues) 2. Make sure that all filenames are lowercase, markdown filenames and directories generally match 3. Pay attention on lab section (each lab has a title(#), Introduction (##), Objectives(###), Prerequisites(###), Acknowledgements (##)) -4. Third-party URL shorteners like bit.ly and tiny are no longer permitted in public-facing content, as they can obscure the destination link, making it easier for malicious sites to go undetected. Instead, using clickable URLs formatted in markdown is a better option. This approach not only enhances the visual appeal of your content but also conceals long, non-memorable URLs in a safer and more transparent way. +4. Third-party URL shorteners like bit.ly and tiny.url are no longer permitted in LiveLabs content, as they can obscure the destination link, making it easier for malicious sites to go undetected. Instead, using clickable URLs formatted in markdown is a better option. This approach not only enhances the visual appeal of your content but also conceals long, non-memorable URLs in a safer and more transparent way. Check the example in **Task 5**. ## Task 4: Security @@ -101,7 +101,30 @@ Leverage LiveLabs [Markdown Cheat Sheet](https://c4u04.objectstorage.us-ashburn- 3. Do not use any IP addresses, intranet URLs (for example links to a Confluence page), email addresses, OCIDs, usernames, or passwords in the text. Do not provide a demo password. -## Task 5: Link to absolute path images +## Task 5: Formatting of URLs + +Markdown simplifies the process of adding hyperlinks (clickable links) to your text. You can create a hyperlink using the following syntax: + +``` + +[Link Text](https://www.example.com) + +``` + +a. **Link Text**: + +* This is the text that users will see and click on. +* It should describe the content or destination of the link clearly. +* For example, instead of writing something vague like "Click Here," use something more informative like "[View our latest post](https://www.example.com)". + +b. **URL**: + +* This is the actual web address you want the link to point to. +* You must include the full URL, starting with https:// or http://. +* If the link is broken, the markdown won’t produce an error, but users will be taken to a non-functioning page. + +## Task 6: Link to absolute path images + Rather than pointing to images within your lab folder or workshop directory with a relative path, you can just as easily point your images to URLs. This comes in handy if you use [common images](https://github.com/oracle-livelabs/common/tree/main/images), or reuse an image a lot, the code you write to display it in markdown will always be the same no matter where the image is in relation to markdown. Using absolute image paths is also handy if you need to keep an image updated, as changing the destination file image will affect every instance where you pointed an image to it. This is also useful when you want to *point to an image in a different repository* (you don't need to clone or fork that repository). This is the same concept and implementation as using absolute paths for common labs in your manifest.json files. *For screenshots of OCI menu navigation, use the images with absolute links* @@ -125,7 +148,7 @@ Rather than pointing to images within your lab folder or workshop directory with ![Recommended to use GitHub path for images.](./images/home-page.png " ") -## Task 6: Use conditional formatting +## Task 7: Use conditional formatting If your workshop supports multiple instance types, but the bulk of the content stays the same, then conditional formatting can save you a lot of work. Most commonly, if you have differences between the "Free Tier" and "LiveLabs" (Green button) versions such as provisioning a database instance in Free Tier and just checking that it's created properly for LiveLabs, then conditional formatting will allow your workshop to use a singular markdown for both. This will save you immense effort and prevent accidental oversights if you need to update your workshop in the future since you won't have to maintain a duplicate markdown. @@ -165,7 +188,7 @@ If your workshop supports multiple instance types, but the bulk of the content s ![tabs-conditional-formatting](./images/tabs-conditional-formatting.png " ") -## Task 7: Link within a workshop (Hotlinks) +## Task 8: Link within a workshop (Hotlinks) Sometimes you may want to link to something within your lab or workshop. Most commonly, this is used in pages to link from the introduction or objectives to a specific section in the lab. This section in particular is hot-linked from the introduction to driving home that point. We'll take a look at the "Need Help?" lab to demonstrate how to incorporate this in your workshop. @@ -178,7 +201,7 @@ Sometimes you may want to link to something within your lab or workshop. Most c ![Inspect element of a hotlink.](./images/hotlink-element.png " ") -## Task 8: Scale an image +## Task 9: Scale an image Without using image scaling, all the screenshots you take for your workshop will be of different sizes (unless you're a master of making pixel-perfect crops). To remedy this, we HIGHLY recommend you to stick with a scaling and use it throughout your workshop. This will make all the images scale to the same width (if possible) and contribute to a more consistent and polished feel. You can override the default image scaling by applying these manual controls below. **We highly recommend you use #4's format by default.** @@ -216,7 +239,7 @@ Without using image scaling, all the screenshots you take for your workshop will 5. As a final note, it's in your best interest to take as large of a picture as you can and then scale it down using the parameters above. LiveLabs allows the magnification of images so if you have a larger base image, the audience will have more clarity. -## Task 9: Add and embed a Video +## Task 10: Add and embed a Video Adding videos is very similar to adding images. We most commonly see videos added in the introductions for labs to familiarize the audience with the product before they dive into the workshop. LiveLabs supports embedding of videos from [YouTube](https://www.youtube.com) or [Oracle Video Hub](https://videohub.oracle.com). @@ -236,7 +259,7 @@ LiveLabs supports embedding of videos from [YouTube](https://www.youtube.com) or ![The Video Hub URL](images/video-hub-url.png =60%x* " ") ### Embedding a video from YouTube -1 + 1. Take a look at this example of a video linked in the introduction of a workshop. ![Example of a video link.](./images/youtube-vsc.png =60%x* " ") @@ -247,7 +270,7 @@ LiveLabs supports embedding of videos from [YouTube](https://www.youtube.com) or ![How to link a youtube video.](./images/youtube-url.png =60%x* " ") -## Task 10: Scale a video +## Task 11: Scale a video Without using video scaling, all the video you embed will have small as the default size for your workshop. You can override the default video scaling by applying these manual controls below. @@ -319,7 +342,7 @@ Without using video scaling, all the video you embed will have small as the defa [Video hosted on YouTube](youtube:lHriX403Oz4:large) -## Task 11: Tables +## Task 12: Tables You can define a table in Markdown just like so: @@ -372,7 +395,7 @@ Isn't that cool? You can also refer to the [LiveLabs Markdown Cheatsheet](https://c4u04.objectstorage.us-ashburn-1.oci.customer-oci.com/p/EcTjWk2IuZPZeNnD_fYMcgUhdNDIDA6rt9gaFj_WZMiL7VvxPBNMY60837hu5hga/n/c4u04/b/livelabsfiles/o/labfiles/LiveLabs_MD_Cheat_Sheet.pdf) -## Task 12: Variables +## Task 13: Variables You can specify variables in another file and refer to them in your Markdown. @@ -431,7 +454,7 @@ or - Here you can find more info: **[](var:doc_link)** -## Task 13: Use the LintChecker +## Task 14: Use the LintChecker The LintChecker is a great javascript function for QAing that you should take advantage of. It is especially handy in catching some of the more easily overlooked errors such as indentation and syntax errors. @@ -441,7 +464,7 @@ The LintChecker is a great javascript function for QAing that you should take ad A box will pop up with any errors that the LintChecker caught. Keep in mind that these are not an exhaustive list of errors, they are only the ones that the function has been programmed to catch. Also keep in mind that even though it lists something as an "error", if it was done intentionally by you, you can by all means just ignore it. -## Task 14: Case Sensitivity +## Task 15: Case Sensitivity **THIS IS IMPORTANT.** The majority of us use Windows and macOS which are **Case Insensitive** systems. This means that Windows and macOS consider "OrAcLe.PnG" to be the same as "oracle.png" or "Oracle.PNG" for file structure. GitHub and GitHub pages are **Case Sensitive**, and **do** make that distinction. @@ -457,7 +480,7 @@ The LintChecker is a great javascript function for QAing that you should take ad 2. If you do run into a Case Sensitivity error on Windows or macOS, you cannot simply fix it by renaming it DIRECTLY with the correct case... because the system will not recognize that you are trying to rename it. You have to either rename that item to something else entirely and then rename it back with the correct case... or you can use **"git mv"** as described [in this article](https://stackoverflow.com/questions/11183788/in-a-git-repository-how-to-properly-rename-a-directory) for more complicated fixes that involve entire directories. -## Task 15: Code Snippets +## Task 16: Code Snippets 1. If you include code snippets in your workshop instruction, you can use the following syntax for code to distinguish it from other instructions. @@ -520,7 +543,7 @@ The LintChecker is a great javascript function for QAing that you should take ad **Reminder** Download this handy [Cheatsheet](https://c4u04.objectstorage.us-ashburn-1.oci.customer-oci.com/p/EcTjWk2IuZPZeNnD_fYMcgUhdNDIDA6rt9gaFj_WZMiL7VvxPBNMY60837hu5hga/n/c4u04/b/livelabsfiles/o/LiveLabs_MD_Cheat_Sheet.pdf), which has more information about using Markdown syntax for LiveLabs development. -## Task 16: Strikethrough +## Task 17: Strikethrough With this new feature, you can now cross out text or words in a paragraph by adding two tilde before and after the word or text in a paragraph. @@ -530,7 +553,7 @@ With this new feature, you can now cross out text or words in a paragraph by add *`~~An example of Strikethrough.~~`* transforms to *~~An example of Strikethrough.~~* -## Task 17: Clickable Links +## Task 18: Clickable Links 1. Old pattern of making URL clickable required markdown formatting. For example, you need to have this format in markdown to make the links clickable. @@ -546,7 +569,7 @@ With this new feature, you can now cross out text or words in a paragraph by add 4. The URLs are opened in a new tab in the browser and the same applies to email addresses as well. -## Task 18: Building Blocks +## Task 19: Building Blocks Building Blocks are a way to enhance both the workshop development and customer experience. This step focuses on how authors can use Building Blocks and Tasks to accelerate their workshop development in your repo. @@ -556,7 +579,7 @@ Building Blocks are a way to enhance both the workshop development and customer 3. If you would like to leverage pre-built building blocks for your repository, feel free to check out this [how to create building block guide](https://github.com/oracle-livelabs/common/blob/main/building-blocks/how-to-author-with-blocks/how-to-author-with-blocks.md) to begin building for your repo. -## Task 19: Use LiveServer extension +## Task 20: Use LiveServer extension If you have installed the LiveServer extension in your VSCode by following the steps in Lab 2 Task4, you can conveniently utilize Live Server to open your workshop's HTML file and enjoy the seamless experience of dynamically viewing and testing your changes. @@ -587,4 +610,4 @@ You may now **proceed to the next lab**. * Brianna Ambler, Product Manager * **Last Updated By/Date:** - * Ana Coman, Technical Program Manager, Oracle Database Product Management, September 2024 \ No newline at end of file + * Ramona Magadan, Technical Program Manager, Oracle Database Product Management, September 2024 \ No newline at end of file diff --git a/sample-livelabs-templates/create-labs/labs/5-labs-qa-checks/5-labs-qa-checks.md b/sample-livelabs-templates/create-labs/labs/5-labs-qa-checks/5-labs-qa-checks.md index 35e1840d..e4f88e00 100644 --- a/sample-livelabs-templates/create-labs/labs/5-labs-qa-checks/5-labs-qa-checks.md +++ b/sample-livelabs-templates/create-labs/labs/5-labs-qa-checks/5-labs-qa-checks.md @@ -62,7 +62,7 @@ You have finished developing your workshop. To publish your workshop, you still ![Tags](images/tags.png " ") -4. If you have changed your Status to **Self QA** or your workshop status is in **Quarterly QA**, click on the **Self QA Checklist** tab and check your workshop against the form. Update your workshop and create a new pull request if necessary for the workshop to follow LiveLabs standards. +4. If you have changed your Status to **Self QA** or your workshop status is in **Quarterly QA**, click on the **Self QA Checklist** tab and check your workshop against the form. Update your workshop and create a new pull request if necessary for the workshop to follow LiveLabs standards. After creating the Pull Request, come back in this tab and insert the link to your PR in *Insert Github Pull Request Link* field and also the link to the workshop from your personal Github in *Your [github_username].github.io workshop link* field. ![Self QA Checklist](./images/self-qa-checklist-1.png " ") ![Self QA Checklist](./images/self-qa-checklist-2.png " ") diff --git a/sample-livelabs-templates/create-labs/labs/5-labs-qa-checks/images/self-qa-checklist-1.png b/sample-livelabs-templates/create-labs/labs/5-labs-qa-checks/images/self-qa-checklist-1.png index 5052089c..35ef451b 100644 Binary files a/sample-livelabs-templates/create-labs/labs/5-labs-qa-checks/images/self-qa-checklist-1.png and b/sample-livelabs-templates/create-labs/labs/5-labs-qa-checks/images/self-qa-checklist-1.png differ diff --git a/sample-livelabs-templates/create-labs/labs/5-labs-qa-checks/images/self-qa-checklist-2.png b/sample-livelabs-templates/create-labs/labs/5-labs-qa-checks/images/self-qa-checklist-2.png index 1ec2ca21..caefba62 100644 Binary files a/sample-livelabs-templates/create-labs/labs/5-labs-qa-checks/images/self-qa-checklist-2.png and b/sample-livelabs-templates/create-labs/labs/5-labs-qa-checks/images/self-qa-checklist-2.png differ