Re: FreeBSD Documentation Portal status and review request

From: Rocky Hotas <>
Date: Mon, 22 Nov 2021 22:16:05 UTC
On nov 21 17:31, Sergio Carlavilla wrote:


> For example a local search using Algolia[2] as Hugo[3] or
> AsciiDoctor[4] does. Algolia provides a free version for Open Source
> projects[5].
> And the dark theme.
> Apart from that, you can see the new Documentation Portal here[6].

First, thank you for the updates and for this huge work.

I do not know very much the above tools, so I can only give a personal
opinion about the appearance of Documentation Portal. This is of
course very subjective.

- The beginning page is very clear and the whole space looks well
  organized with the rectangles: all the available items are clearly and
  quickly recognizable.
- The contents pages are amazing! The actual text width is less than the
  current version and this improves readability.
- A dark theme would be very useful (and also very cool!).
- The font for titles of chapters and sections is too much bold.
  Lower level subsections, like `14.2.1. Preventing Logins', are instead
- The whole page uses sans-serif fonts, except for the `Note', `Warning'
  and similar panels. This seems mismatched. Why not to use a sans-serif
  font also there?
- There is a very high contrast with the background when using the
  black-filled circles with numbers in a code block. Maybe replace black
  with a different color?
- In the side panels, the vertical spacing between lines is excessive,
  in particular inside the same group (the lines with the sections of a
  chapter, for example).
- In the main text, the font size could be just a little bit smaller (1
  pt or even 0.5 pt), or tunable by the user. The horizontal spacing
  of the font sometimes looks excessive: too empty space between letters
  or words.
- The `Download PDF' and `Edit this page' links currently are not
- The typewriter font used in-line and also in the emulated black screen
  rectangles is too little in comparison to the main text font.

The overall result is, however, already very pleasing and comfortable.
So, congratulations :)!