feat(#1554): change theme from Docsy to Hextra

[andrablaj]

Description

Closes #1554
Additionally, closes #900

Per last year's research, the Hextra theme was recommended by UX colleagues and technical writers as a modern alternative to Docsy. This PR migrates the docs site from Docsy to Hextra.

Issues to resolve after going live

• subtitles not shown on some pages. For example, on every specific version's release see new vs old . Also see "Reference Apps" new vs old. Sections fixed:
  • Reference Apps
  • Technical Overview
  • Design
  • Host
  • Community.
  • Build
  • Releases
• Related content was removed. We should review the need and use of a "Related content" functionality as that is quite messy on the current docs site.
• building / training page has the {{< subpages >}} but is only showing one page instead of four. see new and old
• onboarding page has a very large screenshot that would be nice if it was smaller (eg in <card>). see new and old
• style guide tabular schedules table isn't rendering with pretty circles - has X instead. see new and old
• "Multi vs Single node couchdb requirements" comparison table - isn't showing on new site - maybe this intentional given Diana's recent research? see new and old
  * This was moved to the considerations page under the same section see new page
• old 0.4.15 doesn't redirect to new one. see new and old - should go to here - need to add alias
• old 4.0.0 page doesn't redirect to new one. see new and old, should redirect to here - need to add alias
• new 4.2 page could use a little image formattting see new and old
• old 4.7 page doesn't redirect to new. see new and old should redirect to here - need to add alias
• old 4.7.1 page doesn't redirect to new. see new and old should redirect to here - need to add alias
• headers should be displayed in bold font
• Some pages has huge images that would be nice if it was smaller. For example, manually testing on the device (old good size vs new big image; downloading and launching old vs new
• Some images completely changed their size example on the desktop view of contact
• Features page in new site doesn't have the topic as in the old page.
• same as above for Quick guides for implementers new is empty vs old has the index topics
• images are not loading on filtering targets aggregates new page. See old.

Issues to resolve before going live

• images aren't loading on 3.10 page see new vs old
• images aren't loading on 3.11 page see new and old
• left hand nav word wraps in chrome on deeply nested nav. see comment 1 and comment 2
• release note images not show (all pages with images). see new vs old
• tabular layout we created for ANC reference app is broken. Old working page, new not working page. This is dependent on some hugo templates Marc and I worked on way back when.
• diagram on PIH Malawi not rendering correctly. same as ANC above. see new and old
• list of logos should be table see old vs new
• main core architecture diagram is showing as a "Data Flows" link instead of an image on the page. see old and new
• watchdog architecture diagram is showing as a "Data Flows" link instead of an image on the page. see old and new
• Data Flows for Analytics diagram is showing as a "Data Flows" link instead of an image on the page. see old and new
• we may opt to not fix, but wide tables like on the release pages are cut off, so you need to horizontally scroll. This is because there's a max width of the page where as the old site the right hand column content is flush right and the center is stretchy. Make your browser wide and see new page and old page
• release sub nave shows "0.x" and "2.10.0" etc. where this is not visible on the old site. see new and old
• Release pages are broken. All the links redirect to 2.10.0, 3.0.0 and 4.0.0
• image on CHW not showing. see new and old
• image on supervisor not showing. see new and old
• image on reg manager not showing. see new and old
• image on nurse not showing. see new and old
• image on data mngr not showing. see new and old
• swatches of color not showing in tables. see new and old
• icon images render always as a two icons per row, as opposed to 5 (based on my current browser width). On the old site if the browser is very narrow it will only show 2 per row. Maybe ok as is? If I set CSS from 1480 to 1980 feels more comfy to me overall. see new and old

  .hx-max-w-screen-xl {
    max-width: 1980px;
  }

• images on UI Kit don't show. see new and old
• images on best practices don't show. see new and old
• images on local-setup don't show. see new and old
• images as profiles are different sizes, instead of the same size. show as each being on their own line, instead of all for being on the same line. images in general are very different (bigger, not right aligned) on this page - maybe some of these are OK? see new and old
• mermaid charts on vert vs horz scaling are clipping the text see new vs old
• README needs updates from Docsy to Hextra
• Documentation coding style sanity check

Pages to check by group

Please put your name next to each section you plan on checking. do a side by side comparison with the live site and the hextra site:

group 1 (Lorena)

new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old

group 2 (Lorena is working on this)

new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old

group 3 - mrjones

new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old

group 4 - mrjones

new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old

group 5 - mrjones

new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old

group 6 - mrjones

new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old

there is no spoon (aka no group 7) - mjones is not above claiming no work is work he did \o/

quux

group 8 - mrjones

new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old

group 9 - mrjones

new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old

group 10 - mrjones

new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old

group 11 - mrjones

new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old

group 12 - mrjones

new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old
new vs old

New features implemented

• cards to achieve multi column layouts - also see examples site for more ideas!:

  {{< cards rows="4" >}}
  {{< card link="tasks-care1.png" image="tasks-care1.png"  method="resize">}}
  {{< card link="tasks-care2.png" image="tasks-care2.png"  method="resize">}}
  {{< card link="tasks-care3.png" image="tasks-care3.png"  method="resize">}}
  {{< card link="tasks-care4.png" image="tasks-care4.png"  method="resize">}}
  {{< /cards >}}

• new subpages shortcode as a list of subpages is not automatically shown on _index.md pages:

  {{< subpages >}}

• see list of comparison of new and old below

Changes (WIP)

The theme change needed the following updates:

• Upgrade Hugo to 0.146.0
• Replace pageInfo with GitHub style alerts
• Replace alert with GitHub style alerts
• Replace tabpane shortcodes with tabs (docs)
• Remove Feedback at the bottom of the pages
• Remove "Create cht-core issue"
• Added CHT logo on the homepage with light/dark mode alternatives
• Changed favicon to CHT logo
• Use Noto Sans font
• Use CHT colors for underlined text and sidebar
• Move "Create cht-docs issue" to the left pane
• Remove package.json & all node related code.
• Remove unused scripts and images
• Removed "Related content" as it doesn't work with Hextra.
• Move the privacy policy from footer to the left pane.

How many readers clicked on "Feedback" during the last year: 62 users, 75 clicks, some months none at all. see graph for details

License

The software is provided under AGPL-3.0. Contributions to this project are accepted under the same license.

[andrablaj]

Kindly deployed by @mrjones-plip on https://hextra-docs.dev.medicmobile.org/ - it updates automatically every 30 min or we can manually refresh.

[andrablaj]

This is ready for a first round of review on https://hextra-docs.dev.medicmobile.org/.

Current changes:

• Upgrade Hugo to 0.146.0

• Replace pageInfo with GitHub style alerts

  • Old vs new
  • Old vs new with warning style

• Replace alert with GitHub style alerts

  • Old alert vs new alert

• Replace tabpane shortcodes with tabs (docs)

  • Old tabbed vs new tabbed

• Remove Feedback at the bottom of the pages. Old style (at the bottom of every page):

  

• Remove "Create cht-core issue". Old style:

  

• Move "Create cht-docs issue" to the left pane

  • Old:

  

  • New:

  

• Move the privacy policy from footer to the left pane.

  • Old:
    
  • New:
    

• On the homepage, I added a few callout items for the demo purpose.
  

What's different:

• ⚠️ The search functionality is different: it searches the documentation site, and not Google/Forum/Documentation as Docsy did. We might be able to replicate this search functionality with Hextra, but that will require extra research.
• There are no sub-pages table of contents on section _index.md
  • Old vs new
• There are no description under page titles
  • Old vs new
• We don't show the last commit info on every page; we only show the Last updated date
  • Old vs new

Additionally, if we were to move forward with this theme, we would need to update READMEs and remove unused Hugo configurations.

[mrjones-plip]

Nice work on this Andra!

I think given the large scope of the changes it's working linking to before and after examples of each change so folks can more easily appreciate the differences. While some work to curate the list, it will make it easier for a larger audience to do a more targeted review of the changes.

For example the app developer page has an instance of the old tabbed content style and new tabbed content style.

maybe just edit your comment above to have the examples?

[andrablaj]

@mrjones-plip excellent suggestion, thank you! I updated the comment above with links and screenshots. Please let me know if you need extra information or details.

[mrjones-plip]

I note that the tabular layout we created for ANC reference app is broken. Old working page, new not working page. This is dependent on some hugo templates Marc and I worked on way back when.

[andrablaj]

The gallery on this page seems broken. It might be related to existing custom layouts.

[mrjones-plip]

Add a check list so we can more easily track what needs to be fixed before going live.

[mrjones-plip]

I went from top to bottom of the navigation and got as far as " Building -> Contact Mangmt -> Contacts". I added a bunch of to dos! I wonder if the images not being included could be solved with one giant search and replace?

[mrjones-plip]

@andrablaj - what about crowd sourcing some of the fixes and adding a Good First Issue label and then asking folks to open PRs to fix broken issues per the growing list? They could open PRs against this branch so they'd be pushed up to the site.

also - ok for me to merge main into this branch so it has the recent Releases move?

[andrablaj]

@mrjones-plip and @lorerod thank you for comparing old and new docs sites.

As all the "must have" items were fixed, I suggest we mark this PR ready for review. What would be a good review strategy, considering all the work we've already done together?

[mrjones-plip]

Hey @lorerod @andrablaj @antonykhaemba and @dianabarsan - wanna ship this!!? We'll file issues for remaining fixes and go from there!

[mrjones-plip]

oh no! I'm sorry I missed your earlier comment @andrablaj 😅

If we all agree this is good to go, I say we call out on #development, cross post to #app-serv, and say we're going to go live on Monday 5th if no one has any concerns.

[lorerod]

Hey @lorerod @andrablaj @antonykhaemba and @dianabarsan - wanna ship this!!? We'll file issues for remaining fixes and go from there!

Hi @mrjones-plip, @andrablaj, I'm okay with shipping this, but I couldn't finish with the pages I was willing to compare. If I can continue comparing after this is live, it will be fine. What I have seen so far are image distributions and sizes that don't look right. But I already added the issue to the list of "fix for later."

[andrablaj]

@mrjones-plip I love your plan! I don't have time to do this today, but if you are available to send that message yourself today, that would be wonderful.

Additionally, I suggest we create a CHT Docs v1 release to capture the Docsy era just before we merge.

[mrjones-plip]

yeah - sounds good @andrablaj ! by my EOD I'll

• make Slack posts
• tag v 1.0 in docs
• stand up old-docs.dev.medicmobile.org in place of hextra site so folks can easily compare old to new after we go live

[andrablaj]

Sounds good @mrjones-plip, thank you! To be clear, does this mean we will need to create a tag for the new PRs that are merged before going live with the new theme?

[mrjones-plip]

ah - we can make the v1.0 tag right before we merge hextra to avoid needing to cherry pick. good thinking!

[mrjones-plip]

archive of the current docs site is live! it is not auto updating and there's no CD or anything. there's a ticket covering how it was done.

when we're done with the hextra work , I'll decommission hextra-docs.dev.medicmobile.org