Skip to content

Markdown Syntax

The easiest way to document is to use markdown syntax. You write the code in plain text with some easy formatting rules. This can be transformed into HTML or other formats. But it's not an inherent standard, different flavors exist.

For the alinex modules I decided to use this as the base for documentation. The following examples should help to use the right syntax which will be interpreted by GitHub and the integrated document generation of the alinex-builder.

Headings

Two formats of headers are supported. First you may use double or single underlines:

Heading Level 1
==========================================

Heading Level 2
------------------------------------------

Or you can define the headings with starting hash signs:

# Heading Level 1

## Heading Level 2

### Heading Level 4

#### Heading Level 3

##### Heading Level 5

###### Heading Level 6

Paragraphs

Paragraphs are written with an empty line. Newlines are ignored but you may add an <br /> Tag if you want:

This text
will be in one line
<br>And this in a new one.

becomes

This text will be in one line
And this in a new one.

Text Format

This styles can be used inline and also within a word. To prevent wrong interpretation you may escape the signs with an backslash \.

Strikethrough

Currently not supported in the document generation but in GitHub view!

Use a double tilde sign before and after the text:

Here is the ~~wrong text~~ right text.

becomes

Here is the wrong text right text.

Emphasis

*single asterisks*

_single underscores_

becomes

single asterisks

single underscores

Strong

**double asterisks**

__double underscores__

becomes

double asterisks

double underscores

Code

`code in backquotes`

becomes

`code in backquotes`

If you give a standard URL in the text an link will be added automatically. You can also surround them with <...>:

http://example.com and <http://example.com>

info@alinex.de and <info@alinex.de>

becomes

http://example.com and http://example.com

info@alinex.de and info@alinex.de

You may also give a special link text by writing the text in square brackets and the link in round brackets behind:

This is the alinex [home](http://alinex.github.io/node-alinex).

becomes

This is the alinex home.

And at last you may use referenced links like that

This is [an example][id] reference-style link.

[id]: http://example.com/  "Optional Title Here"

becomes

This is an example reference-style link.

The referenced links will get you the same output but makes the source code more readable. You may also keep the id empty to use the name also as the id.

Lists

You can write unordered lists like:

* red
* green
* blue

which becomes

  • red
  • green
  • blue

You can do the exactly same with an *, + or - sign.

Ordered lists are written with the numbers following by periods:

1. red
2. green
3. blue

will become

  1. red
  2. green
  3. blue

If your list entry has multiple paragraph the second paragraph has to be indented by 4 spaces. To avoid interpreting number with dots as list you may escape the dot with an backslash.

Blockquotes

You may use email like block indenting with lines beginning with one or multiple >. You can also be lazy and put the sign only on the first line of an paragraph.

I answered

> Hello
>
> > Is this code written in coffeescript?
>
> Thats correct.

becomes

I answered

Hello

Is this code written in coffeescript?

Thats correct.

Blockquotes can also contain any other markdown format.

Code blocks

Standard Markup Syntax is to indent code blocks with four spaces:

function test() {
  console.log('Test succeeded!');
}

A better way is to fence the code like below. This also adds the ability to specify the language used (needed for syntax highlighting):

``` javascript
function test() {
  console.log('Test succeeded!');
}
```

``` coffee
test = ->
  console.log 'Test succeeded!'
```

becomes

function test() {
  console.log("Test succeeded!");
}
test = ->
  console.log 'Test succeeded!'

Possible languages are listed in the languages YAML file.

Horizontal lines

You can add them by writing a paragraph which consists of only three or more * or - signs:

----------------------

becomes


Tables

Currently not supported in the document generation but in GitHub view!

Tables will be created by dividing cells with a pipe | and the header row with hyphens -:

    | Color | Value  |
    | ----- | ------ |
    | red   | ff0000 |
    | green | 00ff00 |
    | blue  | 0000ff |

becomes

Color Value
red ff0000
green 00ff00
blue 0000ff

The cells don't need the exact same width it may also vary in the same column. And you may put inline markup into the cell like bold, italic...

To align columns you have to add a colon in the divider line between header and body:

| Left               |       Center       |              Right |
| :----------------- | :----------------: | -----------------: |
| first entry        |    first entry     |        first entry |
| another            |      another       |            another |
| and the last entry | and the last entry | and the last entry |

becomes

Left Center Right
first entry first entry first entry
another another another
and the last entry and the last entry and the last entry

Symbols & HTML

You may also use some HTML symbols or tags but only as less as possible:

&copy;<br />&frac12;

becomes

&copy;<br />&frac12;

Images

Images may be placed like links but start with an exclamation mark !:

![Alinex Logo](../alinex-logo.png "ALINEX")

becomes

Alinex Logo

The title at the end is optional but will output as the tooltip.

Like for links you may use the reference style here, too:

![Alinex Logo][id]

[id]: ../alinex-logo.png "ALINEX"

becomes

Alinex Logo

Extended Markdown

Within the report package an extended version of markdown conversion is used supporting all of the above but also

  • boxes
  • emoji
  • special styles
  • table of contents
  • footnotes
  • acronyms
  • and more

Last update: January 1, 2021