Navbars

Table of Contents

Inhaltsverzeichnis

Imprint

Contents of this Page

  • 1   Overview
  • 2   docutils Containers
  • 3   Navbars with Multiple Sections
    • 3.1   Sections and Groups
    • 3.2   The flexnavbar Container
    • 3.3   The flexgroup Container
    • 3.4   The Sections of the Navbar
  • 4   Navbars with Exactly One Section
  • 5   Footers
  • 6   Display in Printout
  • 7   Summary
  • 8   Discussion

1   Overview

This package serves for the creation of a navigation bar with several regions, each containing e.g. a series of links. Typically there are two such regions, shown at the left and right end of the navigation bar. It is however also possible to show only one such region, or to create arbitrary many regions.

Each region contains one or more sections, which are shown graphically as distinct units. At the sides of each section a specific fixed space is left up to the border of the navigation bar or to the neighbouring section in the respective region. When regions come close to each other by lack of space, this fixed space is left between them as well.

The navigation bar is described in the ReST code by a container. Sections are defined as text paragraphs. Such sections can be placed either directly in the navigation bar container, or they can be grouped by a superordinate group container within the navigation bar. In the former case, the section constitutes a region consisting solely of this one paragraph; in the latter case the sections are shown directly aside of each other in the region described by the group. The group container itself does not show up graphically, it only groups the sections contained within it. It is possible to define exactly one group in the navigation bar; this then is shown always at the left side.

It is for instance possible to write:

.. container:: flexnavbar

    .. container:: flexgroup

        ((Section 1))

        ((Section 2))

    ((Section 3))

This structure is rendered as follows:

Section 1

Section 2

Section 3

The navigation bars of this kind are also called for short navbars.

Additionally, footers are made available in a similar way:

.. container:: flexfooter

    ((left section))

    ((right section))

In footers it is not possible to group sections.

2   docutils Containers

The docutils container directive encloses its content in the HTML rendering by a div element. One writes:

.. container:: ((arguments))

    ((body of the container))

The (optional) arguments of the container directive are translated into class names of the resulting div element.

When the body of a docutils Container contains one single paragraph consisting of continuous text, then this paragraph forms the content of the container div element. When such a text paragraph however is one of several paragraphs in the container, then the paragraph is surrouned by a p element. Paragraphs not consisting of continuous text are never rendered as p elements. This applies e.g. for regions being a group of sections.

This has implications for the design of the navbar styles, because one cannot expect a p element in case there is only one text paragraph. Otherwise, when several paragraphs are present, the p elements can be used for styling.

docutils offers the compound directive to group contents into paragraphs. Thus, one can write:

.. container::

    .. compound::

        ((paragraph content))

Unfortunately, even though the compound directive creates a p element surrounding the ((paragraph content)) as intended, this paragraph however is not placed directly in the container div element. Instead, the p paragraph is embraced by an additional div element in the superordinate div container.

No method is known to me in order to enclose in a container with only one paragraph as body its content in a p element, such that this paragraph is positioned directly in the container div element. Thus, separate styles are provided for navigation bars with several sections and for such with only one section. Such a distinction is also useful to permit choosing for navigation bars with only one section between rendering this section at the left or right end. It is furthermore correct that docutils leaves out the p element when not several paragraphs are present, in order to keep the HTML rendering as simple as possible.

3   Navbars with Multiple Sections

3.1   Sections and Groups

The CSS codes presented here are applicable, when the sections of the navigation bar are enclosed in p elements. This is fulfilled as soon as on all levels with text paragraphs at least two paragraphs are present:

  1. When no grouping is used, at least two text paragraphs need to be present in the navigation bar.
  2. Once grouping is conducted, it is guaranteed that the section paragraphs are enclosed in p elements.

(2.) is grounded on the following observations:

  • A group consists always of at least two paragraphs, otherwise it isn't a group.
  • When in the container holding the group additional paragraphs are present, on this level with necessity multiple paragraphs are involved as well.

An example for a navigation bar without groups showing two paragraphs is:

.. container:: flexnavbar

    ((section 1))

    ((section 2))

A navbar defined in such a way is rendered as:

section 1

section 2

Instead of each text paragraph here a group can be written (.. container:: flexgroup), see above.

Furthermore it is possible to code in the navigation bar exactly one group having multiple sections:

.. container:: flexnavbar

    .. container:: flexgroup

        ((section 1))

        ((section 2))

        ((section 3))

Here, the group is shown always on the left-hand side of the navigation bar:

section 1

section 2

section 3

3.2   The flexnavbar Container

