DocOps Shields

1. Introduction

The DocOps Shield Extension allows you to create visually appealing badges and shields in your AsciiDoctor documents. Shields are useful for displaying status information, version numbers, build status, and other metadata in a visually consistent way.

This guide will help you understand the basic concepts of shields, how to include them in your AsciiDoctor documents, and provide examples of different types of shields.

2. Basic Concepts

2.1. What are Shields?

Shields in the DocOps extension are SVG-based graphical elements that can be included in your AsciiDoctor documents. Each shield has:

  • A label (the left part of the shield)

  • A message (the right part of the shield)

  • Optional URL for making the shield clickable

  • Optional logo/icon

  • Customizable colors for both label and message sections

  • Customizable font color

The extension supports various styling options, including:

  • Custom colors for label and message sections

  • Icons from the SimpleIcons library

  • Dark mode

  • Custom font colors

  • Links to external resources

2.2. Shield Components

A shield includes:

  • A label (left side)

  • A message (right side)

  • Optional URL for making the shield clickable

  • Optional logo/icon

  • Color settings for visual appearance

3. AsciiDoctor Syntax for Shields

To include shields in your AsciiDoctor document, you use a special macro syntax. The extension supports two input formats: pipe-delimited and JSON.

3.1. Pipe-Delimited Format

Here’s the basic format for pipe-delimited input:

[docops,badge]
----
Label|Message|URL|LabelColor|MessageColor|Logo|FontColor
----

The macro processes the pipe-delimited configuration and generates an SVG representation of the shield that is embedded in your document.

3.2. JSON Format

Alternatively, you can use JSON format for more complex configurations:

[docops,badge]
----
[
  {
    "label": "Status",
    "message": "Stable",
    "labelColor": "#3C3D37",
    "messageColor": "#4CC9F0"
  },
  {
    "label": "Version",
    "message": "1.0.0",
    "labelColor": "#0D47A1",
    "messageColor": "#2196F3",
    "url": "https://example.com/version",
    "logo": "<tag>",
    "fontColor": "#fcfcfc"
  }
]
----

The JSON format allows you to specify multiple badges with all available properties in a structured format.

