Page MenuHomeFreeBSD

Build offline documentation using Hugo

Authored by carlavilla on Sep 13 2021, 7:11 AM.


Group Reviewers

Problems solved:

  • Allow to build the documentation using Hugo
  • Fix link problems
  • Remove SVN entities
  • Fix lang problems to help weblate
  • Move all the AsciiDoctor translations to the shared folder to help weblate
  • Allow the possibility to build each document. For example each document can be edited in and watched the result in real time in VS Code or Vim/NeoVim
Test Plan

To build the documentation for offline use
make clean
make html

To export the documentation to pdf
make clean
make pdf

Diff Detail

R9 FreeBSD doc repository
Lint Skipped
Unit Tests Skipped

Event Timeline

carlavilla created this revision.

Upgrade the diff.
Check only the english result.
I need to make the same changes in the other languages in the books.

Hi @carlavilla... Could you check the patch?, I think it's missing some files.

$ cd documentation
$ make clean
$ make or make html

hugo v0.87.0-B0C541E4+extended freebsd/amd64 BuildDate=2021-08-09T19:54:48Z+0000 VendorInfo=freebsd
INFO 2021/09/22 19:47:53 syncing static files to /git/doc/documentation/public/
Error: Error building site: "/git/doc/documentation/content/en/articles/bsdl-gpl/_index.adoc:26:17": failed to extract shortcode: template for shortcode "lang" not found
Total in 142 ms
*** Error code 255

Sorry, I forgot to add the untracked files. My fault.

Hi @carlavilla .

I'm not seeing the other changes, I'll focus on the offline HTML on English documents.
But I really liked the {{% lang %}, shared/asciidoctor.adoc and shared/attributes/ approach. =)


The indexes files are not usable because of the references to localhost/en/:


It's a minor, IMHO they can be removed from the offline HTML.


About the split books. en/books/handbook/, you removed the single page/split page links, but the single page version is still there en/books/handbook/book/.

I think it's better to use just the single-page version for offline HTML because browsing offline loses usability. When you link to an index page from any chapter, for instance, you will see many folders and need to find the index file.

Anyway, when packaging (.tar.gz) each document, it will be better to use just the single-page, when there is one for that document.


When updating this review or another, please include full context in the diff. [1]

And thanks again for your work. =)

1 -

I still need to check the pdf generation. And make some changes in the links.

This is what is resolved right now:

  1. Hard-coded language on Includes [1]
  2. The offline documentation can be generated using Hugo [2]
  3. Hardcoded links also removed. Right now for the offline documentation relative links would be used [3]
  4. For this point [4], we need to handle this with the script


@dbaio, I can't upload the diff using -U99999 because the diff it's to big. If you want the complete diff I can share it with you by email

I'll try to solve tomorrow the remaining things. But right now it's in a good shape :) Sorry for the delay, it was a long task with a *lot* of changes. With this commit we solve a lot of points.

I forgot to say that right now every document can be compiled in an independent way saving a lot of time.

I forgot to say that right now every document can be compiled in an independent way saving a lot of time.

with Hugo?

Hi Sergio.

Thank you for your hard work on that. =)

I checked a few documents locally and hosting them on my local network, and it looks very nice.


It's missing some includes of teams.adoc, I noticed on articles/committers-guide/ and books/fdp-primer.

An additional feature will be to remove all indexes after the build (indexes that are not necessary for offline usage):


I can help with that.

And I can help with the offline assets and as well.

And thanks again Sergio.

In the following days, I'll check all documents more carefully. =)

I only need to fix some problems with the pdf's and add some teams.adoc[] includes

I only need to rebase with the last doc tree and it will be ready.
@dbaio you can take a look when you're ready

carlavilla edited the summary of this revision. (Show Details)
carlavilla edited the test plan for this revision. (Show Details)

Updated to the last revision of the tree

These are just some details.

  • I'm seeing issues with images on all books/, take a look at dev-model for instance.

For the record:

  • When building the HTML Offline version, we need to remove the indexes files, later...
  • Other points I commented on code.

And thanks for your work.


Please, add --verbose here.


We need to include attributes when building html5 as well.

include::shared/attributes/attributes-{{% lang %}}.adoc[]

Update this script with this version:


With the current path, when building PDF, all images are not found.

The earlier version was using

:imagesdir: ../../../../static/images/{images-path}

Did you change it because of another issue?

carlavilla marked 2 inline comments as done.

Fixed the problems.

I only need to add a post clean to remove some index files.
@dbaio try it please and let me know :)

Minor point: Fix asciidoctor-pdf requirement.

I tested:

  • Online Documentation
$ make
  • Offline Documentation
$ make html

Local Includes ok; Images ok;
Just the indexes files we need to remove later.

  • PDF Documentation
$ make pdf

Images ok

ps. I didn't check every document, just a few of them in each language.

But this looks good to me.

Thanks Sergio.


Remove this on RUN_DEPENDS.
If brings an old issue:

We still can have the requirements-pdf target here.:

-pdf-books: generate-books-toc
+pdf-books: requirements-pdf generate-books-toc
+pdf-articles: requirements-pdf

Please, restore this.

Fix last remaining things in the Makefile.
Also add a task to remove the index files

I did more tests, and it looks good.

  • Online Documentation
  • Offline Documentation
  • PDF

Thanks for your work!

This revision is now accepted and ready to land.Nov 2 2021, 8:38 PM