We give the div.flexnavbar the following style:

div.flexnavbar {
    display: flex;
    justify-content: space-between;
    background-color: #f8f8f8;

    column-gap: 1.5ex;
    padding: 0 1.5ex;

    border: thin solid #ddd;
    border-radius: 1.5ex;
}

By the declaration display: flex the div.flexnavbar element turns into a flex container with principal axis from left to right (this is the standard behaviour).

To show in the case of two sections these sections at the left and right ends of the container, the declaration justify-content: space-between is applied.

Furthermore, we give to the entire navigation bar a grey colour tone, with a thin grey border line as well as rounded corners.

At the side ends of the navbar a space of 1.5ex is left between content and border (padding: 0 1.5ex). The distance between neighbouring elements within the navigation bar is bounded towards small values by the same measure of 1.5ex (column-gap: 1.5ex), however, because of justify-content: space-between the distance is typically larger than this figure. The vertical padding between the child elements of the div.flexnavbar elements and the border line amounts to 0, such that groups have exactly the same height.

3.3   The flexgroup Container

Paragraphs in the flexnavbar container can consist either of text or of .. container:: flexgroup containers. These flexgroup elements obtain at their left and right ends by the flexnavbar container the correct spacing up to the ends of the navigation bar or up to neighbouring regions in the navbar. Their only purpose is thus, to behave as flex container and to render their child elements within with correct horizontal spacing. This is achieved by:

div.flexnavbar div.flexgroup {
    display: flex;
    column-gap: 1.5ex;
}

In the vertical direction, the groups are equally high as the complete navbar, and inside of them everything behaves in the same way as in the flexnavbar container.

3.4   The Sections of the Navbar

It has been assumed here already that the sections of the navbar are rendered as p elements. To format these sections of the navbar, it is possible to write:

div.flexnavbar p {
    text-align: left;
    padding: 0.5ex 0.8ex;
    margin: 1.25ex 0;
    background-color: white;

    border: thin solid #ccc;
    border-radius: 1ex;
}

Here those paragraph elements are selected, which are descendants of the container div.flexnavbar element. This applies both to child p elements contained directly in the flexnavbar as well as to those contained within a group residing in the navigation bar. We frame the sections with a thin grey line by setting the border property. The corners of each section's border are rounded, similarly to those of the navbar. In the interior of the frame the sections are picked out by white background (background-color: white) from the navbar.

The frame of a section is furthermore distanced a little bit from its text content (padding). Here, the horizontal distance is chosen slightly larger than the vertical distance, to render these distances visually equal. Padding is in particular required as a correction due to the rounded corners.

By the definition of 1.25ex vertical margin, between the horizontal border lines of the sections and the border of the navbar some spacing remains, which is intentionally a little smaller than the horizontal measure of 1.5ex given by flexnavbar and flexgroup. Since the top and bottom edge of flexgroup group containers coincide with the top and bottom edge of the entire flexnavbar, the 1.25ex vertical margin behaves inside of groups exactly the same as directly in the flexnavbar. Because the horizontal spacing around the sections is determined by the container elements (flexnavbar or flexgroup), the section p elements do not require any horizontal margin.

When in a section no line break is required, its horizontal size is determined precisely by its contained text:

Left Link

Right Link

When the horizontal room in a navigation bar is not sufficient to show the text of the navbar sections single-lined, the text-align: left declaration comes into effect:

Project Table of Contents | Overview of all Projects | Additional Link 1 | Additional Link 2 |

Inhaltsverzeichnis des Projektes | Übersicht aller Projekte | Zusätzlicher Link 1 | Zusätzlicher Link 2

Downloads of the Project | Downloads of the Entire Site | Imprint

The surplus room is collected here by text-align: left at the right end of the section.

4   Navbars with Exactly One Section

In the case of a singleton section in the container for the navigation bar, no subordinate XML element exists to surround the content of the section. It is therefore impossible to graphically set off the single section from the surrounding navigation bar. Thus, it offers itself for the design:

div.flexnavbar-left {
    text-align: left;
    padding: 0.5ex 0.8ex;
    background-color: #f8f8f8;

    border: thin solid #ddd;
    border-radius: 1ex;
}
div.flexnavbar-right {
    text-align: right;
    padding: 0.5ex 0.8ex;
    background-color: #f8f8f8;

    border: thin solid #ddd;
    border-radius: 1ex;
}

