weixin_39788572
2020-12-08 21:33 阅读 1

Change README file to Markdown syntax

Use Markdown syntax.

该提问来源于开源项目:wjaguar/mtPaint

  • 点赞
  • 写回答
  • 关注问题
  • 收藏
  • 复制链接分享

4条回答 默认 最新

  • weixin_39658716 weixin_39658716 2020-12-08 21:33

    What for? Markdown, as a format, is so limited it's useless for any practical purpose. For real docs, I use txt2tags ; for simple stuff, the venerable ASCII "------" is all the markup that is needed.

    点赞 评论 复制链接分享
  • weixin_39788572 weixin_39788572 2020-12-08 21:33

    Because Markdown works great on GitHub, when you visit a repository with a README.md file on the GitHub website it gets rendered beautifully. It makes it appear readable and gives off a good first impression.

    It is not useless, it is good enough for a README file, and the preferred format on GitHub. It is is hugely popular and widely understood. It is a de facto standard for projects hosted on GitHub (and many other forges).

    Now other formats (such as txt2tags) might be good too when you pass them through a documentation generator or when building interlinked documentation, but for the README file in the project root directory Markdown works really well.

    点赞 评论 复制链接分享
  • weixin_39658716 weixin_39658716 2020-12-08 21:33

    I.e. Github (aka MS now, but it started before) is pushing the thing for some reason. At the same time, the thing still hasn't got support for tables, nor definition lists. Those are showstoppers, for me. As I do not work for MS, I cannot care less what they push and why. Useless is useless is useless.

    Is pretty-printing the README on Github page really worth the hassle? See, I'll have to keep two versions of it irregardless, as the README as it is now, is also packaged into the handbook.

    点赞 评论 复制链接分享
  • weixin_39788572 weixin_39788572 2020-12-08 21:33

    Markdown does indeed have support for tables.

    First Header | Second Header
    ------------ | -------------
    Content from cell 1 | Content from cell 2
    Content in the first column | Content in the second column
    

    Gets rendered as:

    First Header | Second Header ------------ | ------------- Content from cell 1 | Content from cell 2 Content in the first column | Content in the second column

    While Markdown doesn't have a native syntax for definition lists, you can use HTML inside markdown.

    So

    html
     <dl>
      <dt>Coffee</dt>
      <dd>Black hot drink</dd>
      <dt>Milk</dt>
      <dd>White cold drink</dd>
    </dl> 
    

    `

    Gets rendered as:

    Coffee
    Black hot drink
    Milk
    White cold drink

    I didn't know that README was used in the handbook. On the other hand I am not sure it should.

    点赞 评论 复制链接分享

相关推荐