On GitHub's readme writing and markdown grammar interpretation

Ever since I started to play GitHub, it has become more and more like love. Recently, it has been quite interested in its readme.md file. Write this post to help more students who will not write the Readme file.

The Readme file suffix is called Md. MD is the acronym for Markdown, and Markdown is a language for editing blogs. With the use of a visual blog editor (such as Csdn blog, embarrassing), this programmatic blog editing program is really a bright one. But it doesn't seem to support all the markdown syntax. Most of the content of this article is my own groping, may be some inaccurate narrative, but also hope that you criticize correct.

————————————————————————————

I've built a project for this article on GitHub for you to view the code as a concrete effect: https://github.com/guodongxiaren/test

First of all, we strongly recommend that you do not use 360 or Sogou browser to visit the GitHub website, you will find many buttons are not available at this time. We recommend using Firefox or Google Chrome to access GitHub

————————————————————————————

Start editing the Readme

Open your GitHub project, we can directly online edit your readme file, if you already have this file, then click it directly in the file directory, if you do not have this file then click on the project name to the right of a button to add a new file:

Then you open the edit page, the upper left corner of the editing area has the name of the area filled in, note plus the suffix . MD

If you have this file to re-edit it, then click on the file directory in the file, there is a toolbar above, select Edit

Then scroll to the bottom of the screen, if it is a new file will have a Commit the button of the new file, if no content is not clickable. If the old file is re-edited, then this button shows a Commit changes

Incidentally, if it is 360 or Sogou browser, this button is never clickable, embarrassing.

Just write the new file and then click Edit to reopen it. You will find changes in the upper-left corner of the editing area.

By default, code, our edit mode, is selected. If you click Preview, the current display will be displayed in real time.

Okay, here's the official start of editing this file.

About the title

The specification of the Readme file begins with a title, which is called the headline.

Big headline = = =

Add the equals sign below the text, and the text above becomes a big headline. The number of equals number is unlimited, but must be greater than 0 oh.

Lower than the big headline is the title, that is, the display is smaller than the big title dot.

In the title-------

Underline the text below-the text above becomes the middle title, and the same number of underscores is unlimited.

In addition, the title also has a hierarchical notation, divided into six levels, the text size of the display decreases in turn. The number of pound # is identified between different levels. The first level title has a #, level two heading has two #, and so on.

#一级标题 # #二级标题 # # # # # # # # # # # #四级标题 # # #五级标题 ##### #六级标题

Note that the pound sign # and the title name should be written one line by side, showing the effect

In fact, the headlines and titles described above correspond to the headings of the first level and the level two headings respectively. That is, the large title size is the same as the first level heading, with the same title size and level two headings.

Display textNormal text

The text entered directly is normal text. It is important to note that the line can not be changed directly by carriage return to line, need to use <br>. This is the tag inside the HTML.

This is an ordinary text, the direct return can not be wrapped,<br> to use \<br>

Note that the third row of the <br> front plus a backslash \. The goal is to escape like any other language, that is, the escape of <.

Effect

Also, to display a hyperlink , simply enter the URL of the link. The display will automatically become a linked form.

Single-line text

Use two tab characters to implement a single line of text.

Hello, everyone, I am jelly shrimp.

Note that there are two tabs in front of you. Single-line text display effect on GitHub

Multiple lines of text

Multiple lines of text and a single line of text, just add two tab at the beginning of each line

Welcome to visit. Nice to meet you, good morning, noon, good evening.

Highlighting of some text

If you want to highlight some of the text in a paragraph, and play a prominent role, you can surround it with '. Note that this is not a single quote, but a key to the left of the number 1 (note the English Input method) above the tab.

Thank ' You '. "Call Me ' coder '

Text hyperlink

The format for adding hyperlinks to a text is this [ text to display ] ( The linked address ). For example:

