Markdown

Good day, colleagues! After a long journey of learning, everyone wants to show the employer their fruits, and to show them only from the best, professional side, right? I think yes. Therefore, in addition to a correctly designed and implemented project, we need to be able to formalize it. The employer won't read all your project code to understand what it is about and what is included in it? In this article, we will finally summarize the previous two, namely: Continuous Integration and Code Coverage , and let us understand on the “front” sheet of the open-source project what we used in our project and what it represents. Today we will talk to you about Markdown, ask our favorite questions: “What is it?” and “Why is this?”, let’s figure out where it is used and how to work with it. There will even be an example, we will implement it in our open-source project . So, let's go!

What is "Markdown"?

Since you and I are programmers, we’ll immediately go to Google and open the first Wiki link , which says: Markdown is a lightweight markup language created with the goal of writing the most readable and easy-to-edit text, but suitable for conversion to languages ​​for advanced publications (HTML , Rich Text and others). Here, to be honest, I don’t have much to add, I think this is an almost perfect explanation.

Why do we need this "Markdown"?

To be honest, it’s actually not bad without it :D But let’s remember our goal: to write a competent project template that already has Continuous Integration and has Code Coverage statistics on the Codecov resource. Why did I mention this? Moreover, Markdown will allow us to take data from these resources and provide the data itself, or badges that will redirect us where we need to get this information. It’s convenient to have everything on one “title” page, rather than scattered in different places, isn’t it?

Where is it used?

Anyone who has uploaded any of their projects to GitHub at least once knows that GitHub persistently wants to invite you to create a README file: What is the extension of this file? That's right, Bolt knows Markdown! As we already know, this file is very easily adjusted to many formats and converted into the HTML we need. But let's take our time and don't rush to immediately add it directly to GitHub.

How to work with it?

First, as you may have noticed, we can add it directly to GitHub and it will work! But we don’t always need to add it to just one project, for example. Or for example we want to think more about how we create it. And here GitHub is no longer suitable for us. And in general, we can create Markdown files not only for the purpose of pushing them to GitHub. Secondly, we could create it directly through IDEA, which is exactly what we will do, but not right away, for the reason that why do we need a powerful development environment to write one small file? Here I recommend browsing the catalog of easy, and not so easy, Markdown file editors. For myself, I chose Haroopad , it's very simple, accessible, has an instant representation of what you're writing (IDEA does too), and has a syntax hint. This is what the editor window looks like: Here I opened a ready-made README.md of one of my projects. On the left is a cheat sheet, on the right is a display, in the center is text. Everything is very primitive and simple. You can also see badges, which we'll talk about shortly. Those who choose a different way of writing these files - do not be alarmed, all that will be different is the graphical interface. The text, syntax and display will remain unchanged. Example The task is very simple: write README.md so that it contains: information about the project (including badges), information about importing the project, information about the implementation of the project, information about the author’s contacts. Everything is very simple and primitive, as I already said. Let's get down to business.

1. Let's write a title - the name of our project.

   The main and largest heading is created using the hash operator " # " and then the title is written. In our case:

   # ForJavaRushPublication

2. Then we'll write a slightly smaller title, and we'll write "Project Information". The smaller header is preceded by more " # ":

   ## Information

   And then we will write information about the project.

3. Let's insert links to our articles. This is done very simply, and if you use Haroopad, then just type the cheat sheet and the template will be inserted itself. The syntax is: " [text](url) ";

4. Let's insert badges. Let's take a closer look here.

   First, let's arrange them in the form of a table, for beauty. There will be 2 columns and 2 columns. The syntax will look something like this:

   And the result will be like this:

   Next, we’ll insert hyperlinks to our badges, but where can we get them? I showed in the previous article where to get Codecov, but I didn’t mention which one to get. Since we have a Markdown file, we also need a Markdown Badge:

   Just copy it and paste it into a column in our Markdown. But don’t forget that Codecov appeared in the JaCoCo branch, but not in master, so you’ll have to correct it manually. Travis CI Badge is taken directly opposite the project name, where the build log is:

   We pick the badge, and then the settings window pops up:

   We definitely select Markdown, and the branch that you need. I will make README.md for two branches, and they will be slightly different, because I have not yet implemented Codecov in the master branch.




5. Let's write information on how to import or clone this project. I won’t explain how to do this, but you can read it in my README.md. We will write about the technologies that we used in our project, placing links to them. Still, this is an educational project. Well, let's write down the contact information.




6. Our Markdown is ready. All we have to do is add it to our project and we're done. But not all at once! Let's open our IDEA, and in Plugins we check that you have Markdown Support:

   I have Ultimate IDEA, so I have everything, your plugin may not be installed by default, but when you create a file with the md extension, you should be prompted to download it. Download and restart your IDEA.




7. After importing the Markdown we wrote, open it through IDEA and edit it if necessary. This is what it looks like via IDEA:

   We do push. Then we see that when opening a project, information about it is immediately loaded, this is our README.md:

   Now, when we click on the badge, we can jump straight to the project assembly and see what we have there and how.




8. I’ll do the same for the JaCoCo branch in order to demonstrate Codecov Badge, because we don’t have README.md in it yet. As a result, we now have two badges:

   Codecov shows the percentage of code coverage, and it can also redirect us to the Codecov page and show a detailed code coverage report.

useful links

• What Wiki tells us about Markdown;
• Markdown Editors Directory ;
• Haroopad which I recommend;
• About Markdown on the JetBrains website ;
• Markdown Navigator on the same JetBrains;
• Badges and everything about them. Here you can choose the style of any badge and customize it for yourself;
• How to upgrade your open-source project? This article will also answer ;
• Previous article

Let's summarize the series of my articles

1. We looked at what CI is, what it is for and how to use it in the first article about Continuous Integration ;
2. We played around with CC and understood what it is and why it is needed in the second article about Code Coverage ;
3. And in this article we looked at what Markdown is, why it is needed and how to use it effectively.

Thank you all for reading these three long articles, I hope they were useful. There may be errors and omissions in the text. Thank you all for your attention!