Blox Project Table of Contents | Overview of all Projects
Inhaltsverzeichnis des Blox-Projektes | Übersicht aller Projekte
Downloads of the Blox Project | Downloads of the entire Site | Imprint
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.
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.
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:
(2.) is grounded on the following observations:
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
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.
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.
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:
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.
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:
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.
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.
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; } }
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