Labs Style Guide

O’Reilly Lab Style Guide

For more general style conventions, see the O’Reilly Style Guide and Word List.

Related scenarios in a set: Both the Intro page and the Outro page should have a Set TOC, with a numbered list and hyperlinks to the other scenarios in the set. Use an arrow (←) and italic You are here on the current scenario. For the Outro page, you’ll also add an arrow and italic Next up on the next scenario in the set (unless you’re on the last one).

Descriptions: These blurbs on the title cards in the Katacoda.com author page should be initial cap/lowercase, no end punctuation, as here (taking care not to lowercase cap terms, however). These descriptions should be a single sentence that tells the learner what they will do in the lab. For example, “Create microservices with Azure Functions” or “Creating and assuming an IAM role for developer access.”

Code blocks: These should be preceded by a colon with some introductory text (e.g., “in the following snippet:”), as usual. Exceptions are fine when it makes sense.

Headers: We only have styles for H1 and H2, so avoid any third level

Block Quotes: If you add > at the beginning of a para, it should render as an indented block quote in the platform. Use sparingly for quoted material.

Admonitions: Use bold markup along with the admonition type, followed by a colon, e.g., Note: Note text… Avoid using horizontal rules, as they will not appear on the platform. Admonition options include: Note, Warning, and Tip.

Lists: Variable lists markdown = * Some element: Some text…

Scenario titles: The scenario title lives at the top level of index.json. Keep titles brief and to the point, leading with the main topic/technology/concept being taught and the task to be completed. For example:

Kubernetes: Launch a Single-Node Cluster

The scenario title should:

be brief
include the primary technology addressed (noun)
summarize the task or activity involved (verb + object)

Step titles: Avoid duplicate titles on the step pages. Rather than adding headers in the step.md file, define all the step titles within index.json. Do not include step numbers (ie: Step 1, Step 2, etc) in your step titles, as the step numbers are built into our UI. e.g., “Step 1: Using Functions” should be simply “Using Functions.”