Skip to content

Standards Markdown Gallery and Preferences

Document Metadata

Every document should start with a metadata block (YAML front matter) as shown below:

---
author: <Author Name>
Copyright: (c) Arda Systems, All rights reserved
License: "Please contact Arda Systems for licensing information"
email: miguel@arda.cards
share: "true"
title: <document title>
---

Currently, comments are supported in all the published documents, if the document should not allow comments, add
a comments: "false" line to the metadata block.

At the end of the document, add the copyright line:

*******
Copyright: © Arda Systems <year of creation or updata>, All rights reserved

Draft Watermark

For documents that need to be marked as draft, add the following line right after the metadata block:

&nbsp;
{ .draftWatermark }

General Syntax Rules

See the .editorconfig file in the root of this repository.

  • Single Blank lines:
    • Before and after headings
    • Before and after lists (bulleted or enumerated)
    • Before and after blockquotes
    • Between Paragraphs
  • Single Spaces:
    • After blockquotes.
    • After # for headers.
    • After a list bullet (-, *).
    • Between words
  • Indentation:
    • Use spaces only, no tabs.
    • 2 spaces for each indentation level, including in code blocks and lists.
  • Lists:
    • Use - for bulleted lists
  • Admonitions
    • Use GitHub style admonitions only (see Notes section below)
  • Horizontal lines
    • Use **** (4 or more asterisks) for horizontal lines, do not use ---- to avoid conflicts with yaml front matter.

Diagrams

Use:

  • PlantUML for diagrams. See PlantUML Guide for details.
  • Draw.io for other types of diagrams: Create a file <name>.drawio.svg in the assets or _assets subfolder where
    the document is located and embed it in the document using ![Alt text](assets/diagram.drawio.svg). The Drawio editor, VS Code and IntelliJ plugins
    will open the file directly and save the editing data in the SVG file itself.

Below this line are examples of markdown syntax

Official Documentation

H2

H3

bold

italic

strike

bold-italic

subscript

superscript

underline

inline code

Quotation

New line: Line 2 Quotation

Code block

function something() {
  return 'asdf'
}

Bullets:

  • Asdfgh
  • Qwerty

Enum

  1. One

  2. Two

    1. (i)

  3. Three

Notes

Note

Useful information that users should know, even when skimming content.

Tip

Helpful advice for doing things better or more easily.

Important

Key information users need to know to achieve their goal.

Warning

Urgent info that needs immediate user attention to avoid problems.

Caution

Advises about risks or negative outcomes of certain actions.

Comments