Formatting

Formatting

This section covers the code and content for formatting your pages, organizing your data, and using markdown to convey your options to users clearly.

too long; didn’t read

Markdown
  • Headers
    • H1 headers are not needed on index pages, but may be added to any pages containing the configuration chapter: false
    • H2 headers begin a new section in a page
    • H3 headers highlight action items for the user
    • H4 headers are for subsections within sections
    • H5 headers may be used at your discretion as needed
    • H6 headers are used to title tables and images
  • Use Horizontal Rules to break up sections
  • Use Bold text when a user should click that option in the UI
  • Use inline code when referencing a CLI command or syntax
    • Not when instructing users to type it!
  • Use code blocks when providing commands for user input, as well as when capturing CLI output.
  • Unordered lists are great for providing quick, easily digested summaries (like this)
  • Ordered and task lists should be used for objectives and review of labs
  • Definitions are useful when introducing new vocabulary or concepts.
  • Tables are usefull for comparing and contrasting different technologies
  • Block quotes can be used for quoting other sections or even other source material
  • Everything to know about links can be found here.
ShortCodes
  • Badges should be used to denote firmware or cloud specific information, but can be used creatively to convey any other variations in instruction as needed.
  • Buttons provide a way to guide users to additional resources in another tab. Useful for opening external resources, such as Qwik Labs or CSP Consoles.
  • Expand is a convenient way to add verbose information without clutering a page.
  • Icons are used throughout shortcode, providing simple graphics to help denote specific information.
  • Mermaid allows for diagrams and charts to be drawn dynamically, rather then relying on images.
  • Notice boxes provide information specific to the lab. Such as the Result boxes shown throughout this document.
Visual Aids
  • Images should be:
    • no more than 200kb in size
    • no more than 800 pixels wide
    • always contain alt text
  • Capturing CLI
  • Embedding Images
  • Classes and Image Effects