Markdown Guide for Developers. Markdown is a powerful conversational… | by Cesar William Alvarenga | Mar, 2022

Markdown is a powerful conversational tool for developers. Developers can use it to share their ideas across multiple applications

Have you ever tried to copy text out of a communication app, and it doesn’t format well in another text editor? Have you ever started to write your documentation in a word processor, migrate to a new platform, and it doesn’t adapt? In this article, we’ll learn how to improve our writing skills so we don’t fall into those traps.

Markdown is a powerful conversational tool for developers. Developers can use it to share their ideas across multiple applications easily, clearly, and in most cases platform-independent.

In this post, I will demonstrate how we communicate effectively with co-workers, using markdown. We can apply those strategies in a daily chat using Slack, Discord, or git repositories like GitHub, Bitbucket, or GitLab.

It is important to be clear and contribute with your ideas using well-written messages.

We will start with some recommendations to use in your Git repositories.

Suggestion

You can suggest a specific change to one line or multiple lines of code when reviewing a pull request using the markdown Suggestions. Then, the merge request author can apply these suggestions with a click. This action generates a commit in the merge request, authored by the user that suggested the changes.

In GitHub, to select a multi-line code block, you can either:

  • click and hold to the right of a line number, drag and then release the mouse when you’ve reached the last line of the desired selection; or
  • click on a line number, hold Shiftclick on a second line number and click the “+” button to the right of the second line number.

Once you’ve selected the code block, click the diff icon and edit the text within the suggestion block.

Mermaid

With Mermaid, you can easily create diagrams, sequences, Gantt charts, and more based on the textual description. The purpose of Mermaid is to help with visualizing documentation and helping it catch up with development. The documentation of the textual description can be found here https://mermaid-js.github.io/mermaid.

You can try it and get more examples in this Mermaid Live Editor.

Task lists

Task lists in issues, comments, and pull request descriptions are incredibly useful for project coordination and keeping track of important items.

A task list item consists of a minus sign (-) followed by a left bracket ([), either a whitespace character or the letter x in either lowercase or uppercase, and then a right bracket (]).

When rendered, the task list item is replaced with a semantic checkbox element; in an HTML output, this would be an <input type=”checkbox”> element.

If the character between the brackets is a whitespace character, the checkbox is unchecked. Otherwise, the checkbox is checked.

Maps

You can create interactive maps in your markdown using GeoJSON syntax. GeoJSON is an open standard file format for representing map data. You can find more information in the GeoJSON specification.

Title and Headers

If you want to create a title or header you have to add a hashtag at the beginning of the line.

As you add in more the headers become smaller.

Sections

Three dashes symbolize a horizontal line which is good for different sections of your document.

Emphasize

To emphasize something add asterisks at the beginning and end of the word or phrase. One set means you are italicizing and two you are bolding.

Block Quote

To create a blockquote, add a carrot at the beginning of the line.

You can create an ordered list by numbering each item in the list.

But instead of using one, two, three, and so on. I have a trick for you, you can replace the one, two, three with all ones. This way if you change the order of your list the numbers stay the same.

emojis

You can add in emojis by add in colons at the beginning and end of the emoji name. For example :alarm_clock::pig::airplane: When Pigs Fly.

⏰ 🐷 ✈️ When Pigs Fly.

Link

To add a link in your text, just surround the word or phrase that you want to create a hyperlink for in brackets and then add the link between parentheses.

Code

If you want to add in some code in your text you can add a back-tick at the beginning and end of the code and that will make it look all cody.

For block code and syntax highlighting you will add three back-ticks at the beginning and end of the code.

You can specify what language you are using.

Footnotes

Footnotes allow you to add notes and references without cluttering the body of the document. When you create a footnote, a superscript number with a link appears where you added the footnote reference. Readers can click the link to jump to the content of the footnote at the bottom of the page.

To create a footnote reference, add a caret and an identifier inside brackets ([¹]). Identifiers can be numbers or words, but they can’t contain spaces or tabs. Identifiers only correlate the footnote reference with the footnote itself — in the output, footnotes are numbered sequentially.

Add the footnote using another caret and number inside brackets with a colon and text ([¹]: This text is inside a footnote.). You don’t have to put footnotes at the end of the document. You can put them anywhere except inside other elements like lists, blockquotes, and tables.

Tables

You can build tables to organize information in comments, issues, pull requests, and wikis.

  1. The first line contains the headers, separated by “pipes” (|).
  2. The second line separates the heads from the cells.
    – The cells can contain only empty spaces, hyphens, and (optionally) colons for horizontal alignment.
    – Each cell must contain at least one hyphen, but adding more hyphens to a cell does not change the cell’s rendering.
    – Any content other than hyphens, whitespace, or colons is not allowed
  3. The third, and any following lines, contain the cell values.
    – The cell sizes don’t have to match each other. They are flexible but must be separated by pipes (|).
    – You can have blank cells.
  4. Column widths are calculated dynamically based on the content of the cells.

Additionally, you can choose the alignment of text in columns by adding colons (:) to the sides of the “dash” lines in the second row.

Images

To add an image, add an exclamation mark (!), followed by alt text in brackets, and the path or URL to the image asset in parentheses. You can optionally add a title in quotation marks after the path or URL.

See markdown isn’t that intimidating, if you have all these ideas at your disposal you’ll be off to the races and writing fast and efficiently to communicate with your colleagues.

Because of the reality that we live in today, developers must now devise clever ways to communicate. Learning how to communicate better with your colleagues is important to create a remote-friendly company or organization.

Leave a Comment