These CSS codes raise the section to the navbar. The typesetting is largely equivalent to the design of the paragraphs in case of multi-sectioned navigation bars, but it pertains here to the div region instead of to the p elements, while the grey background of the div element is maintained. Because of this, the single section of the flexnavbar-left or flexnavbar-right navbar stretches over the entire breadth available. The contained text is formatted in the navigation bar left-justified or right-justified, respectively.

For instance, a navigation bar flushed left with a single section using flexnavbar-left is displayed as:

First Link | Second Link

5   Footers

For footers no grouping is provided. In all other respects, footers are populated with content just as navigation bars, only a different CSS class is used for the surrounding container:

.. container:: flexfooter

    ((left section))

    ((right section))

No styles for footers with only one section are defined, because they aren't needed. There is always a section present on the left side with release-related date figures and a section on the right side to navigate in the publication history.

It is more simple to design footers than navigation bars, because footers are separated from the page contents already by a horizontal rule and are graphically in the background. Therefore it suffices to write:

div.flexfooter {
    display: flex;
    justify-content: space-between;
    column-gap: 1.5ex;
}
div.flexfooter > p {
    text-align: left;
    margin-top: 0;
    margin-bottom: 0;
}

Neither background colours nor borders are tailored. The principal approach is very similar to that for navigation bars with several sections: A flex-Container with justify-content: space-between and column-gap: 1.5ex is employed. For the p sections it suffices here to set the margin-top and margin-button figures to 0, overridding the docutils style of 1em.

An example is not given here, because the horizontal rule separating the footer from the text body of the page cannot be reproduced here and moreover it is essential for the rendering, that there is no further content following below the footer.

6   Display in Printout

Navigation bars cannot be used when printed out, and therefore shall be omitted entirely in printout. Furthermore the footers comprise in practice exactly two sections: On the left the release information and on the right tools for navigating in the release history of the article. The right section of footers is therefore irrelevant in printout and shall be removed likewise.

Thus, one writes in the style sheet:

@media print {
    div.flexnavbar { display: none; }
    div.flexfooter > p ~ p { display: none; }
}

For hiding thereby display: none is specified for the respective elements.

7   Summary

The CSS code for navigation bars with multiple sections, for navigation bars with only one section as well as for footers thus runs altogether:

navbars.css
div.flexnavbar {
    display: flex;
    justify-content: space-between;
    background-color: #f8f8f8;

    column-gap: 1.5ex;
    padding: 0 1.5ex;

    border: thin solid #ddd;
    border-radius: 1.5ex;
}
div.flexnavbar div.flexgroup {
    display: flex;
    column-gap: 1.5ex;
}
div.flexnavbar p {
    text-align: left;
    padding: 0.5ex 0.8ex;
    margin: 1.25ex 0;
    background-color: white;

    border: thin solid #ccc;
    border-radius: 1ex;
}

div.flexnavbar-left {
    text-align: left;
    padding: 0.5ex 0.8ex;
    background-color: #f8f8f8;

    border: thin solid #ddd;
    border-radius: 1ex;
}
div.flexnavbar-right {
    text-align: right;
    padding: 0.5ex 0.8ex;
    background-color: #f8f8f8;

    border: thin solid #ddd;
    border-radius: 1ex;
}

div.flexfooter {
    display: flex;
    justify-content: space-between;
    column-gap: 1.5ex;
}
div.flexfooter > p {
    text-align: left;
    margin-top: 0;
    margin-bottom: 0;
}

@media print {
    div.flexnavbar { display: none; }
    div.flexfooter > p ~ p { display: none; }
}

8   Discussion

There are several design elements which can be seen in relation to the navbar: large buttons and code segments. The styles conceptualised here are defined in such a way, that the resulting navbars harmonise in design with these other elements. Thus, the radius of the outer corner rounding has been chosen identically as for the large buttons. The shade of grey of the navigation bars has been chosen in such a way, that the weight of the navigation bars is neither too large nor to small; this results in a grey different from the one used for code segments. The horizontal distance between the frames of the navbar sections and the edges of the navbar itself has been adjusted such that the result resembles the horizontal distances in the large buttons; the vertical distance is independent of these and has been set slightly smaller. An equalisation of the roundings of code segments and of navbars has been dispensed of, so that the sharp corners of the code segments remain unaltered.

Picking out graphically the sections of the navigation bar from the the navigation bar background emphasises that the elements of the section belong together. Experience shows that for footers such an emphasis is not needed.

In case of multi-lined sections the sections of the navbar are broader than the wrapped content. The readability is optimum with text-align: left, this is here especially superior to the text-align: justify alternative.


Released 29 January 2025.

← Previous Version | Next Version → | Latest Version