[My blog] (Http://blog.csdn.net/guodongxiaren)

Display effect:

You can also add a mouse hover to display the text.

[My blog] (http://blog.csdn.net/guodongxiaren "hover display")

That is, enclose a string in double quotation marks after the URL. Also note that this is an English double quote.

Insert SymbolDot symbol

• This is a dot symbol

• This is also a dot symbol

The dot above is a list of symbols in the CSDN blog editor. Writing articles is often used when listing entries. The use of dot characters is also supported in GitHub's markdown syntax. When editing, use an asterisk *

* Nickname: Jelly Shrimp * Alias: Next door Lao Wang * English name: Jelly

Note that there is a space behind the asterisk *. Otherwise, it is displayed as a normal asterisk. The above display effect

There are also two-level dots and three-point dots. is to add a tab.

* Programming language * Scripting language * Python

The second line is a tab, and the third row is two tab. This is used to indicate that the hierarchy is clearer, see the effect:

If you think that the level three structure is not enough to express, we can try to change a form, see the character surrounded

Character Surround

I don't know if it's appropriate to call it "character bracketing." I read it too. There's a blog post on the internet, so I'll just call it that. It's embarrassing.

> Data Structures >> trees >>> Two fork tree >>>> balanced binary tree >>>>> full two fork tree

Display effect:

There may be other uses for this "character surround" usage. Let's find out for ourselves.

Insert PicturePictures from the web

There are many tutorials on the web to insert pictures, I have tested it many times, I found that the simplest and most basic syntax to use is:

! [] (Http://www.baidu.com/img/bdlogo.gif)

That's an exclamation mark! + square brackets [] + brackets () where the exclamation mark is the URL of the picture.

If you don't add an exclamation mark! , it will become the normal text of Baidu.

You can include some identifying information in square brackets, such as

! [Baidu] (http://www.baidu.com/img/bdlogo.gif)

Baidu in this square brackets does not make any changes to the image display, if you want to reach the mouse hover display prompt message, then you can follow the previous introduction of the text in the method, that is:

! [Baidu] (http://www.baidu.com/img/bdlogo.gif "Baidu logo")

After the URL, enclose the string with a double quote, showing the effect

Pictures in the GitHub warehouse

Sometimes we want to show a picture of a GitHub repository (or project) instead of a web image from another source, because URLs from other sources are likely to expire. So how do i show a picture of a github project?

In fact, the format is basically consistent with the above, the difference is the URL in parentheses how to write.

https://github.com / your username / your project name/ raw/ branch name / the folder where the picture is stored / the picture under that folder

That's a clear glance. Like what:

! [] (Https://github.com/guodongxiaren/ImageCache/raw/master/Logo/foryou.gif)

My username on GitHub is guodongxiaren; there is a project Imagecache;raw the meaning of the original data, do not care about it; Master Branch master; There is a folder in the Project Logo;logo folder with a picture foryou.gif

Add a hyperlink to a picture

If you want the image to have hyperlinks, click on an image to enter a specific page. Then you can write this:

[! [Baidu]] (http://baidu.com) [Baidu]:http://www.baidu.com/img/bdlogo.gif "Baidu logo"

These two sentences are different from the previous one, but they are also very easy to imitate and write, not too much introduction. Just note that in the context of Baidu is the name of your own identity, you can be arbitrary, but make sure that the next two lines of identification is consistent.

This will enable you to click on the image to enter the page function.

Inserting Code Snippets

We need to mark the last line and the next line of code with a ' '. "is not three single quotes, but the number 1 to the left, TAB key above the key. To implement syntax highlighting then just add your programming language after "(ignoring the case). The C + + language can be written as C + + or CPP. Look at the code:

Actual display effect

[Digression] Write a diary on GitHub with Gist.

Read so many markdown grammar, you must not be satisfied with just write a readme file, began to try to actually use markdown grammar to write a blog or article it. Indeed, there are blogs on the web that rely on or support markdown grammar. But, more conveniently, you can take advantage of a feature--gist on GitHub itself.

Gist is a file-based unit, not a project. And unlike the usual GitHub built-in warehouses, gist is private. Ordinary projects are public by default, want to become private seems to pay the appearance of money. Since it's private, it's great to write a diary.

At the top of the GitHub page are:

Point in:

This is the private file you can edit, which not only supports text text, but also supports a variety of programming languages! Of course, it includes markdown. Enter the file name:

Last save, select Create Secret Gist is private.

On GitHub's readme writing and markdown grammar interpretation