Skip to content

Markdown Style Guide

Jump to bottom
cgebken edited this page Dec 20, 2019 · 35 revisions

You can use Markdown to get a great formatted output in return of a plain text. To ensure a simple and consistent syntax, stick to the following guidelines and write in American English.

Front Matter

The front matter is obligatory for every post. You need to insert it at the beginning of your post. It contains the following information:

  • layout For every blogpost you need to enter post

  • title Choose a meaningful and interest arising title

  • date Enter the date of the day the blogpost will be published in the following format: yyyy-MM-dd

  • header_image Enter the name of the image in the following format: public|private/image name.file format, e.g.: public/jellybears.jpg. Take into account the information concerning image handling

  • category Enter the key of the category that relates best to your post:
    api-experience: API Experience
    coding: Coding
    events: Events
    language-and-localization: Language & Localization
    methods-and-tools: Methods & Tools
    on-the-job: On the job
    tech-stories: Tech Stories
    techcomm-and-socialmedia: TechComm & Social Media
    ux-and-design: UX & Design

  • tags Enter tags, that relate to your post in the following format: ["tag1","tag2"]
    Every post is unique and can require it's own or special tags. But here is a list of possible tags, to give you a rough idea of how to choose them:

    • microservice
    • api
    • docker
    • agile
    • scrum
    • localization
    • ux
    • design
    • ruby
    • rails
    • javascript
    • java
    • nodejs
    • reactjs
    • webpack
    • gradle
    • ansible
    • springboot
    • kubernetes

  • authors Enter your name in the following format: ["Your name"]. If there is more than one author, use the following format: ["Name 1", "Name 2"]

  • about_authors Enter your author id of the author YAML file in the following format: ["id"]. If there is more than one author, use the following format: ["id 1", "id 2"].

Optionally, you can adjust the header image:

  • header_position Define which part of the image is shown in the header of your post. The default setting is center but you can also choose bottom or top.
  • header_overlay If you chose a light image, the white title is hard to read. Thus, you can darken the header image.
---
layout: post
title: How to write a blog post
date: 2017-11-16
header_image: best-blog-post-image-ever.jpg
header_position: bottom
header_overlay: true
category: techcomm-and-socialmedia
tags: ["agile"]
authors: ["Birgit", "Christina"]
about_authors: ["bbader","cgebken"]
---

Headings

Use ATX-style for headings. As the level one heading (# h1) is automatically used for the title of your post, use a level two heading (## h2) for your first heading. Exception: For interview blog posts, use level three headings (### h3) for the first heading.

Level one heading (# h1):

This is a level one heading

Level two heading (## h2):

This is a level two heading

Level three heading (### h3):

This is a level three heading

Use a spacing before and after a heading

... text before heading.

## Heading 2

Text after heading...

Text structure

Keep headings and sentences short for a readable and portable source text. Use one sentence per line.

This is the first sentence.
This is the second sentence.
This is the third sentence.

Highlighting

You can highlight parts of your texts using

bold **bold**

or

italics _italics_

Links

Write your sentence naturally, then go back and wrap the most appropriate phrases with the link. Do not title your links as "link" or "here". Use the following format: [text](link) .

  • For links to the ePages developer portal, use the relative link. The relative link start after developer.epages.com. This means instead of
Have a look at our fantastic [epagesdevs blog](https://developer.epages.com/blog/)

you only use

Have a look at our fantastic [epagesdevs blog](/blog/)
  • For external links, use the absolute link. To ensure that the link opens in a different window, use the following format
Have a look at our awesome [Git repository](https://github.com/ePages-de/epages-devblog){:target="_blank"}

Note: We do not support reference-style links as the tests don't cover this format.

Images

We support three different types of images for different use cases:

  1. The Lightbox image is used for images with 100% width and a fixed height. If the reader wants to see the whole image, he can click on it.
{% image_lightbox image="relative full path to the image" %}

Optionally, you can decide how to align the image. The default setting is center.

{% image_lightbox image="relative full path to the image" align="top|center|bottom" %}
  1. The Custom image is used to define the width of your image in percent.
{% image_custom image="relative full path to the image" width="5|10|15|20|25|30|35|40|45|50|100" %}

Optionally, you can define the alignment of the image (default setting is center),

align="left|center|right"

add a caption,

caption="This_is_a_caption"

enable the lightbox view

lightbox

and enable a circle view (e.g. for avatar images)

circle
  1. The Markdown image that is always shown 100%. Do only use this type in rare cases, as the size is not adjustable and the image might fill the whole screen.
![Alternative text](full relative path)

Inline code

Backticks ` designate inline code. Use them for short code quotations and technical keys.

Use one of the HTTP request types `GET`, `POST`, `PULL`, or `PUT`

Use one of the HTTP request types GET, POST, PULL, or PUT

Code blocks

For code quotations longer than a single line, use a code block. Explicitly declare the language.

{% highlight json %}
{
  "message": "Bad Request",
  "status": 400
}
{% endhighlight %}

{% highlight ruby %}
# some syntax highlighted Ruby code
module MyModule
  class MyClass
    def initialize(name)
      @name = name
    end
  end
end
{% endhighlight %}

or

    
        ```ruby
            # some syntax highlighted Ruby code
            module MyModule
              class MyClass
                def initialize(name)
                  @name = name
                end
              end
            end
        ```

Embedded Tweets

If you want to include a Tweet in your blogpost enter

{% twitter absolute link %}

You receive the absolute link by clicking at a tweet. Use the related URL as absolute link. Thus it could look like this:

{% twitter https://twitter.com/epagesdevs/status/932579736953544704 %}

Note: This is the only supported format to embed tweets. We do not support the old format any more!

Videos

We support the implementation of YouTube videos.

{% youtube_video video_id="XYZ" width="560" height="3|5" %}

You can find the video id in the URL of the YouTube video after the v=.
The id of the video https://www.youtube.com/watch?v=j-qMUo8_ChQ is j-qMUo8_ChQ.

Lists

We support two different types of lists:

Fully numbered lists

1. First list item
2. Second list item
3. Third list item
  1. This is the first list item
  2. This is the second list item
  3. This is the third list item

Unordered lists

* First list item
* Second list item
* Third list item
  • This is the first list item
  • This is the second list item
  • This is the third list item

Quotes

If you'd like to mark a sentence as a quote, enter > before that sentence.

> I like the interaction and to discuss about approaches on how to solve things.

Emojis

If you'd like to use an emoji, open Emojipedia or any other website with emojis. Search for the emoji you'd like to use. Copy the emoji and paste it directly into your blog post.

Formulas

You can include standalone formulas and inline formulas in your blog post.

Standalone formulas

\\[ formula \\] e.g. \\[ x = {-b \pm \sqrt{b^2-4ac} \over 2a} \\]

Inline formulas

\\( formula \\) e.g. \\( x = {-b \pm \sqrt{b^2-4ac} \over 2a} \\)
Clone this wiki locally