3.3. Shield Properties

  • Label (required): The text for the left part of the shield

  • Message (required): The text for the right part of the shield

  • URL (optional): The URL to link to when the shield is clicked

  • LabelColor (optional): The color for the label background (default: #999999)

  • MessageColor (optional): The color for the message background (default: #ececec)

  • Logo (optional): The logo to display on the shield (e.g., <github> for GitHub logo)

  • FontColor (optional): The color for the text (default: #000000 for light backgrounds, #fcfcfc for dark backgrounds)

4. Examples

4.1. Basic Shield Example

Here’s a simple example of a shield:

[docops,badge]
----
Status|Stable||#3C3D37|#4CC9F0
----
Status|Stable||#3C3D37|#4CC9F0

4.2. Shield with Logo Example

You can add a logo to your shield using the SimpleIcons library:

[docops,badge]
----
Made With|Kotlin||#06133b|#6fc441|<kotlin>|#fcfcfc
----
DocOps.ioMIT Licensehttps://docops.io2025-06-13Generated by DocOps.io - Licensed under MIT License Made With: KotlinBadge showing Made With with value Kotlin

4.3. Dark Mode Shield Example

You can create dark mode shields by using darker colors for the background and lighter colors for the text:

[docops,badge]
----
Dark Mode|Enabled||#1a1a1a|#4361ee|<moon>|#fcfcfc
----
DocOps.ioMIT Licensehttps://docops.io2025-06-13Generated by DocOps.io - Licensed under MIT License Dark Mode: EnabledBadge showing Dark Mode with value Enabled

You can make your shields clickable by adding a URL:

[docops,badge]
----
GitHub|DocOps|https://github.com/docops|#24292e|#2188ff|<github>|#fcfcfc
----
DocOps.ioMIT Licensehttps://docops.io2025-06-13Generated by DocOps.io - Licensed under MIT License GitHub: DocOpsBadge showing GitHub with value DocOps

4.5. Custom Color Shield Example

You can use custom colors for both the label and message sections:

[docops,badge]
----
License|Apache 2.0||#D988B9|#3B1E54|<license>|#fcfcfc
----
DocOps.ioMIT Licensehttps://docops.io2025-06-13Generated by DocOps.io - Licensed under MIT License License: Apache 2.0Badge showing License with value Apache 2.0

4.6. Multiple Shields Example

You can create multiple shields by adding multiple lines to the badge macro:

[docops,badge]
----
Made With|Kotlin||#06133b|#6fc441|<kotlin>|#fcfcfc
JVM|Runtime||#acacac|#3B1E54|<java>|#fcfcfc
AsciiDoctor|Documentation||#acacac|#4CC9FE|<asciidoctor>|#fcfcfc
----
DocOps.ioMIT Licensehttps://docops.io2025-06-13Generated by DocOps.io - Licensed under MIT License Made With: KotlinBadge showing Made With with value Kotlin JVM: RuntimeBadge showing JVM with value Runtime AsciiDoctor: DocumentationBadge showing AsciiDoctor with value Documentation

4.7. CI/CD Status Badges Example

Badges are commonly used to display CI/CD status information:

[docops,badge]
----
Build|Passing||#2A2A2A|#4CAF50|<checkmark>|#fcfcfc
Tests|98%||#2A2A2A|#03A9F4|<test>|#fcfcfc
Coverage|87%||#2A2A2A|#FF9800|<shield>|#fcfcfc
----
DocOps.ioMIT Licensehttps://docops.io2025-06-13Generated by DocOps.io - Licensed under MIT License Build: PassingBadge showing Build with value Passing Tests: 98%Badge showing Tests with value 98% Coverage: 87%Badge showing Coverage with value 87%

4.8. Version Information Badges Example

Display version information with badges:

[docops,badge]
----
Version|v2.3.0||#0D47A1|#2196F3|<tag>|#fcfcfc
Release|Stable||#1B5E20|#4CAF50|<rocket>|#fcfcfc
Updated|2023-06-15||#311B92|#7C4DFF|<calendar>|#fcfcfc
----
DocOps.ioMIT Licensehttps://docops.io2025-06-13Generated by DocOps.io - Licensed under MIT License Version: v2.3.0Badge showing Version with value v2.3.0 Release: StableBadge showing Release with value Stable Updated: 2023-06-15Badge showing Updated with value 2023-06-15

4.9. Security and Compliance Badges Example

Showcase security and compliance information:

[docops,badge]
----
Security|A+||#B71C1C|#F44336|<security>|#fcfcfc
GDPR|Compliant||#004D40|#009688|<checklist>|#fcfcfc
HIPAA|Certified||#4A148C|#9C27B0|<verified>|#fcfcfc
----
DocOps.ioMIT Licensehttps://docops.io2025-06-13Generated by DocOps.io - Licensed under MIT License Security: A+Badge showing Security with value A+ GDPR: CompliantBadge showing GDPR with value Compliant HIPAA: CertifiedBadge showing HIPAA with value Certified

4.10. Technology Stack Badges Example

Display your technology stack with badges:

[docops,badge]
----
Frontend|React||#282C34|#61DAFB|<react>|#fcfcfc
Backend|Node.js||#333333|#8CC84B|<nodedotjs>|#fcfcfc
Database|MongoDB||#1B2A3A|#47A248|<mongodb>|#fcfcfc
Cloud|AWS||#232F3E|#FF9900|<amazonaws>|#fcfcfc
----
DocOps.ioMIT Licensehttps://docops.io2025-06-13Generated by DocOps.io - Licensed under MIT License Frontend: ReactBadge showing Frontend with value React Backend: Node.jsBadge showing Backend with value Node.js Database: MongoDBBadge showing Database with value MongoDB Cloud: AWSBadge showing Cloud with value AWS

4.11. Documentation Status Badges Example

Show the status of your documentation:

[docops,badge]
----
Docs|Up to date||#1A237E|#3F51B5|<book>|#fcfcfc
API|Documented||#BF360C|#FF5722|<api>|#fcfcfc
Examples|Available||#006064|#00BCD4|<code>|#fcfcfc
----
DocOps.ioMIT Licensehttps://docops.io2025-06-13Generated by DocOps.io - Licensed under MIT License Docs: Up to dateBadge showing Docs with value Up to date API: DocumentedBadge showing API with value Documented Examples: AvailableBadge showing Examples with value Available

4.12. Social Media Badges Example

Link to your social media profiles:

[docops,badge]
----
GitHub|Follow|https://github.com/docops|#24292E|#181717|<github>|#fcfcfc
Twitter|@docops|https://twitter.com/docops|#1DA1F2|#1DA1F2|<twitter>|#fcfcfc
LinkedIn|Connect|https://linkedin.com/company/docops|#0A66C2|#0A66C2|<linkedin>|#fcfcfc
----
DocOps.ioMIT Licensehttps://docops.io2025-06-13Generated by DocOps.io - Licensed under MIT License GitHub: FollowBadge showing GitHub with value Follow Twitter: @docopsBadge showing Twitter with value @docops LinkedIn: ConnectBadge showing LinkedIn with value Connect

4.13. Gradient-Style Badges Example

Create badges with complementary color schemes:

[docops,badge]
----
Premium|Feature||#6A1B9A|#9C27B0|<star>|#fcfcfc
Pro|Subscription||#1565C0|#2196F3|<award>|#fcfcfc
Enterprise|Solution||#283593|#3F51B5|<building>|#fcfcfc
----
DocOps.ioMIT Licensehttps://docops.io2025-06-13Generated by DocOps.io - Licensed under MIT License Premium: FeatureBadge showing Premium with value Feature Pro: SubscriptionBadge showing Pro with value Subscription Enterprise: SolutionBadge showing Enterprise with value Solution

5. Conclusion

The DocOps Shield Extension provides a powerful way to enhance your AsciiDoctor documents with visually appealing badges and shields. By using either the pipe-delimited or JSON configuration format, you can create customized shields that match your document’s style and purpose.

The pipe-delimited format offers a simple, concise syntax for basic shield configurations, while the JSON format provides a more structured approach for complex configurations with multiple badges.

The extension supports various customization options, including custom colors, logos, links, and dark mode, allowing you to create shields that effectively communicate status information and metadata in your documentation.

With the examples provided in this guide, you can create badges for various use cases, including CI/CD status, version information, security and compliance, technology stack, documentation status, and social media links.