Page MenuHomeFreeBSD

Build offline documentation using Hugo
Needs ReviewPublic

Authored by carlavilla on Sep 13 2021, 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

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 asciidoctor.sh script

[1] https://people.freebsd.org/~dbaio/doc/FreeBSD_Documentation.html#_hard_coded_language_on_includes
[2] https://people.freebsd.org/~dbaio/doc/FreeBSD_Documentation.html#_building_html_with_hugo_online_docs_and_asciidoctor_standalone_offline_docs
[3] https://people.freebsd.org/~dbaio/doc/FreeBSD_Documentation.html#_hard_coded_links
[4] https://people.freebsd.org/~dbaio/doc/FreeBSD_Documentation.html#_offline_documentation_outdated_ftpdoc

@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.

Minors:

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):

public/index.html
public/en/index.html
public/en/articles/index.html
public/en/books/index.html
...
public/pt-br/index.html
public/pt-br/articles/index.html
public/pt-br/books/index.html

I can help with that.

And I can help with the offline assets and asciidoctor.sh 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