[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Convert README.org to plain text README while installing package

From: Yuri Khan
Subject: Re: Convert README.org to plain text README while installing package
Date: Mon, 27 Jun 2022 21:29:47 +0700

On Mon, 27 Jun 2022 at 17:05, Philip Kaludercic <philipk@posteo.net> wrote:

> > Maybe throwing out the badges would be a good first step ;-)
> Then again, this ties into the README files that look better when
> rendered on GitHub/Lab, and where it is worth considering if *not*
> using them would be of more use.

Badges do not have to be ugly in markdown source. Or, at least, they
can be much less ugly.

Let’s dissect [Eglot’s README.md][1] just as an example (only because
it has badges; otherwise, I think Eglot’s README.md is as non-ugly as

[1]: https://raw.githubusercontent.com/joaotavora/eglot/master/README.md


Here we have three source lines, each longer than 80 characters. They
are not separated with blank lines, so they comprise a single
paragraph; the badges are rendered in a single line.

Each badge is a hyperlink [](); brackets contain the link text and
parentheses specify the link target URL. There is alternative syntax
where you put a short reference identifier at the place of use, and
define that reference on a separate line.

    [![GNU ELPA](https://elpa.gnu.org/packages/eglot.svg)][elpa]

    [build]: https://github.com/joaotavora/eglot/actions/workflows/test.yml
    [elpa]: https://elpa.gnu.org/packages/eglot.html
    [melpa]: https://melpa.org/#/eglot

Next, each badge’s text is actually an image ![](). Brackets contain
the alt text fallback for user agents that do not display images; and
parens specify the image URL. The same external reference syntax

    [![Build status][build-badge]][build]
    [![GNU ELPA][elpa-badge]][elpa]

    [build]: https://github.com/joaotavora/eglot/actions/workflows/test.yml
    [elpa]: https://elpa.gnu.org/packages/eglot.html
    [melpa]: https://melpa.org/#/eglot

    [elpa-badge]: https://elpa.gnu.org/packages/eglot.svg
    [melpa-badge]: https://melpa.org/packages/eglot-badge.svg

Now, only one line is longer than 80 characters.

URLs specified this way can appear anywhere in the markdown source.
Eglot’s README actually uses this syntax for all other (non-badge)
hyperlinks and puts URLs at the bottom.

reply via email to

[Prev in Thread] Current Thread [Next in Thread]