Migration of our website and documentation is completed

Sergio Carlavilla carlavilla at freebsd.org
Mon Jan 25 23:54:01 UTC 2021

Dear FreeBSD users,

The doc repository now completed Hugo/AsciiDoctor migration. Well, at least it
completed the 1st phase of the migration. Now the doc repository is
using Hugo/AsciiDoctor tech.

You're gonna notice some differences:

- The first change it's the structure of the repository. Right now we
have three folders in the root directory:
-- documentation: this folder contains our documentation
-- shared: this folder contains shared resource between the
documentation and the website
-- website: this folder contains our website

If you want to get more information about the Hugo structure, please
take a look here.[1]

- The second change is the tech used to generate the website and the
documentation. We're going to have two new friends here, one of them
it's Hugo[2] and the other new friend it's AsciiDoctor[3]. As Hugo
says in their home page. Hugo is "The world’s fastest framework for
building websites". And AsciiDoctor is going to allow you to make
changes in an easy way.

- The third change it's the location of the documentation. It's moved
to docs.FreeBSD.org Why this change? This would allow us to build an
entirely new documentation portal. This change can be the seed to
build a reference portal to cover all the documentation of our beloved
FreeBSD. For example, as Microsoft does in [4]

We are currently updating the FreeBSD Documentation Project Primer to
reflect all the new changes. The best place to check the differences
between Docbook and AsciiDoctor is the rosetta stone [5]. Also, the
documentation for Hugo and AsciiDoctor is great, you can take a look
here [6] and here [7].

Besides all this, I still have to update some i18n files and some
chapters of the documentation in Japanese and Portuguese. If you plan
to touch any of those documents, please let me know first so as not to
duplicate the work. When everything is synchronized I will send
another notice. Apart from the handbook in Japanese and some
documentation in Portuguese, feel free to update the documentation.
You can check the TODO list here[8].

There are also two backup sites to check if we left something in the

Happy hacking, please let the Doc WG know if you have any issue and
suggestion. Also, keeping FreeBSD the best document is everyone's

This is not the end of the path. It's only the beginning. The doc/
repo is open again!

Benedict Reuschling <bcr@>
Glen Barber <gjb@>
Hiroki Sato <hrs@>
Li-Wen Hsu <lwhsu@>
Sean Chittenden <seanc@>
The FreeBSD Foundation

Sergio Carlavilla.

[1] https://gohugo.io/getting-started/directory-structure/
[2] https://gohugo.io/
[3] https://asciidoctor.org/
[4] https://docs.microsoft.com/en-us/
[5] https://docs.freebsd.org/en/books/fdp-primer/#rosetta
[6] https://gohugo.io/documentation/
[7] https://docs.asciidoctor.org/home/
[8] https://github.com/sergio-carlavilla/doc-todo/blob/main/README.md
[9] https://www-legacy.freebsd.org/
[10] https://docs-legacy.freebsd.org/

More information about the freebsd-translators mailing list