Docs.folio.org technical information

Docs.folio.org is built using Hugo, an open source static site generator. The theme used for the Hugo site is an open source theme called Docsy.  Much adaptation was done to the theme for branding purposes and to improve usability.

The source documentation is in a Github  repository: https://github.com/folio-org/docs

Spring 2023 - Investigating possible new themes for site

Requirements:

1. Open source / actively maintained
2. Allow end users to submit feedback on pages
3. Allow content creators/updaters to submit edits from the content (using Github PRs or other tools to be defined)
4. Full mobile support - all site features available on desktop should be available on mobile
5. Integration with a strong search engine tool (whatever that might be)
6. Support for multiple languages
7. Make it easier to navigate the content of a page. The TOC is hard to read, e.g. https://morning-glory.docs.folio.org/docs/erm/agreements/ 

Nice to have

1. Flowchart support with a tool like Mermaid

---

Current theme is Docsy - https://www.docsy.dev/

• Open Source: Apache License 2.0
• Actively maintained: Releases, Contributions
• Allows end user to submit feedback on pages
• Allows content creators/updaters to submit edits from the content using Github Repository Links, for example "Edit this page" opening a PR.
• Full mobile support – all site features available on desktop are available on mobile. Docsy supports this out of the box. Some time ago some FOLIO customization broke it but it got fixed.
• Algolia search engine
• Support for multiple languages, example for English + German: Preview (note the Deutsch/English language switcher), GitHub Branch
• Makes it easy to navigate the content of a page because the TOC (displayed at the right side) only displays level 2 (##) and level 3 (###) headings. Level 4, 5 and 6 headings are excluded from the TOC, eg. http://ssbp-foliodocs-docsbranch-agreements-toc.docs.folio.org.s3-website-us-east-1.amazonaws.com/docs/erm/agreements/
• Flowchart support with Mermaid

Other themes that Erin liked:

• Learn - https://learn.netlify.app/en/
  • Open source / MIT licensed - https://github.com/matcornic/hugo-theme-learn
  • end users can open PRs to submit updates. unsure if a comment / form submission function exists.
  • Looks like full mobile support - nothing appears to be unresponsive
  • Can support mermaid
  • Compatible with "Hugo multilingual mode", not sure what that is
  • Supports lunr.js javascript search engine, not sure about other options
  • Collapsible ToC possible (see demo site)
• Shadocs - https://shadocs.netlify.app/
• Doks - https://doks.netlify.app/docs/prologue/introduction/
• MKDocs - https://www.mkdocs.org/

My impression is that Docusaurus is popular, but it's not based on Hugo -  https://docusaurus.io/ - built in React - this is what is behind the OpenRefine docs, for example (https://openrefine.org/docs)

• https://github.com/facebook/docusaurus
  • Open source, actively maintained - MIT license

Not open source - 

• Dot - https://demo.gethugothemes.com/dot/
  • Not free, but not super expensive - $80 - https://gethugothemes.com/products/dot, might have to purchase additional licenses for additional sites (e.g., if we wanted to spin up another docs site for another purpose, probably require a second license)