You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Why HUGO?
The contemplated alternative is Jeckyll, which comes with a better integration with github.
At this point, the choice is: "going full github, tick all the boxes" vs "using a widespread alterative, with more control over the published content".
Why hugo-book?
After some time researching and experimenting various templates, this one was standing out (IMHO)
as the one with easiest configuration and closest rendering to what I wanted (with an overall organization
similar to the one produced by gitbook). It worked almost out of the box, with little customization that I could
add later on (e.g. tabs, collapsible sections, etc).
Lately I've also tried "docsy" (a rich template by google/netlify), but I found it a bit complex.
It also came with strong opinions about how to document a project. Although these ideas are good,
they needed an even deeper restructuing of our markdown material.
markdown content now use "frontmatter" headers
Tried to add minimal frontmatter, with maximum reliance on the theme.
doc layout changed to accomodate how hugo builds a site hierarchy
used a few "shortcodes" from the theme for a more compelling UI (e.g. tabs, collapsible sections, ...)
link to edit the page (creates a new PR with the page)
Problem statement
Our documentation site, https://goswagger.io is powered by the venerable
gitbook
.Here are a few impediments with go-swagger documententation:
Proposal
I've been working on a prototype to produce a revamped documentation site.
You may see it in action on my active fork (still some rough edges, as there is some WIP on content): https://fredbi.github.io/go-swagger/
What's on the table?
doc layout changed to accomodate how hugo builds a site hierarchy
used a few "shortcodes" from the theme for a more compelling UI (e.g. tabs, collapsible sections, ...)
link to edit the page (creates a new PR with the page)
doc site built from github actions at every push to master (see https://github.com/fredbi/go-swagger/blob/master/.github/workflows/update-doc.yaml)
github pages are deployed using the "gh-pages" artifact.
What's still missing?
There is still quite some work ahead, though.
@casualjim @youyuanwu how about that?
The text was updated successfully, but these errors were encountered: