15Navigation bars, badges and buttons

Navigation bars are convenient mechanisms for switching between pages within the Wiki, buttons allow for the downloading of files and badges are simple images that show the status of a Wiki page.

All are covered in the following sections.

⬆️ Top

15.1Navigation bars

Navigation bars are used in all PracticalSeries sidebars and footers, they are used to navigate around the Wiki, they look like this:

^{Figure 15.1 — Navigation bars}

The navigation bars in the sidebar and footer are identical for a particular page, the icons have the following meanings:

^{Figure 15.2 — Navigation bar details}

The navigation bar is constructed as a five-column table, each cell is configured with a link to the relevant page. The table is constructed using HTML, the following is a typical example:

^{HTML and GitHub output}

${\large \color{#00C050}\text{H\ T\ M\ L}}$ 🔽

<table align="center"><tr><!-- NAVIGATION BAR -->
    <td align="center"><!-- PREVIOUS PAGE -->
        <a class="hlink" href="06.04-basic-markdown-and-text-formatting">
        <img height="30px" src="https://psop.uk/wi-l" alt="Previous page" title="Previous page"></a></td>
    <td align="center"><!-- PREVIOUS CHAPTER -->
        <a class="hlink" href="05-markdown,-github-markdown-and-html">
        <img height="30px" src="https://psop.uk/wi-u" alt="Previous chapter" title="Previous chapter"></a></td>
    <td align="center"><!-- HOME -->
        <a class="hlink" href="home">
        <img height="30px" src="https://psop.uk/wi-h" alt="Home" title="Home"></a></td>
    <td align="center"><!-- NEXT CHAPTER -->
        <a class="hlink" href="07-special-characters-and-escaping-characters">
        <img height="30px" src="https://psop.uk/wi-d" alt="Next chapter" title="Next chapter"></a></td>
    <td align="center"><!-- NEXT PAGE -->
        <a class="hlink" href="06.10-basic-markdown-and-text-formatting">
        <img height="30px" src="https://psop.uk/wi-r" alt="Next page" title="Next page"></a></td>
</tr></table><!-- END OF NAVIGATION BAR -->

${\large \color{#B00000}\text{G\ I\ T\ H\ U\ B}\space\ \space\text{O\ U\ T\ P\ U\ T}}$ 🔽

^{Table 15.1 — Navigation bar HTML}

This is the link from the side bar of section 6.7.

Each cell of the table <td> contains a link in the form:

${\color{#446FBD}\text{<td\ align="center">}}$

${\color{#446FBD}\text{<a\ class="hlink"\ }\color{#B00000}\text{href="[PageName]"}}$

${\color{#446FBD}\text{<img\ height="30px"\ }\color{#00B050}\text{src="00-0000/02-images/[ImageName]"\ }\color{#ED7D31}\text{alt="[AltName]" title="[ToolTip]"}\color{#446FBD}\text{></a></td>}}$

Where the ${\color{#B00000}\text{href="[PageName]"}}$ is the name of the Wiki page being linked to in the standard format for a link (see section 9.2.1), i.e.:

❶	Do not add the `.md` extension to the ${\color{#B00000}\text{PageName}}$
❷	Any spaces within the ${\color{#B00000}\text{PageName}}$ are replaced with a dash `-`
❸	All uppercase letters are made lowercase (optional)

The ${\color{#00B050}\text{[ImageName]}}$ is one of five images stored in the Wiki directory:

${\color{#446FBD}\text{00-0000/02-images}}$

Image	Filename	Description	Function
	`wi-l.svg`	Wiki image, left arrow	Prev page
	`wi-u.svg`	Wiki image, up arrow	Prev chapter
	`wi-h.svg`	Wiki image, home	Home page
	`wi-d.svg`	Wiki image, down arrow	Next chapter
	`wi-r.svg`	Wiki image, right arrow	Next page
	`wi-b.svg`	Wiki image, white square (blank)	Place holder for a blank cell
^{Table 15.2 — Navigation bar icon images}

If you wish to use these images, I make them available to you, they are contained in the following zip file:

The ${\color{#ED7D31}\text{[AltText]}}$ and ${\color{#ED7D31}\text{[ToolTip]}}$ are always the same for each entry, they provide the tooltip that shows when the mouse hovers over the link and the alternate text if the image is not present.

The text for each of these is listed in the Function column of the above table.

⬆️ Top

15.1.1Navigation bar practicalities

Most pages in a Wiki contain a whole chapter. Under these circumstances, the previous page and the previous chapter have the same link (to the previous chapter). Similarly, the next page and the next chapter are also identical.

Where chapters are split, the previous/next page links to the adjacent section in the current chapter, the previous/next chapter always links to the chapter preceding or following the current chapter.

The first page in the Wiki (generally, the home page) does not have any previous chapter or previous page options; similarly the last page in the Wiki does not have next chapter or next page entries.

In these cases, where a cell in the navigation bar is empty, the entry becomes:

${\color{#446FBD}\text{<td\ align="center">}}$

${\color{#446FBD}\text{<img\ height="30px"\ }\color{#00B050}\text{src="00-0000/02-images/wi-b.svg"\ }\color{#ED7D31}\text{alt="Empty Cell"}\color{#446FBD}\text{></a></td>}}$

I.e. the cell simply contains the blank image (it has the same dimensions as the link images), this maintains the cell width. The cell does not contain an <a> anchor tag, there is no link.

⬆️ Top

15.2Badges

Badges are used extensively in GitHub; these are some examples:

These types of badges are used on all the PracticalSeries Wiki pages. The Web ID one at the top contains the chapter and section number of the current page, the three letters at the end (eck in this case), are a mechanism for tracking the page revision^💠1.

The loc badge is used on sidebar and footer pages to identify which folder the sidebar or footer is located in (it is a mechanism for identifying a particular sidebar or footer, it isn’t always clear which sidebar or footer you are working on, they all have the same name, just the folder is different, see section 4 for details).

The badge in the middle is just an example of what can be done with badges.

The badges used by the PracticalSeries Wiki (and judging by appearances, most GitHub repositories), are generated on demand by the Shields.IO website.

⬆️ Top

15.2.1Creating a badge

These badges are not images stored in the Wiki. They are created dynamically by the Shields.IO website from data passed to it from the Wiki page. Here’s an example:

^{HTML and GitHub output}
${\large \color{#00C050}\text{H\ T\ M\ L}}$ 🔽
<img src="https://img.shields.io/badge/BadgeName-BadgeText-blue">
${\large \color{#B00000}\text{G\ I\ T\ H\ U\ B}\space\ \space\text{O\ U\ T\ P\ U\ T}}$ 🔽

This is what Shields IO refer to as a static badge. Static badges contain fixed information passed to the website when the page is rendered (as opposed to dynamic badges that can read various live data values from a repository, such as the number of commits &c.).

By default static badges are 20 px high (this is generally about right for the GitHub pages). To make the badges bigger or smaller, include the height attribute:

^{HTML and GitHub output}
${\large \color{#00C050}\text{H\ T\ M\ L}}$ 🔽
<img height="40px" src="https://img.shields.io/badge/BadgeName-BadgeText-blue">
${\large \color{#B00000}\text{G\ I\ T\ H\ U\ B}\space\ \space\text{O\ U\ T\ P\ U\ T}}$ 🔽

Important

The Shields IO badges are generated as SVG images and will scale either up or down without distortion.

The image source is always the URL: https://img.shields.io/badge/, this is followed by the text for the BadgeName (the left-hand section of the badge with the grey background), followed by a dash character - and then the BadgeText (the right-hand section of the badge with the coloured background).

This is followed by an addition dash - and then the colour for the background of the right-hand side of the badge.

The predefined colours are as follows; each is a range of colours from the top to the bottom:

Colour	Name	Top colour	Bottom colour
	`brightgreen, success`	`#4FCA21`	`#3DB80F`
	`green`	`#9AC812`	`#89B701`
	`yellow`	`#DBB327`	`#C9A115`
	`yellowgreen`	`#A6A82C`	`#94961A`
	`orange, important`	`#F78344`	`#E57132`
	`red, critical`	`#DC664F`	`#CA543D`
	`blue, informational`	`#4FCA21`	`#3DB80F`
	`grey, gray`	`#5F5F5F`	`#4D4D4D`
	`lightgrey, lightgray, inactive`	`#A1A1A1`	`#8F8F8F`
^{Table 15.3 — Shield.IO predefined colours and names}

The colour can also be specified in hexadecimal RGB format:

^{HTML and GitHub output}
${\large \color{#00C050}\text{H\ T\ M\ L}}$ 🔽
<img height="40px" src="https://img.shields.io/badge/BadgeName-BadgeText-4472C4">
${\large \color{#B00000}\text{G\ I\ T\ H\ U\ B}\space\ \space\text{O\ U\ T\ P\ U\ T}}$ 🔽

Note

The hexadecimal number is entered without a leading hash #.

Spaces can be inserted into the text strings by using an underscore _ or by using the %20 character string (see section 9.6.2). For example:

^{HTML and GitHub output}
${\large \color{#00C050}\text{H\ T\ M\ L}}$ 🔽
<img height="40px" src="https://img.shields.io/badge/Badge_Name-Badge%20Text-4472C4">
${\large \color{#B00000}\text{G\ I\ T\ H\ U\ B}\space\ \space\text{O\ U\ T\ P\ U\ T}}$ 🔽

Other escape sequences are:

A dash character - is entered as a double dash -- An underscore character _ is entered as a double underscore __

^{HTML and GitHub output}
${\large \color{#00C050}\text{H\ T\ M\ L}}$ 🔽
<img height="40px" src="https://img.shields.io/badge/Badge__Name-Badge--Text-4472C4">
${\large \color{#B00000}\text{G\ I\ T\ H\ U\ B}\space\ \space\text{O\ U\ T\ P\ U\ T}}$ 🔽

⬆️ Top

15.2.2Static badge options

The basic form of the static badge:

^HTML
${\large \color{#00C050}\text{H\ T\ M\ L}}$ 🔽
<img src="https://img.shields.io/badge/BadgeName-BadgeText-Colour">

Can be supplemented by various other parameters. These are added to the URL as queries after the Colour entry as follows:

^HTML
${\large \color{#00C050}\text{H\ T\ M\ L}}$ 🔽
<img src="https://img.shields.io/badge/BadgeName-BadgeText-Colour?style=[style]&logo=[logo] &logoColor=[logoColor]&logoSize=[logoSize]&labelColor=[labelColor]&color=[Color]">

Where:

Parameter	Function	Values
`[style]`	Changes the appearance of the badge. Note: any defined colours are ignored if the social style is selected.	`#flat` (default)
		`flat-square`
		`plastic`
		`for-the-badge`
		`social`
`[logo]`	Adds a particular logo to the badge before the BadgeName The full list of logo codes is available here: https://simpleicons.org/	`dotenv`
		`github`
		`git`
`[logoColor]`	Changes the colour of any selected logo (see [logo])	`blue`
`[logoSize]`	The only option is `auto`, it resizes some logos and make them fit better	`auto`
`[labelColor]`	Changes the background colour of the left-hand side of the badge	`#C00000`
`[Color]`	Changes the background colour of the right-hand side of the badge (overrides any colour specified in the link)	`orange`
^{Table 15.4 — Shields.IO static badge parameters}

The following produces this badge:

^{HTML and GitHub output}
${\large \color{#00C050}\text{H\ T\ M\ L}}$ 🔽
<img height="40" src="https://img.shields.io/badge/BadgeName-BadgeText-blue?style=flat&logo=dotenv &logoColor=grey&logoSize=auto&labelColor=brightgreen&color=red">

⬆️ Top

15.2.3Dynamic badges

Dynamic badges display some information about a repository (number of commits, repository size, releases status &c.). Dynamic badges are orientated towards the repository itself and not the Wiki associated with a repository so they have limited use as far as the Wiki is concerned.

Dynamic badges are again created by the Shields.IO website from data passed to it from the Wiki page. Here’s an example (repository size):

^{HTML and GitHub output}
${\large \color{#00C050}\text{H\ T\ M\ L}}$ 🔽
<img height="40" src="https://img.shields.io/github/repo-size/practicalseries/PS2001-pal-software">

The data in the badge updates each time the webpage is reloaded or refreshed.

Dynamic badges require information about the repository, in the above example it needed the username and repository name in the format:

${\color{#446FBD}\text{<img\ src"}\color{#C00000}\text{http:}\text{//img.shields.io/github/}\color{#00B050}\text{[repo-size]/}\color{#ED7D31}\text{[UserName]/}\color{#4B0082}\text{[RepositoryName]}\color{#446FBD}\text{">}}$

The repo-size entry changes depending on the metric being accessed.

There are a great many different dynamic badges available via the Shields.IO website. The website also has a built-in configuration tool that generates and tests the badge from information you supply.

The following is the populated webpage for the above badge, the page is available here:

https://shields.io/badges/git-hub-repo-size

The populated page looks like this:

^{Figure 15.1 — Dynamic badge configuration}

Enter the username in point 1 and enter the repository name in point 2.

To see what the badge looks like, click the ${\large \color{#00B050}\langle\text{Execute}\rangle}$ button, point 3 and the badge is displayed point 4.

The populated link can be copied by hovering the mouse over it and clicking the copy button, point 5. This is the src="https:…" link in the <img> tag above.

There is a very brief description of what each entry means in the centre of the page, point 6. Sometimes these are not very helpful and some experimentation is required.

All the dynamic badges for GitHub are listed in the entries on the left-hand side, in this case it was under Size, point 7 and GitHub repo size, point 8. The biggest problem is guessing the title under which the badge you require is listed.

Note

All the dynamic badges that can be used on GitHub start with the word GitHub.

Some badges require a commit number, generally give this as the full 40-digit sha number. E.g.: 224d0145ba4afb930a9517c91817ed61c732cb2c.

Dynamic badges can be coloured and the text changed using the same options as for a static badge, see section 15.2.2.

⬆️ Top

15.3Buttons

GitHub doesn’t directly support the use of buttons in Markdown, despite having its own buttons on the screen (the ${\large \color{#00B050}\langle\text{new\ page}\rangle}$ button at the top of each Wiki page for example).

It is possible to add a button by creating an image (with any associated text) and pasting it into a Wiki page as a link (see section 11.2.4).

There is, however, a much easier way using the Shield IO (discussed in the previous sections). Look at the following (it works by the way):

This uses a Shields IO badge in a HTML link as follows:

^{HTML and GitHub output}
${\large \color{#00C050}\text{H\ T\ M\ L}}$ 🔽
<a href="https://github.com/practicalseries/GitHub-Wiki-Design-and-Implementation/wiki/00-0000/04-data/github-wiki-design.pdf"><img height="30" src="https://img.shields.io/badge/Download_the_pdf_document-1F883D"></a>
${\large \color{#B00000}\text{G\ I\ T\ H\ U\ B}\space\ \space\text{O\ U\ T\ P\ U\ T}}$ 🔽

^{Table 15.5 — An example button}

The first part is an anchor link to the downloadable document (see section 9.6 for details). In this case it is:

https://github.com/practicalseries/GitHub-Wiki-Design-and-Implementation/wiki/00-0000/04-data/github-wiki-design.pdf

This is the download link to the pdf version of this Wiki, it works if you put it into a web browser.

This is followed by an <img> tag that contains a Shields IO badge (just like those in the previous sections). The only difference is that the BadgeName (the left-hand side of the badge) is missing.

This is a perfectly acceptable arrangement for Shield IO badges.

The normal format for a Shields IO badge is:

^{HTML and GitHub output}
${\large \color{#00C050}\text{H\ T\ M\ L}}$ 🔽
<img src="https://img.shields.io/badge/BadgeName-BadgeText-blue">
${\large \color{#B00000}\text{G\ I\ T\ H\ U\ B}\space\ \space\text{O\ U\ T\ P\ U\ T}}$ 🔽

By removing the BadgeName and the first dash - we have:

^{HTML and GitHub output}
${\large \color{#00C050}\text{H\ T\ M\ L}}$ 🔽
<img src="https://img.shields.io/badge/BadgeText-blue">
${\large \color{#B00000}\text{G\ I\ T\ H\ U\ B}\space\ \space\text{O\ U\ T\ P\ U\ T}}$ 🔽

That’s all we’ve done here, the general format for a button is thus:

^HTML
${\large \color{#00C050}\text{H\ T\ M\ L}}$ 🔽
<a href="[LinkURL]" download><img height="30" src="https://img.shields.io/badge/[BadgeText]-1F883D"></a>
^{Table 15.6 — Button general format}

Where [LinkURL] is the link to whatever the button is linking to.

The [BadgeText] is the text that appears on the button.

The button itself is given the colour #1F883D which is the green colour of the GitHub buttons (obviously, you can choose any colour for your button, I’ve just made mine the same as GitHub).

To centre a button on the screen put a <p align="center"> before the link and </p> after it:

^{HTML and GitHub output}
${\large \color{#00C050}\text{H\ T\ M\ L}}$ 🔽
<p align="center"><a href="https://github.com/practicalseries/GitHub-Wiki-Design-and-Implementation/ wiki/00-0000/04-data/github-wiki-design.pdf"><img height="30" src="https://img.shields.io/badge/ Download_the_pdf_document-1F883D"></a></p>
${\large \color{#B00000}\text{G\ I\ T\ H\ U\ B}\space\ \space\text{O\ U\ T\ P\ U\ T}}$ 🔽

Footnotes:

Note

^💠1 The encoding I use is just the date I posted the page, it helps me keep track of which revision the page is at. The first letter is the year (starting at a=2021, b=2022 &c.). The second letter is the month (a=January, b=February &c) and the third is the day (a=1, b=2, … A=27, … E=31).

In the example, eck corresponds to 11^th March 2025.↩

15Navigation bars, badges and buttons

15 navigation bars, badges and buttons - practicalseries/GitHub-Wiki-Design-and-Implementation GitHub Wiki

15Navigation bars, badges and buttons