Search code examples
htmlgithubmarkdowngithub-flavored-markdownshields.io

Centre-align shield.io in GitHub readme file

I have a GitHub repo with a README.md file. I have some shields beneath my header, but they are left-aligned, not centred.

<a href="">![example1](https://img.shields.io/badge/example-one-red)</a>
<a href="">![example2](https://img.shields.io/badge/example-two-green)</a>
<a href="">![example3](https://img.shields.io/badge/example-three-blue)</a>

I want to centre them, however, wrapping them in a <div align='center'></div> only displays the raw links and not the shield images. Then, I see an alternative using markdown reference style links wrapped in a <h1 align='center'></h1>, like so:

[<h1 align="center">
  [![Contributors][contributors-shield]][contributors-url]
  [![Forks][forks-shield]][forks-url]
  [![Stargazers][stars-shield]][stars-url]
</h1>

[contributors-shield]: https://img.shields.io/github/contributors/othneildrew/Best-README-Template.svg
[contributors-url]: https://example.com
[forks-shield]: https://img.shields.io/github/forks/othneildrew/Best-README-Template.svg
[forks-url]: https://example.com
[stars-shield]: https://img.shields.io/github/stars/othneildrew/Best-README-Template.svg
[stars-url]: https://example.com

Whilst this correctly centre-aligns the shields as I desire, there is a rogue open [ present as shown in the below image:

enter image description here

If I modify the code above to remove it, like so:

<h1 align="center">
  [![Contributors][contributors-shield]][contributors-url]
  [![Forks][forks-shield]][forks-url]
  [![Stargazers][stars-shield]][stars-url]
</h1>

I get the same problem as before: only the raw links are displayed, not the shields. What is this weird behaviour? Is what I'm trying to achieve not possible in HTML/markdown or just not compatible with shields?

Solution

  • I want to centre them, however, wrapping them in a <div align='center'></div> only displays the raw links and not the shield images.

    In GitHub's GFM, you'll need to separate your opening and closing <div> tags from your Markdown with blank lines:

    <div align="center">

  <a href="">![example1](https://img.shields.io/badge/example-one-red)</a>
  <a href="">![example2](https://img.shields.io/badge/example-two-green)</a>
  <a href="">![example3](https://img.shields.io/badge/example-three-blue)</a>

</div>

    This is because (emphasis added)

    [The original Markdown] allows blank lines to occur inside an HTML block. There are two reasons for disallowing them here. First, it removes the need to parse balanced tags, which is expensive and can require backtracking from the end of the document if no matching end tag is found. Second, it provides a very simple and flexible way of including Markdown content inside HTML tags: simply separate the Markdown from the HTML using blank lines

    I don't see anything like [<h1>... in the example you call an "alternative", but please do not abuse <h1> tags this way:

    Using more than one <h1> is allowed by the HTML specification, but is not considered a best practice. Using only one <h1> is beneficial for screenreader users.

    Semantics count! Only top-level header content belongs in an <h1> tag, and there should only be one such tag per page. Shields and badges definitely do not belong there.