Skip to content
Kong Logo | Kong Docs Logo
search
  • We're Hiring!
  • Docs
    • Kong Gateway
    • Kong Konnect
    • Kong Mesh
    • Plugin Hub
    • decK
    • Kubernetes Ingress Controller
    • Insomnia
    • Kuma

    • Docs contribution guidelines
  • Plugin Hub
  • Support
  • Community
  • Kong Academy
Get a Demo Start Free Trial
  • Kong Gateway
  • Kong Konnect
  • Kong Mesh
  • Plugin Hub
  • decK
  • Kubernetes Ingress Controller
  • Insomnia
  • Kuma

  • Docs contribution guidelines
    • Style guide
    • Word choice and naming
    • Notes and other notices
    • Documenting user interfaces
    • Contribution templates
    • Plugin documentation
    • Markdown rules
    • Reusable content
    • Variables
    • Single-sourced versions
    • Single-sourced plugins
    • Conditional rendering
    • Welcome to the Kong Docs community
    • Community expectations
    • Hackathons

github-edit-pageEdit this page

report-issueReport an issue

enterprise-switcher-iconSwitch to OSS

On this page
  • Best practices
  • Notice types
    • Note
    • Important
    • Warning
    • No icon
Contribution guidelines
  • Home
  • Style guide and contribution guidelines
  • Notes and other notices

Notes and other notices

Notices are carefully selected, called-out text. They purposely break the flow of text to grab a reader’s attention and highlight important information.

Notice types:

  • Note: Information concerning behavior that would not be expected, but won’t break anything if it’s not followed.
  • Important: Information that the reader really needs to pay attention to, otherwise things won’t work.
  • Warning: Information necessary to avoid breaking something or losing data.

You can set the notice label to anything you want. For example, you might want an important note to start with Protect your password!:

Protect your password! Store your password in a password manager. Never write passwords down on paper, or share them in plaintext.

Best practices

  • When using notices, think about whether the thing you’re trying to note is actually a note (or warning, or caution), or simply another piece of information that fits the flow of the task or content on the page.
  • Avoid nesting too many elements inside notices.
  • Keep notices short.
  • Don’t stack notices. You never want to place multiple notices one after the other.

Notice types

Crete a notice with Markdown blockquotes (>) and a class to display a specific style:

Note

This is a generic note block that points out useful information that the reader should pay attention to, but won’t break anything if it’s not followed. If you don’t use any class at all, the blockquote element defaults to this style.

{:.note}
> **Note**: Here's some info.

Note: Here’s some info.

Important

Use the important block for something that the reader really needs to pay attention to, otherwise the thing they’re trying to do won’t work.

{:.important}
> **Important:** Be cautious about this thing.

Important: Be cautious about this thing.

Warning

Use the warning block for any breaking changes, or for anything irreversible.

{:.warning}
> **Warning:** Everything will break forever if you do this.

Warning: Everything will break forever if you do this.

No icon

If you have a situation where you need to use a specific notice type but the icon doesn’t belong, you can hide the icon by setting no-icon along with any other notice class. For example, here’s the result of using {:.warning .no-icon}:

{:.warning .no-icon}
> This is something that's vital in a special way and the icon doesn't apply.

This is something that’s vital in a special way and the icon doesn’t apply.

Thank you for your feedback.
Was this page useful?
  • Kong
    THE CLOUD CONNECTIVITY COMPANY

    Kong powers reliable digital connections across APIs, hybrid and multi-cloud environments.

    • Company
    • Customers
    • Events
    • Investors
    • Careers Hiring!
    • Partners
    • Press
    • Contact
  • Products
    • Kong Konnect
    • Kong Gateway
    • Kong Mesh
    • Get Started
    • Pricing
  • Resources
    • eBooks
    • Webinars
    • Briefs
    • Blog
    • API Gateway
    • Microservices
  • Open Source
    • Install Kong Gateway
    • Kong Community
    • Kubernetes Ingress
    • Kuma
    • Insomnia
  • Solutions
    • Decentralize
    • Secure & Govern
    • Create a Dev Platform
    • API Gateway
    • Kubernetes
    • Service Mesh
Star
  • Terms•Privacy
© Kong Inc. 2023