• How to Write Beautiful and Meaningful Readme.md
  • Divyansh Tripathi [SilentLad]
  • The Nuggets translation Project
  • Permanent link to this article: github.com/xitu/gold-m…
  • Translator: Jessica
  • Proofreader: Vito,Hsu Zilin

How to write elegant and meaningful readme.md

Tips for writing a great Readme file (and why Readme is important)

As developers, we know all the details of the code and project at our fingertips. Yet some of us (myself included) lack soft skills even in online communities.

A developer will spend an hour tweaking the padding and margin of a button. You don’t spend 15 minutes perfecting your project’s Readme file.

I hope most of you already know what a README file is and what it does. But in the case of Mengxin, I’ll do my best to explain what it is.

What is readme.md?

README (as the name implies: “Read me”) is the first file you should read when starting a new project. It contains both a list of useful information about the project and a manual for the project. It’s the first file someone sees when they open your repository on Github or any Git-hosting site.

As you can clearly see, the readme.md file is located at the root of the repository, and it will automatically show up in the project directory on Github.

The.md file suffix comes from the word markdown. It is a markup language for text formatting. Just like HTML, it can elegantly present our documents.

Here is an example of a Markdown file and how it will be rendered on Github. Here, I use VSCode preview, which also shows a preview of the markdown file rendered.

If you want to dig deeper into the language, here’s the official Github Markdown memo.

Why spend time on Readme?

Now let’s get down to business. You’ve spent a few hours working on a project, you’ve posted it on GitHub, and you want visitors, recruiters, colleagues, (or exes?) See this project. Do you really think they’ll go to root/ SRC /app/main.js to see the logic of your code? Really?

Now that you’re aware of the problem, let’s see how to fix it.

Generate documentation for your component

In addition to a project’s Readme, the recording component is also important for building a code base that is easy to understand. This makes it easier to reuse components and maintain code. For example, use tools like Bit (Github) to automatically generate documentation for components shared on bit.dev. (Translator & Editor: Wang Siyuan)

Teams share reusable code components · Bits

Describe your project! (Technique in plain English)

Write a good description for your project. For advice only, you can format the description to the following topics:

  • Title (if possible, provide a title image. If you’re not a graphic designer, edit at canva.com);
  • Description (in words and pictures);
  • Demo (pictures, video links, online Demo links);
  • Technology stack;
  • A few pitfalls to watch out for in your project (potholes you encounter, unique elements of the project);
  • Technical description of the project, such as: installation, start-up, how to contribute;

Let’s dive into the technical details

I’ll use my project as a reference, and I think it’s one of the most beautiful Readme files I’ve ever written or even encountered. You can check out the code for its readme. md file here: silent-lad/VueSolitaire

Use the pencil icon to display the Markdown code:

1. Add pictures! Come on!

You may remember your project well, but your readers may need some actual pictures of the project presentation.

For example, I made a solitaire project and added images as descriptions to the Readme file.

Now you may want to add a video describing your project. Just like in my project. However, Github does not allow you to add videos to Readme files. That… What to do?

… We can use GIF

Github allows you to put a GIF in a Readme file.

2. Medal of Honor

Badges on Readme files give visitors a sense of reality. You can set up custom or regular shields (badges) for your warehouse from the following url: https://shields.io

You can also set up personalized shields, such as the number of stars in the warehouse and the code percentage indicator.

3. Add an online Demo

If you can, please host your project and open a running demo. After that, link the demo to the Readme file. You never know how many people might come to play with your project. In addition, recruiters only like projects that can be demonstrated online. It shows that your project is not just code on Github, but actually a running business.

You can use hyperlinks in the Readme. For example, provide a link to an online demo under the caption image.

4. Use code styles

Markdown provides the option to render text as code style. Therefore, instead of writing code in plain text, use ‘(back single quotes) to wrap code around code styles, such as var a = 1; .

Github also provides the option to specify the language in which the code is written, so that it can use specific text highlighting to improve the readability of the code. You just need to use:

{code language}<space>{code block} ‘ ‘

{‘ ‘} — three backquotes for multiple lines of code, and it also allows you to specify the language of the code block.

Use code highlighting:

Do not use code highlighting:

5. Using HTML

Yes, you can use HTML in Readme. Not all of the features in HTML work, but most do. While you’d be better off with markdown only syntax, some features, such as centered images and centered text, are HTML only.

6. Be creative

The rest is up to you; each project requires a different readme.md file and a different type of description. But keep in mind that the 15-20 minutes you spend on your Readme file can have a huge impact on the number of visitors you get to Github.

For your information, here are some projects with Readme:

  • silent-lad/VueSolitaire
  • silent-lad/Vue2BaremetricsCalendar

To learn more

  • How to share React UI components between projects and applications
  • The top 13 React component libraries for 2020
  • 11 Top React Developer Tools for 2020

If you find any mistakes in your translation or other areas that need to be improved, you are welcome to the Nuggets Translation Program to revise and PR your translation, and you can also get the corresponding reward points. The permanent link to this article at the beginning of this article is the MarkDown link to this article on GitHub.

The Nuggets Translation Project is a community that translates quality Internet technical articles from English sharing articles on nuggets. The content covers Android, iOS, front-end, back-end, blockchain, products, design, artificial intelligence and other fields. If you want to see more high-quality translation, please continue to pay attention to the Translation plan of Digging Gold, the official Weibo, Zhihu column.