Page MenuHomeFreeBSD

Build offline documentation using Hugo
Needs ReviewPublic

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

Details

Reviewers
dbaio
blackend
Group Reviewers
doceng
Summary

Building offline documentation using Hugo.
It's still in progress, I need to fix some minor things. But we can start the review.

With this approach we can use any format that Hugo supports like MarkDown.
The problem with the CSS and the fonts it's solved.

Test Plan

make clean
make html

Diff Detail

Repository
R9 FreeBSD doc repository
Lint
Lint Skipped
Unit
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/:

index.html
en/index.html
en/articles/index.html
en/books/index.html

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 - https://wiki.freebsd.org/Phabricator#Create_a_Revision_via_Web_Interface