This platform is designed to allow you to create your own Cloud training, either from scratch or by taking existing content and allowing you to customize it to the needs of your Cloud environment.
To do this courses are created in "Lab Markup", a simplified text Markup Language which broadly follows the SGML standard. The principles of SGML were chosen as it allows more inference of the type of data between tags, rather than HTML's strict tag requirements.
The aim is to create easy to read tags which interfere with document flow as little as possible. As an example, the example course for Three Tier Web Setup on this site has 15000 words and 16 images in the course. There are just under 600 tags in the course markup but these are converted into over 3500 HTML tags.
You can edit your course content using an online editor on this platform or by editing it in the text editor of your choice and uploading it.
Once you have edited the content the site then converts it into a rich HTML 5 web page. This is based on the Bootstrap web framework which is designed to adapt to multiple screen sizes, so laptops and desktop screens should be fully supported.
Because every page on the site is built from standardized templates, it is also easy to convert a dedicated site to your organization's corporate look and feel.
All the Markup tags are simple square bracket tags, some are standalone and others have opening and closing tags. Many are similar to HTML tags but generally simplified to improve presentation. Tags are case insensitive.
Unlike HTML the Markup syntax reflects the format of your typing in terms of line breaks and paragraphs. The preview and publish services convert these to HTML <BR> and <P> tags as part of the conversion. This means you can also use multiple line breaks to create gaps in your document or space around images, for example.
This feature is constantly evolving so please use the feedback form to send feature requests, report any issues or ask for help.
Working with Large Language Models
Writing course content in Markup has a number of advantages when working with Large Language Models such as Claude, Gemini, Chat GPT etc. If you prompt the LLM to read this document and one or two example courses in Markup format the LLM should build a good understanding of the Markup syntax.
Then when creating course content the LLM is constrained in the page elements which can be used and so courses will follow a standard format as they are created. The reduction in the number of Markup tags compared to HTML means that it is far easier for humans to review the course content without the distraction of viewing the HTML layout tags.
LLMs are also very useful when creating courses by importing existing content. The site import scripts should have an over 90% success rate in converting text and images as well as correctly identifying code blocks, tables and highlighted text. However, by processing with an LLM you can further remove artifacts such as "This page intentionally left blank" messages which may be missed by the import process. They are also good for reformatting the section headings in a document and parsing text for callout and warning messages. After this you can then review the content for style and accuracy before converting it to a training module.
Markup Features
Headings
[h] tags create headings and sub headings.
Just as in HTML, 6 levels of heading are supported. They also are used to create the dynamic menu which is displayed page left on every lab web page and, if exported to other formats, could be used for a table of contents.
[h1] Title Text [/h1] creates a major heading and [h2] Sub Heading [/h2] a sub heading in a document. They create the section and item headings in the navigation menu respectively.
If you want to use a longer title for a document but would like a shorter version for the menu item this is supported. Simply include the menu text in brackets, for example [h1]Setting Up Your First EC2 Instance (EC2 Setup)[/h1] would give a document title of "Setting Up Your First EC2 Instance" and a menu title of "EC2 Setup" (you can see this at the start of this document).
Headings [h3] ... [/h3] to [h6] ... [/h6] produce headings in the document but are not reflected in the menu or HTML section structure.
Highlighting
It is very common in lab / course documentation to ask the user to carry out multiple actions in sequence. This may be filling in multiple items in a form, or making several menu choices.
The challenge for course authors is that it is important to highlight these in the instructions, but doing this manually is very time consuming.
This is what the Highlight Tag is used for. When placed around a block of text any text in "double quotes" will be highlighted in the appropriate syntax.
You can see lots of examples in the 4 example labs but two examples are below.
[highlight:select]
In the AWS Console go to "IAM", then select "Roles" in the Left Hand Menu and "User Defined Roles" in the drop down menu.
[/highlight:select]
[highlight:code]
In your terminal session type the following commands
"cd /var/opt/httpd"
"sudo service httpd stop"
"sudo service httpd start"
"ps -ef|grep httpd" or "sudo service httpd status"
[/highlight:select]
A highlight tag can span multiple document sections or even be applied to a whole document. Other tags can be opened and closed within the tag pair, there is no strict requirement to close a highlight before opening another tag.
The current highlight types supported are highlight:select, highlight:enter, highlight:code and highlight:example.
Lists
Lists are created with the [list] ... [/list] tags. Like HTML they can be bullets, numbered or alphabetical. Unlike HTML you do not need the <li> .. </li> around list items, a new list item is opened with a hyphen and space at the start of a line.
e.g.
[list]
- This is item 1
- This is item 2
[/list]
Would output
This is item 1
This is item 2
Lists can be embedded within each other, so you can have a alphabetical list within a bullet point list.
You can also start numerical and alphabetical lists at a specific point e.g. [list type:alphabetical start:c]
Callout Blocks
The Lab Page design is based on the Bootstrap Web Framework. This means that there are a number of pre-built components you can add to the page. One of these is callout blocks. These are highlighted text boxes with icons and colored backgrounds.
e.g. this is a Warning Box
S3 Permissions
Except for special use cases, you should not need to have a publicly accessible S3 bucket. Even for Web-hosting for most use cases it is more cost effective and secure to use a Content Delivery Network such as Cloudfront and a private S3 bucket. If in doubt start with no public access and change when needed.
The format is as follows
[callout:warning]
Title (first line only)
Body Text, this can be any length but from a style perspective it probably works best as a short message.
[/callout]
The supported types are [callout:warning], [callout:info] and [callout:tip] . Each type generates its own color and icon.
Code Blocks
Code blocks allow you to literally represent blocks of code, be it HTML, JSON and programming languages. They include a copy helper button which allows the user to copy the content of the code block to their local clipboard.
import sys
import argparse
import shutil
from pathlib import Path
from typing import List, Tuple, Optional
# Import the main processor class from the existing file
import importlib.util
module = importlib.util.module_from_spec(spec)
spec.loader.exec_module(module)
PackageDocumentProcessor = module.PackageDocumentProcessor
If you specify the type e.g. [codeblock:python] the lab page will attempt to use a Javascript library to highlight the code syntax but this may not be implemented in the editor preview.
The format for the above codeblock would be;
[codeblock:python]
import sys
import argparse
import shutil
from pathlib import Path
from typing import List, Tuple, Optional
# Import the main processor class from the existing file
import importlib.util
module = importlib.util.module_from_spec(spec)
spec.loader.exec_module(module)
PackageDocumentProcessor = module.PackageDocumentProcessor
[/codeblock]
HTML Codeblocks
HTML in a code block will still be interpreted literally, so you will need to replace angle bracket HTML tags with < and > HTML tags. We may add a substitution process in future if people request it.
Codeblocks adapt their display depending on the number of lines inside them. If there are under 10 lines the text is displayed as input. From 10 to 25 lines the initial lines are displayed with a "Expand" button to reveal the full text. If there are over 25 lines the expand box changes to generate a pop out window which allows the full viewing of the embedded data. This feature was added based on user feedback and allows the inclusion of long blocks of code or logfiles without interrupting the overall document flow.
Code Copy
Regardless of the length of the embedded code in the code block, the copy button will always copy the enclosed text into the copy/paste buffer. This means users can copy long files without having to inspect them all
Linking to other Documents
Linking to other web pages is supported with the link command, the format is [link:url] ... [/link]
e.g. [link:https://aws.amazon.com/architecture/icons/ page:new]AWS Architecture Icons[/link]
The tag takes only one argument, adding "page:new" after the link will open a new browser tab / page.
You can also use the link tag to move to a specific section of a document. If you look at the generated menu, the h1 headings are section headings and can be referenced within a document using [link:#section-1].
The h2 headings are referenced as items, they inherit their section number. So to reference the fifth sub heading in the second section of a page you would use the format [link:#item-2-5].
This is quite powerful if you want to allow students to skip ahead if they have already completed some setup.
Just as with HTML you can surround either text or an image with the [link] ... [/link] tags.
Images
Images are processed with the [image:(imagename.type)] tag. There is no complex path information associated with an image, it is always just a filename.
Image files are uploaded with the Image Uploader attached to the Markup Editor and associated with a single course.
To reduce the risk of images changing over time or inappropriate content being displayed only local images can be displayed.
The image tag supports the following attributes
border:(0-5) This creates a contrasting border around the image, useful when you have a screenshot which may merge into the page background
You can specify a blank margin around the image from 0 to 50 pixels in size. This is useful if you have an image which looks more effective with spacing around it.
e.g. [image:ec2-menu-dropdown.png border:2 margin-left:50] would give you an image with a 2 pixel border and a 50 px gap to the left of the page.
Copy to Clipboard
If you enter a line of text in double quotes and then add [copy] after the closing quotes, the publisher will create a copy icon after the text to allow the student to copy that quoted text directly to the clipboard.
This will copy "Hello World!"
Tables
Tables are processed in a very similar way to HTML and the tags are broadly the same.
Tables are opened and closed with [table] ... [/table]
Table rows are defined with [tr] ... [/tr]
Table cells are defined with [th] ... [/th] for header cells and [td] ... [/td]
As with HTML cells can span multiple columns or rows by adding colspan and rowspan within a [th] or [td] tag. A tag of the format [td colspan=3] would span three columns and [td rowspan=2] would span 2 rows
Style elements can also be added to a table by using the adding the class element to a table e.g. [table class="table-bordered table-striped table-hover"]. These have the following effect;
table-bordered
Adds a border effect to the table and table cells
table-striped
Alternates table rows between the primary and secondary colours of the theme color scheme
table-hover
Highlights a row when the user hovers their mouse over any row element
Style
Text Styles
The Markup language supports a number of basic tags for describing how text is displayed. Each of these may be embedded within each other so [b][i]text[/i][/b] would produce Bold and Italic text.
Tags available
[b]...[/b]
Renders the font between the tags as bold
[i]...[/i]
Renders the font between the tags as italic
[strong]...[/strong]
Emphasises the text between the tags for attention using the theme definition of strong text.
[pre]...[/pre]
Renders the font between the tags as
preformatted
text
[code]...[/code]
Renders the font between the tags as code text
Hidden Text
This isn't a feature in the markup editor but any text within a [hidden] ... [/hidden] text block is not processed by the markup publisher and never appears in end content. This has a number of potential uses.
You can use a hidden block in a document to add your own notes and meta information about a course.
You can use it to alternate versions, so if one course audience uses Internet Gateways only and another Direct Connect only you can hide and unhide sections to meet their needs without having to manage two course version for the rest of the text.
Note if this use case is useful please let us know because we have a number of ideas around ways to build documents from sections and A / B deployments but would like to get feedback before implementing them.
HTML Markup
Any HTML text found in a document is escaped so the HTML tags in the document are represented as typed in the course. This makes it easy for you to include HTML samples in a course.
HTML can't be included in a course design. This is a policy decision to protect the course from elements which would break the look and feel or the potential to inject harmful content.
The entire site is built from templates which create the page header, menues, content and footer as well as Cascading Style Sheets and Javascript files which manage the look and feel and functionality of the site. This means that if you licence the platform for your own organization you can easily adapt every element to your house style.
We hope everyone using the service can develop the courses they want to using the Markup publishing service. If not please let us know the additions you need and we'll add them to the roadmap.
Testing
A key feature of this service is the ability for students to work their way through a course building services on AWS to enhance their knowledge through using the cloud platform. At various points they can click a testing button and get feedback and suggestions on what they have built so far and help if they are having issues.
This feature is in testing at present, please send a feedback request to see a demo and discuss your requirements.
Roadmap
There are a number of features we plan to add to the Markup syntax over the coming versions, drawing from other SGML Markup and Markdown features as well as the features provided by the Bootstrap web framework the site is built on.
Coming up next are plans for support for abbreviation expansion (tooltips for industry acronyms which will be useful to students), easier linking within documents and a limited selection of Bootstrap graphical elements.
We also want to add improved table support, at present you can insert HTML tables but we would like to move to a more SGML standard table format to improve the ability to export documents to a wider range of formats.
Embedded Video was our first feature request and we'll also look at the best ways to implement this in the framework.
As the primary aim of this service is education we also want to improve the site's accessibility features and seek external certification as being fully accessible to a wide range of users.
We would like to see the Markup language to be used as a standard and so will be publishing a full SGML Document Type Definition describing the syntax. Once the beta is finalised and we move this site to production we will also introduce versioning to the Markup so you can pin your document to a specific version and be sure they should always render in the same way.
A Visual Code Editor plugin is in very early beta stages. The goal here is to allow you to write more of the course content in VS Code or VS Codium and then upload it to your content on the site.
If you have any feature requests please let us know through the feedback form or by emailing support@cloudsandlight.com
