Consider removing bullet lists from section overview diagrams #520
Description
As detailed in comment below, we should consider if we actually want to include a bullet list in the section overviews. It is not displayed terribly well at the moment, but it is legible, so I don't think this is a hard fault, but it is probably worth the consideration. I think we should also have a go at "highlighting" the current section in the flow diagram, since that would at least add some value to having this at the top of each section; otherwise, it is the same diagram for each if we remove the bullet points!
Thanks @bielsnohr for having a go with the Markdown list formatting and also investigating the alt / accDescr behaviour.
Annoyingly it seems that the Mermaid Markdown support is only for inline level formatting such as bold / italic not any block elements like lists, and further that in current Mermaid renderer versions setting the text alignment of labels using a style directive like style nodeid text-align:left has no effect. Looking at the SVG / HTML produced with a style directive added, while the style information does get correctly applied to the outer node element and inner span containing the label, it has no effect on the span element as this text-align only works for block display elements like divs, and the span element is nested inside a div for which text-align is fixed to center. From a previous StackOverflow question / answer on this issue it seems this wasn't always the case.
It seems like there is still some benefit to wrapping the labels in "`...`" as from the Mermaid documentation it seems like this should preserve any newlines in label text without needing to manually include <br> tags. Unfortunately it seems that common whitespace at the beginning of lines (for example from indenting diagram syntax) is not stripped and effect the rendered output. I have suggested changing the remaining section overview Mermaid diagrams to use Markdown labels for the bulleted lists and reduced the whitespace at the beginning of the list items to a single indent level, as this makes them display slightly more nicely on Mermaid Live and GitHub preview for me. We could also remove all indentation from the list items but then this makes the diagram syntax difficult to read.
Possibly given issues with formatting long text segments in Mermaid diagrams we might want to revisit whether to continue to have the detailed section breakdowns in the overviews in Mermaid rather than as a separate bulleted list, but I think this is probably better dealt with in another issue / PR.
Originally posted by @matt-graham in #513 (review)