The README files are generally made in markdown syntax which you can learn from these links
As markdown syntax is pretty much flexible, so many times same text renders in different way on various platforms.
This happens because most of the people make very common mistakes while creating the markdown files. Those mistakes may not get visible on their local editors but become clearly visible when the markdown file gets hosted on popular code repositories like Github, Bitbucket, Azure, etc.
So to overcome this issue it is recommended to use some kind of markdown linters which force creator to use standard syntax while making markdown files.
For the same purpose, I have found quite impressive linter https://textlint.github.io/ that we should use. So to use it, you can copy the content of README file into https://textlint.github.io/playground/ then see the lint errors and resolve all of them. That would make your README pretty readable to users.
Note: The textlint - playground can be found at textlint.github.io where textlint is a pluggable and configurable linter tool for Natural Language. Maintain your text quality with ease.
Apart from this you can follow few common rules while creating markdown file as given below:
1. Change the title to repository name rather.
- for Github: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet
- for BitBucket: https://confluence.atlassian.com/bitbucketserver/markdown-syntax-guide-776639995.html
This happens because most of the people make very common mistakes while creating the markdown files. Those mistakes may not get visible on their local editors but become clearly visible when the markdown file gets hosted on popular code repositories like Github, Bitbucket, Azure, etc.
So to overcome this issue it is recommended to use some kind of markdown linters which force creator to use standard syntax while making markdown files.
For the same purpose, I have found quite impressive linter https://textlint.github.io/ that we should use. So to use it, you can copy the content of README file into https://textlint.github.io/playground/ then see the lint errors and resolve all of them. That would make your README pretty readable to users.
Note: The textlint - playground can be found at textlint.github.io where textlint is a pluggable and configurable linter tool for Natural Language. Maintain your text quality with ease.
Apart from this you can follow few common rules while creating markdown file as given below:
1. Change the title to repository name rather.
- For example, change # SMS Starter Example to projectx-sample-sms-java.
3. Always leave one line gap before & after code block. Avoid this
4. Do not put the underline below heading. Avoid this
5. Try to adjust the look via various headings in sequence.
- Start with # that refers to <h1> as main title of the doc
- Then make next heading as ## which refers to <h2>
- Make subsequent sub-headings by increasing the number of # (it can go at max upto h6)
Comments
Post a Comment