hugo migration notes (16 apr 2018).md

Hugo transition notes 16 Apr 2018

BEP - Bjørn's effort

• branch: hugo-migration

• example site at 'https://k8sio-hugo-migration.netlify.com/'

• glossary moved into a "page bundle" structure in hugo

  • when you start to translate, it makes a sort of overlay so that what's not translated reflects whatever the base content/language was provided

• the "capture" thing for setting up template pages was a bit tricky, but functional now as shortcodes. BEP indicated there might be some upstream revisions to make this process a bit more sane.

• two issues to speak about

  • 'content/en/docs/tutorials/stateless-applications'
  • tutorials - guestbook now appears as a standalone set with mostly just random YAMl files in it, hasn't translated easily
  • in several places - content page, and subfolder with example files/resources
  • BEP would recommend an alternative setup - make a directory and include content within it as 'index.md' and reference the resources directly from there. Use this as a consistent grouping-of-all-resources together
    • add a new tutorial, make it self-contained
    • this can make it lot more sane to translate as well
    • translated content in another language can reference the same resource files (yaml, etc)
  • this is the "bundle" concept in Hugo
    • content relative links for free, easier translation
    • very useful for the blog section, where images are frequently referenced from a content page
    • side effect is that resource files are not immediately visible/accessible from the internet (maybe desired? overlaps with the kubectl -f https://kubernetes.io/... problem space we're hitting)

• toc_hide: true/false - in front-matter toggles wether or not the content will show up in the table of contents

  • "title" and "weight", "content_template", "reviewers" are other pieces in the front-matter
    • weight is shifting the sort order so that elements appear in different locations in a ToC field. Default sorting is by date/name - weight will shift it. If weight it set, it will be used to sort the content in the ToC

• basic pieces are up and operational, list that BEP is working through

  • still oriented on programmatic translation of the site, mostly translation to shortcodes
  • some TOC translation elements still need refinement - it's making some incorrect structures at the moment

• Jennifer: title is repeated in title bar and content

  • BEP in hugo, all content has two titles - title and link_title
  • link_title is for ToC display, title is within the content directly
  • some of what Jennifer is seeing right now are bug artifacts

• generated markdown content isn't getting an in-article ToC generated quite correctly right now

• hugo uses a different "highlighter" - uses Chroma (port of Pygments)

  • style is pluggable, and didn't match the specific styles we had previously
  • (maybe go looking through and picking one in the future)
  • can be set in Hugo configuration - currently at "emacs"

• whole site (800 pages en, 250 pages cn) building in ~3 seconds on BEP's laptop

• short codes

  • /layouts/shortcodes
    • impl capture, code, deprecationwarning, glossary_tooltip, and note
    • stored in layout page bundle for fast access
    • examples read from file and read from bundle, so can work either way

• script to convert callouts that style in the blog section, style markers are "after" the content, proving more difficult to translate

  • working on a script to translate that to Hugo reasonably
  • callouts will change to "shortcodes" in Hugo - will wrap content, rather than annotate immediately after it.
  • blog is using some interesting/unusual callouts ('.big-img' being the example)