move away from GitBook for default rendering

[afeld]

It appears that GitBook has moved to a SaaS model:

We have moved away from the static site generator model ... you can no longer host a GitBook generated documentation yourself.

https://docs.gitbook.com/v2-changes/important-differences#cli-toolchain

This is therefore not a great default option for OpenControl content rendering. Seems that a static site generator might be preferable. Options:

Tool	Pros	Cons
Jekyll	Flexible; works on GitHub Pages; proofs of concept exist	Requires Ruby, though this could possibly be worked around
Hugo	Easy to install on different operating systems; super fast	Less widely used; doesn't work on GitHub Pages
hyperGRC	Provides a nice UI	Requires Python/Docker
Gatsby	Very flexible input format	(Still) requires Node.js

[mogul]

*Gatsby* may be useful in that it can more effectively make use of structured data. This would make the renderer simple and make the templates easier to maintain/extend.

…

On Tue, Jun 4, 2019 at 9:43 PM Aidan Feldman ***@***.***> wrote: It appears that GitBook has moved to a SaaS model: We have moved away from the static site generator model ... you can no longer host a GitBook generated documentation yourself. https://docs.gitbook.com/v2-changes/important-differences#cli-toolchain This is therefore not a great default option for OpenControl content rendering. Seems that a static site generator might be preferable. Options: Tool Pros Cons *Jekyll* Flexible; works on GitHub Pages; proofs of concept exist <#221> Requires Ruby, though this could possibly be worked around <https://phusion.github.io/traveling-ruby/> *Hugo* Easy to install on different operating systems; super fast Less widely used; doesn't work on GitHub Pages — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#346?email_source=notifications&email_token=AAALVESTNLFEXK5HUABQYUDPY475TA5CNFSM4HTO6KYKYY3PNVWWK3TUL52HS4DFUVEXG43VMWVGG33NNVSW45C7NFSM4GXVXXHA>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAALVEXTX7OOXAO4LJZ7RR3PY475TANCNFSM4HTO6KYA> .

[biggsean]

@mogul you can do that with hugo as well...

@afeld I agree, but you can still use the old gitbook-cli for the time being... the relevant parts of my dockerfile:

# Install gitbook
ARG NODE_VERSION=v6.3.0
ARG NODE=node-$NODE_VERSION-linux-x64
ARG GITBOOK_VERSION=2.6.7
ENV PATH=/usr/local/lib/nodejs/$NODE/bin:$PATH
RUN yum install -y tar xz && \
    mkdir -p /usr/local/lib/nodejs && \
    curl https://nodejs.org/dist/$NODE_VERSION/$NODE.tar.xz | \
      tar xJvf - -C /usr/local/lib/nodejs && \
    npm install -g gitbook-cli && \
    gitbook fetch $GITBOOK_VERSION

[aegershman]

If it means anything, hugo does indeed work with github pages, e.g. can produce compiled output into a folder, like /docs or whatever the case may be, and github pages will render it. It's gotten better with time.

In any case, it'd be nice to continue the current practice of having a default compiled output, to help prevent too much quibbling and fiddling with zillions of configuration options. Even though it's pretty outdated at this point, I do love the simple and clean aesthetics of gitbooks. Not saying it couldn't be extended, but it is nice to have an opinionated standardized default which covers both human readability (github pages) and can generate content which is portable for auditors (e.g. being able to produce a pdf output)