Re: FreeBSD Documentation Portal status and review request

On Sun, Nov 21, 2021 at 5:31 PM Sergio Carlavilla
<carlavilla@freebsd.org> wrote:
>
> Dear FreeBSD community,
>
> A couple of months ago we added information about the new FreeBSD
> Documentation Portal to the quarterly reports[1].
>
> Well, at this time there's some things that need to be accomplished in the new
> Documentation Portal. 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]. I
> used my personal
> VPS to deploy the documentation portal temporarily to show to the
> community since I have problems with Gitlab and Docker. I didn't add
> all the languages because the bandwidth and the disk size is very
> limited. I have the cheapest VPS in Digital Ocean hehe.
>
> To summarize the changes you are going to find:
>
> - Completely new responsive design. Tested in FreeBSD and all other major OS.
> - Removed Python from the dependencies.
> - Removed the list of figures, tables and examples.
> Do you think these lists are useful? In this case I'll restore it
> using the AsciiDoctor API instead of Python.
>
> This change will not be as traumatic as the previous one, it will not
> be necessary
> to freeze the repository or change the technology used to build the
> documentation.
> The existing theme will "just" be modified.
>
> Please let me know your thoughts about this :)
> I'm gonna send this message to the documentation and translators list
> to reach more people.

I like it very much. Thanks for working on this!

A few details:

The "community" link seems broken. It points to
https://carlavilla.es/en/communit

Font size at the fourth level of the titles seems a bit small to me.
See the size difference between:

3.2.2. Maintainer responsibilities

and

3.2.2.1. Keep your ports up to date ---> This looks a bit small

in https://carlavilla.es/en/articles/contributing/

Can this be configured or do we rely on changing the font size in the browser?

My last question is about Algolia. I'm not familiar with it. Why do we
plan to use it? What does it provide that Google or Duck Duck Go do
not?

Thanks!
>
> The next steps will be:
>
> - Finish the dark theme (1 more week)
> - Implement Algolia to use it for local searches (1 more week)
> - Use mandoc to generate the manual pages
> - Redesign the ports page
> - Redesign of the FreeBSD main website
>
> Bye!
>
> [1] https://www.freebsd.org/status/report-2021-07-2021-09/#_freebsd_website_revamp_webapps_working_group
> [2] https://www.algolia.com
> [3] https://gohugo.io/
> [4] https://docs.asciidoctor.org/home/
> [5] https://www.algolia.com/for-open-source/
> [6] https://carlavilla.es
>